@keystrokehq/skills 0.0.2 → 0.0.3

package/keystroke-credential-binding/SKILL.md

@@ -95,7 +95,7 @@ Teach these rules:
 
 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
+- `credentialDefinitionId` 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`.
@@ -118,14 +118,14 @@ This matters for integration authors and when explaining `createOperationFactory
 - 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.
+- The drawer-label rule is enforced at three layers today: compile-time on a single primitive (`AssertUniqueCredentialSetIds`), build-time across the project (`assertUniqueCredentialDefinitionIds`), 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.
+The credentials stored for "acme-crm" were uploaded against a different schema than the workflow currently expects.
 
   Uploaded at:    2026-01-15T12:34:56.000Z
   Uploaded shape: abc123…
@@ -139,133 +139,68 @@ The CLI (`keystroke credentials upload`) and the web UI (`POST /api/v1/credentia
 
 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`
+### Dynamic credential resolution
 
-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:
+`CredentialSet` no longer accepts authored `resolve` hooks or separate
+`stored` schemas. Runtime transforms that mint temporary credentials are modeled
+as trusted dynamic connections:
 
 ```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',
-}
+connections: [
+  {
+    id: 'assume-role',
+    kind: 'dynamic',
+    resolver: { id: 'official.aws.assume-role', cacheMs: 10 * 60_000 },
+  },
+]
 ```
 
-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'`.
+The build/runtime contracts call this `needsDynamicResolution` with an optional
+`dynamicResolutionCacheMs` hint. User-authored integrations should prefer
+manual, OAuth, credentials-exchange, exchange, or platform connections unless a
+trusted registered resolver already exists.
 
 ### 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.
+OAuth connections no longer declare where `clientId` / `clientSecret` come
+from in authored code. Connection definitions are seeded or registered into
+the database with an `oauth_client_policy`; trusted platform paths use that
+policy to resolve the right provider app credential row.
 
-The pattern is two credential sets, both authored with the raw
-`CredentialSet` primitive:
+The final authoring shape stays focused on the user-runtime credential:
 
 ```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,
+  connections: [
+    {
+      id: 'oauth',
+      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' },
     },
-  },
+  ],
 });
 ```
 
 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' } }`.
+- Provider app client material is represented by platform-only credential
+  definitions in DB seed/registration data, not by a public `CredentialSet`
+  field.
+- `oauth_client_policy.kind = 'platform-provider-app'` selects Keystroke-owned
+  provider app credentials; `kind = 'workspace-provider-app'` selects
+  organization-scoped workspace provider app credentials.
+- User-runtime consumers never receive platform-only provider app secrets.
 
 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>`).
+workspace provider app is registered.
 
 ## Validating a credential at upload time
 
@@ -330,7 +265,7 @@ 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`.
+Canonical adopter: the Stripe provider package in the integrations repo.
 
 ## `credentials-exchange`
 
@@ -346,7 +281,7 @@ not a third-party authorization server — exchange them for something else
    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`.
+   `createBrowserLoginExchange` from `@keystrokehq/browserbase`.
 
 3. **Service-account JWT.** User pastes a private-key PEM. Input:
    `clientEmail` + `privateKeyPem`. Stored: freshly-minted JWT. Rotate by

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

@@ -98,7 +98,7 @@ Use the declarative form when `tokenResult.accessToken` (optionally
 
 ```ts
 import { CredentialSet } from '@keystrokehq/core';
-import { createOAuth2Connection } from '@keystroke/credential-connection';
+import { defineOAuthConnection } from '@keystroke/credential-connection';
 import { z } from 'zod';
 
 export const salesforceCredentials = new CredentialSet({
@@ -107,7 +107,7 @@ export const salesforceCredentials = new CredentialSet({
     SALESFORCE_ACCESS_TOKEN: z.string(),
     SALESFORCE_INSTANCE_URL: z.string(),
   }),
-  connection: createOAuth2Connection({
+  connection: defineOAuthConnection({
     authUrl: 'https://login.salesforce.com/services/oauth2/authorize',
     tokenUrl: 'https://login.salesforce.com/services/oauth2/token',
     scopes: ['api', 'refresh_token', 'offline_access'],
@@ -137,7 +137,7 @@ 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({
+connection: defineOAuthConnection({
   authUrl: 'https://account.docusign.com/oauth/auth',
   tokenUrl: 'https://account.docusign.com/oauth/token',
   scopes: ['signature', 'extended'],
@@ -206,55 +206,33 @@ connection: {
 },
 ```
 
-Canonical adopter: `packages/integrations/integration-stripe/src/integration.ts`.
+Canonical adopter: the Stripe provider package in the integrations repo.
 
-## Cached resolve
+## Dynamic credential resolution
 
-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.
+Use a trusted dynamic connection when a provider requires minting temporary
+runtime credentials from stored connection state. The resolver is registered by
+descriptor, not authored as a credential-set method.
 
 ```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.',
-  },
+export const aws = new CredentialSet({
+  id: 'aws',
+  auth: z.object({ AWS_ACCESS_KEY_ID: z.string(), AWS_SECRET_ACCESS_KEY: z.string() }),
+  connections: [
+    {
+      id: 'assume-role',
+      kind: 'dynamic',
+      resolver: { id: 'official.aws.assume-role', cacheMs: 10 * 60_000 },
+    },
+  ],
 });
 ```
 
-## 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.
+The generated contracts surface this as `needsDynamicResolution` and
+`dynamicResolutionCacheMs`.
 
 ## `credentials-exchange` — API-login
 
@@ -314,7 +292,7 @@ export const acmeCrm = new CredentialSet({
 ## `credentials-exchange` — browser-login
 
 Provider has no API; login requires a real browser. Use
-`createBrowserLoginExchange` from `@keystroke/integration-browserbase` to
+`createBrowserLoginExchange` from `@keystrokehq/browserbase` to
 drive Browserbase + Stagehand. The LLM never sees plaintext credentials —
 Stagehand substitutes `%fieldName%` at Chromium level.
 
@@ -322,7 +300,7 @@ Stagehand substitutes `%fieldName%` at Chromium level.
 import {
   createBrowserLoginExchange,
   type BrowserbaseCredentials,
-} from '@keystroke/integration-browserbase';
+} from '@keystrokehq/browserbase';
 import { CredentialSet } from '@keystrokehq/core';
 import { z } from 'zod';
 
@@ -464,8 +442,6 @@ 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) => {
@@ -499,8 +475,6 @@ declare function assumeRole(params: {
 
 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(),
@@ -541,8 +515,6 @@ declare function kmsSignJwt(params: {
 
 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) => {
@@ -575,8 +547,7 @@ post-exchange identity fetches.
 
 ```ts
 import {
-  buildDefaultAuthUrl,
-  exchangeCodeDefault,
+  oauthDefaults,
   oauthPresets as p,
   pipe,
 } from '@keystroke/credential-connection';
@@ -584,8 +555,8 @@ import {
 connection: {
   kind: 'oauth',
   // ...urls, scopes, tokenType, vault...
-  buildAuthUrl: pipe(buildDefaultAuthUrl, p.scopeDelimiter(',')),
-  exchangeCode: pipe(exchangeCodeDefault, p.requireSuccessFlag('ok')),
+  buildAuthUrl: pipe(oauthDefaults.buildAuthUrl, p.scopeDelimiter(',')),
+  exchangeCode: pipe(oauthDefaults.exchangeCode, p.requireSuccessFlag('ok')),
 },
 ```
 
@@ -651,7 +622,7 @@ The same agent example could also be written with `new Operation({...})` if the
 ## Agent usage
 
 ```ts
-import { anthropic } from '@keystroke/integration-ai';
+import { anthropic } from '@keystrokehq/ai';
 import { Agent } from '@keystrokehq/core';
 
 export const supportAgent = new Agent({
@@ -714,13 +685,14 @@ export const crmMcpServer = new McpServer({
 
 Use `credentialMapper(...)` to convert Keystroke credential values into transport-specific config such as headers, env vars, or query parameters.
 
-## `needsResolve`
+## Dynamic resolution flags
 
 ```ts
-const shouldResolve = oauthCredentials.needsResolve;
+const usesDynamicResolution = requirement.needsDynamicResolution;
 ```
 
-`needsResolve` is `true` only when the credential set was defined with both `stored` and `resolve`.
+`needsDynamicResolution` is true only for requirements backed by a trusted
+registered dynamic resolver.
 
 ## `describe()` and `toManifest()`
 
@@ -746,7 +718,7 @@ One `CredentialSet` declared in code is a **type**. The platform can store many
 ┌───────────────────────────────────────────────────────────────────┐
 │  Credential Set TYPE                                              │
 │  Declared in code. One per integration.                           │
-│  Example: keystroke:gmail                                         │
+│  Example: gmail                                                   │
 │    schema = { access_token: string, refresh_token: string }       │
 │    connection = OAuth 2.0 with Google                             │
 └───────────────────────────────────────────────────────────────────┘
@@ -767,7 +739,7 @@ One `CredentialSet` declared in code is a **type**. The platform can store many
 What authors often try first is the anti-pattern:
 
 ```ts
-import { gmail } from '@keystroke/integration-google';
+import { gmail } from '@keystrokehq/google';
 import { Step } from '@keystrokehq/core';
 
 export const brokenStep = new Step({
@@ -783,7 +755,7 @@ The supported path is **multi-step decomposition**: one credential set type, mul
 
 ```ts
 // One credential set TYPE, declared exactly once (by the integration).
-import { gmail } from '@keystroke/integration-google';
+import { gmail } from '@keystrokehq/google';
 import { Step, Workflow } from '@keystrokehq/core';
 import { z } from 'zod';
 
@@ -833,14 +805,14 @@ export const inboxDigest = new Workflow({
 });
 ```
 
-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:
+At run time, the operator connects both Gmail accounts, which creates two vault rows under `credentialDefinitionId: 'gmail'`, then chooses which one backs each call site:
 
 ```jsonc
 {
   "workflowId": "inbox-digest",
   "credentialBindings": {
-    "readPersonal:keystroke:gmail": "cset_personal",
-    "readWork:keystroke:gmail": "cset_work"
+    "readPersonal:gmail": "cset_personal",
+    "readWork:gmail": "cset_work"
   }
 }
 ```
@@ -856,14 +828,14 @@ One drawer per `id`, ever. A `CredentialSet` declaration is the label on the dra
 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`
+- build-time across the project via `assertUniqueCredentialDefinitionIds`
 - 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';
+import { stripe } from '@keystrokehq/stripe';
 
 // One declaration in code.
 export const billingCredential = stripe;

package/keystroke-credential-binding/references/source-map.md

@@ -10,25 +10,25 @@ import { CredentialSet } from '@keystrokehq/core';
 
 - `id`
 - `namespace`
-- `resolvedCredentialSetId`
+- `credentialDefinitionId`
 - `name`
 - `description`
 - `auth`
-- `stored`
-- `resolve`
-- `needsResolve`
+- `connections`
+- `needsRawSecret`
+- `onCredentialRevoked`
 
 ### What they are used for
 
 - `id`: stable credential set identifier
 - `namespace`: optional namespace used for manifest and storage identity
-- `resolvedCredentialSetId`: computed namespaced id used for manifest and binding infrastructure
+- `credentialDefinitionId`: computed namespaced id used for manifest and binding infrastructure
 - `name`: human-readable name
 - `description`: short explanation of what the credentials are for
 - `auth`: runtime credential schema
-- `stored`: stored credential schema when the stored shape differs from the runtime shape
-- `resolve`: async conversion from stored values to runtime auth values
-- `needsResolve`: tells you whether the credential set uses the stored-plus-resolve flow
+- `connections`: credential acquisition paths such as manual, OAuth, exchange, dynamic, or platform
+- `needsRawSecret`: routes real secret values into the runtime when proxy substitution cannot work
+- `onCredentialRevoked`: top-level policy for revoked credential errors
 
 ## `CredentialSet` instance methods
 
@@ -61,7 +61,7 @@ import { CredentialSet } from '@keystrokehq/core';
 - if `stored` is present, `resolve` must also be present
 - if `resolve` is present, `stored` must also be present
 - prefer typed access through runtime context rather than ad hoc env access inside primitives
-- runtime credential context keys use raw `id`, not `resolvedCredentialSetId`
+- runtime credential context keys use raw `id`, not `credentialDefinitionId`
 
 ## Where to read next
 

package/keystroke-trigger-authoring/references/testing.md

@@ -6,11 +6,11 @@ Assume `paymentWebhook`, `orderPolling`, and `paymentWorkflow` are the public tr
 
 ## Vitest setup
 
-`keystrokeTestPlugin()` adds the core test setup file to Vitest, which is required for credential resolution and context mocking.
+`keystrokeTestPlugin()` adds the Keystroke testing setup file to Vitest, which is required for credential resolution and context mocking.
 
 ```ts
 import { defineConfig } from 'vitest/config';
-import { keystrokeTestPlugin } from '@keystrokehq/core/vitest';
+import { keystrokeTestPlugin } from '@keystrokehq/testing/vitest';
 
 export default defineConfig({
   plugins: [keystrokeTestPlugin()],

package/keystroke-workflow-authoring/SKILL.md

@@ -123,7 +123,7 @@ Teach these rules:
    - waits and hooks
 5. Put operational work in steps, shared operations, or agents.
 6. Keep each exported primitive in its own typed file.
-7. Finish with tests using `@keystrokehq/core/vitest`.
+7. Finish with tests using `@keystrokehq/testing/vitest`.
 
 ## Workflow rules