@keystrokehq/skills 0.0.4 → 0.0.7

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @keystrokehq/skills
 
+## 0.0.7
+
+### Patch Changes
+
+- 7abf3aa: Add runtime script guidance and scaffold `@keystrokehq/runtime` into initialized projects.
+
+## 0.0.6
+
+### Patch Changes
+
+- a1488f8: Update trigger authoring skills for declarative webhook and polling trigger APIs.
+
+## 0.0.5
+
+### Patch Changes
+
+- a94a8e3: Rename the packaged Keystroke project context artifact to `_AGENTS.md` while preserving `AGENTS.md` as the destination filename during CLI init and skills sync.
+
 ## 0.0.4
 
 ### Patch Changes

package/README.md

@@ -16,6 +16,7 @@ The packaged skills are:
 - `keystroke-trigger-authoring`
 - `keystroke-task-authoring`
 - `keystroke-cli-workspace`
+- `keystroke-runtime-scripts`
 
 ## Editing
 
@@ -31,7 +32,7 @@ The publishable package content follows this structure:
 
 ```text
 src/
-├── AGENTS.md
+├── _AGENTS.md
 ├── <skill-name>/
 │   ├── SKILL.md
 │   └── references/
@@ -40,7 +41,8 @@ src/
 └── ...
 ```
 
-- `src/AGENTS.md` is the Keystroke project context written or appended to project-root `AGENTS.md` by `keystroke init`.
+- `src/_AGENTS.md` is the Keystroke project context written or appended to project-root `AGENTS.md` by `keystroke init` and `keystroke skills sync`.
+- The leading underscore keeps the package source artifact from being loaded as repository-local editor context while preserving the destination filename.
 - `SKILL.md` stays concise and procedural.
 - `references/` holds longer examples, source maps, and gotchas.
 - `evals/<skill-name>/evals.json` stores the initial evaluation prompts used with `.agents/skills/skill-creator/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keystrokehq/skills",
-  "version": "0.0.4",
+  "version": "0.0.7",
   "private": false,
   "type": "module",
   "publishConfig": {

package/src/{AGENTS.md → _AGENTS.md}

@@ -29,6 +29,8 @@ Keystroke also has one shared unit-of-work primitive: `Operation`.
 - Use the `Operation` name when describing shared infrastructure, integrations, or a reusable unit that can be used in both places.
 - The runtime behavior comes from context, not from which alias name was used in the constructor.
 
+For local TypeScript scripts, agents can import `@keystrokehq/runtime` to run `Operation` / `Step` / `Tool` instances with automatic credential loading from overrides, env vars, or saved Keystroke auth.
+
 Runtime boundary:
 
 - workflows and steps are authored as TypeScript control-flow and unit-of-work code
@@ -103,7 +105,7 @@ Required structure:
 
 - exported primitives should be top-level and statically visible
 - helper files such as `schemas.ts`, `utils.ts`, or `prompts.ts` should not export primitives
-- a `*.trigger.ts` file may also export that trigger's `TriggerAttachment` values
+- a `*.trigger.ts` file may also export narrowed trigger variants or bound trigger helpers
 - tests are exempt, but authored project code should follow the typed-file convention everywhere
 
 Example layout:

package/src/keystroke-agent-authoring/SKILL.md

@@ -172,7 +172,7 @@ Teach these rules explicitly:
 - Do not use `process.env` in authored agent or tool code.
 - Expect the default agent sandbox to be persistent.
 - Create a custom `Sandbox` only when the default sandbox needs customization.
-- Follow Zod v4 syntax in examples and authored code. See `../../../.agents/rules/zod-v4-requirements.md`.
+- Follow Zod v4 syntax in examples and authored code. See `../../../.agents/skills/zod-4/SKILL.md` for deep schema guidance.
 
 ## Agent Guidelines for Custom Tools & Operations
 

package/src/keystroke-agent-authoring/references/source-map.md

@@ -88,7 +88,7 @@ import {
 ### What they are used for
 
 - `credentialSets`: credentials attached directly to the agent
-- `allCredentialSets`: combined credential surface from the agent, its tools, its MCP servers, and its messaging gateways
+- `allCredentialSets`: combined credential requirements from the agent, its tools, its MCP servers, and its messaging gateways
 - `messaging`: `MessagingGateway[]` conversational entry configuration
 - `runtimeKind`: whether the agent is declarative-only or has `run` / `stream` implementations
 - `workflowSafeReference`: stable reference shape used by other primitives such as `Task`

package/src/keystroke-credential-binding/SKILL.md

@@ -87,7 +87,8 @@ Do not assume one credential location covers every layer. An agent can need prov
 
 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)
+- polling triggers read credentials from `poll(ctx).credentials` when they attach credential sets
+- webhook filters, webhook idempotency, and workflow trigger transforms are declarative or mapping-only paths and do not receive credentials
 - MCP servers map credentials through `credentialMapper`
 - authored code should not read secrets from `process.env`
 
@@ -117,7 +118,7 @@ This matters for integration authors and when explaining `createOperationFactory
 - 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`.
+- Follow Zod v4 syntax in examples and authored code. See `../../../.agents/skills/zod-4/SKILL.md` for deep schema guidance.
 - 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
@@ -439,6 +440,6 @@ 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/source-map.md` for public credential APIs
 - `references/cli.md` for the current credential command cookbook
 - `references/patterns.md` for field-by-field code examples

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

@@ -410,7 +410,7 @@ drop it from `stored` and have `rotate` return `'needs-reinput'` instead.
 - 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
+  Throws when neither is present so a missing credential becomes
   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.
@@ -640,28 +640,27 @@ This attaches credentials directly to the agent and also allows tools on the age
 ## Trigger usage
 
 ```ts
-import { WebhookTrigger } from '@keystrokehq/core';
+import { pollingTrigger } 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',
+export const crmPolling = pollingTrigger({
+  id: 'crm-polling',
+  description: 'Polls CRM records with credential-backed API access.',
   credentialSets: [crmCredentials],
-  payload: z.object({
-    id: z.string(),
+  schedule: '5m',
+  response: z.object({
+    records: z.array(z.object({ id: z.string() })),
   }),
-  verify: async (_request, ctx) => {
-    const secret = ctx.credentials.crmApi.apiKey;
-    if (!secret) {
-      throw new Error('Missing signing secret');
-    }
+  poll: async (ctx) => {
+    const apiKey = ctx.credentials.crmApi.apiKey;
+    return {
+      records: [{ id: `record-for-${apiKey}` }],
+    };
   },
 });
 ```
 
-This pattern is useful when the trigger itself must verify or authenticate incoming events.
+This pattern is useful when polling logic needs credentials. Webhook triggers do not attach per-trigger credential sets in the current custom/app source model.
 
 ## MCP server usage
 

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

@@ -52,7 +52,8 @@ import { CredentialSet } from '@keystrokehq/core';
 - `Operation.run(..., ctx).credentials`
 - `Step.run(..., ctx).credentials`
 - `Tool.run(..., ctx).credentials`
-- trigger `verify` callback and polling trigger `poll` callback (`filter`, `idempotencyKey`, and `transform` do not receive credentials)
+- polling trigger `poll(ctx).credentials`
+- not webhook `filter`, webhook `idempotencyKey`, or workflow trigger `transform`
 - `McpServer.credentialMapper(credentials)`
 
 ## Important rules

package/src/keystroke-runtime-scripts/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: keystroke-runtime-scripts
+description: Use @keystrokehq/runtime in local TypeScript scripts to run Keystroke Operation, Step, or Tool instances with credential loading and runtime context. Use when writing one-off scripts, local integration checks, or credential-backed operation runs outside Vitest.
+---
+
+# Keystroke Runtime Scripts
+
+Use this skill when an agent needs to run Keystroke operations from a local TypeScript or JavaScript script.
+
+Default split:
+- use `@keystrokehq/runtime` for local scripts and manual integration checks
+- use `@keystrokehq/testing` for Vitest tests, mocks, hooks, and deterministic assertions
+- use the CLI skill for workflow builds, deploys, credential upload, and deployed workflow runs
+
+## Quick start
+
+Install the runtime side effect once, then call `.run(...)` on an `Operation`, `Step`, or `Tool`.
+
+```ts
+import '@keystrokehq/runtime';
+
+import { listObjects } from '@keystrokehq/attio/objects';
+
+const objects = await listObjects.run({});
+console.info(JSON.stringify(objects, null, 2));
+```
+
+Or use the explicit helper:
+
+```ts
+import { run } from '@keystrokehq/runtime';
+import { listObjects } from '@keystrokehq/attio/objects';
+
+const objects = await run(listObjects, {});
+console.info(JSON.stringify(objects, null, 2));
+```
+
+## Configure runtime
+
+Use `configureRuntime(...)` for process-wide script settings:
+
+```ts
+import { configureRuntime } from '@keystrokehq/runtime';
+
+configureRuntime({
+  credentials: {
+    mode: 'auto',
+    overrides: {
+      attio: {
+        ACCESS_TOKEN: process.env.ATTIO_ACCESS_TOKEN,
+      },
+    },
+  },
+  workflowGlobals: {
+    tenantId: 'tenant_local',
+  },
+  stepContext: {
+    stepId: 'local-script',
+  },
+});
+```
+
+Credential modes:
+- `auto`: explicit overrides, env vars, then saved `keystroke auth` credentials
+- `env-only`: overrides and env vars only
+- `off`: no runtime credential resolver
+
+Use `withRuntime(options, callback)` when configuration must be scoped to one block. Use `createRuntime(options)` when you need an explicit handle and will call `runtime.dispose()`.
+
+## Rules
+
+- Keep scripts small and disposable.
+- Prefer operation `.run(input)` after the side-effect import for simple scripts.
+- Prefer `run(operation, input)` when the call site should make the runtime dependency obvious.
+- Put secret values in `credentials.overrides` or env vars named from the credential set, not in source.
+- Pass `workflowGlobals` when the operation expects typed workflow globals.
+- Pass `stepContext` only for local metadata such as `stepId`, attempts, tracing, or prefilled credentials.
+- Do not use runtime scripts as tests; use `@keystrokehq/testing` in `.test.ts` files.
+- Do not use `execution: 'cloud'`; local scripts currently use `execution: 'local'`.

package/src/keystroke-task-authoring/SKILL.md

@@ -22,12 +22,10 @@ import { z } from 'zod';
 import { welcomeAgent } from './welcome.agent';
 
 const welcomeWebhookTrigger = webhookTrigger({
-  name: 'Welcome Webhook',
+  id: 'welcome-webhook',
   description: 'Receives welcome payloads.',
   source: {
     type: 'custom',
-    method: 'POST',
-    path: '/welcome',
   },
   payload: z.object({
     name: z.string(),
@@ -40,7 +38,7 @@ export const welcomeWebhookTask = new Task({
   description: 'Uses a webhook payload to drive one agent run.',
   agent: welcomeAgent,
   prompt:
-    'Write a greeting for this webhook payload: {{trigger.payload}}. Trigger name: {{trigger.name}}.',
+    'Write a greeting for this webhook payload: {{trigger.payload}}. Trigger id: {{trigger.id}}.',
   triggers: [welcomeWebhookTrigger],
   lifecycle: {
     maxExecutions: 1,
@@ -80,7 +78,7 @@ Teach these rules:
 Teach the supported task prompt variables:
 
 - `{{trigger.payload}}`
-- `{{trigger.name}}`
+- `{{trigger.id}}`
 - `{{trigger.type}}`
 
 Use prompt templating when the agent prompt should include structured trigger context without inventing a separate payload mapping layer.
@@ -113,7 +111,7 @@ Choose a workflow when:
 - Keep each exported task in its own `*.task.ts` file.
 - Keep the referenced agent in its own `*.agent.ts` file.
 - Keep triggers in their own `*.trigger.ts` files.
-- Use Zod v4 syntax in all examples and authored code. See `../../../.agents/rules/zod-v4-requirements.md`.
+- Use Zod v4 syntax in all examples and authored code. See `../../../.agents/skills/zod-4/SKILL.md` for deep schema guidance.
 - Keep task prompts explicit about what the agent should do with trigger data.
 
 ## References

package/src/keystroke-task-authoring/references/patterns.md

@@ -10,12 +10,10 @@ import { z } from 'zod';
 import { triageAgent } from './triage.agent';
 
 const inboundWebhook = webhookTrigger({
-  name: 'Inbound Webhook',
+  id: 'inbound-webhook',
   description: 'Receives inbound payloads.',
   source: {
     type: 'custom',
-    method: 'POST',
-    path: '/inbound',
   },
   payload: z.object({
     message: z.string(),
@@ -41,7 +39,7 @@ import { z } from 'zod';
 import { reportAgent } from './report.agent';
 
 const dailyReportTrigger = cronTrigger({
-  name: 'Daily Report Trigger',
+  id: 'daily-report-trigger',
   description: 'Runs each morning.',
   input: z.object({
     mode: z.literal('daily'),
@@ -56,7 +54,7 @@ export const dailyReportTask = new Task({
   id: 'daily-report-task',
   name: 'Daily Report Task',
   agent: reportAgent,
-  prompt: 'Generate the daily report for {{trigger.name}} using {{trigger.payload}}.',
+  prompt: 'Generate the daily report for {{trigger.id}} using {{trigger.payload}}.',
   triggers: [dailyReportTrigger],
 });
 ```
@@ -69,7 +67,7 @@ import { z } from 'zod';
 import { followUpAgent } from './follow-up.agent';
 
 const staleTicketPolling = pollingTrigger({
-  name: 'Stale Ticket Polling',
+  id: 'stale-ticket-polling',
   description: 'Polls for stale tickets.',
   schedule: '*/15 * * * *',
   response: z.object({
@@ -80,7 +78,9 @@ const staleTicketPolling = pollingTrigger({
     ticketId: 'ticket_123',
     status: 'stale',
   }),
-  filter: (payload) => payload.status === 'stale',
+  filter: z.object({
+    status: z.literal('stale'),
+  }),
 });
 
 export const staleTicketTask = new Task({

package/src/keystroke-task-authoring/references/source-map.md

@@ -31,13 +31,12 @@ import { Task, type TaskConfig, type TaskLifecycle } from '@keystrokehq/core';
 ## `TriggerContext`
 
 - `payload`
-- `name`
+- `id`
 - `type`
 
 The current public trigger context `type` values are:
 - `cron`
 - `polling`
-- `provider`
 - `webhook`
 
 ## Prompt template tokens
@@ -48,8 +47,8 @@ directly into the `prompt` string — there is no function to call.
 
 Supported tokens:
 - `{{trigger.payload}}` — resolved to `JSON.stringify` of the trigger payload
-- `{{trigger.name}}` — resolved to the trigger name
-- `{{trigger.type}}` — resolved to the trigger type (one of `cron`, `polling`, `provider`, `webhook`)
+- `{{trigger.id}}` — resolved to the trigger id
+- `{{trigger.type}}` — resolved to the trigger type (one of `cron`, `polling`, `webhook`)
 
 Unknown `{{...}}` tokens are left as-is in the resolved prompt.
 
@@ -57,5 +56,5 @@ Unknown `{{...}}` tokens are left as-is in the resolved prompt.
 
 - tasks reference an agent through `agent`
 - tasks list triggers directly in `triggers`
-- tasks do not use `TriggerAttachment`
+- tasks do not bind triggers with workflow-style `{ transform }`
 - tasks are deployed through `keystroke deploy` or focused with `keystroke deploy --target <task.task.ts>`

package/src/keystroke-trigger-authoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: keystroke-trigger-authoring
-description: Build Keystroke cron, webhook, polling, and provider triggers with @keystrokehq/core. Use when the user wants to author, test, or explain trigger code, including webhook verification, polling schedules, filter and idempotency callbacks, and mapping trigger input into workflows or task-driven agent runs.
+description: Build Keystroke cron, webhook, and polling triggers with @keystrokehq/core. Use when the user wants to author, test, or explain trigger code, including webhook app/custom sources, declarative filter schemas, webhook idempotency config, polling schedules, trigger narrowing, and mapping trigger input into workflows or task-driven agent runs.
 ---
 
 # Keystroke Trigger Authoring
@@ -22,12 +22,10 @@ import { webhookTrigger, Workflow } from '@keystrokehq/core';
 import { z } from 'zod';
 
 export const paymentWebhook = webhookTrigger({
-  name: 'Payment Webhook',
+  id: 'payment-webhook',
   description: 'Receives payment events from an external provider.',
   source: {
     type: 'custom',
-    method: 'POST',
-    path: '/payments',
   },
   payload: z.object({
     id: z.string(),
@@ -36,8 +34,13 @@ export const paymentWebhook = webhookTrigger({
       amount: z.number(),
     }),
   }),
-  filter: (payload) => payload.type === 'payment.completed',
-  idempotencyKey: (payload) => payload.id,
+  filter: z.object({
+    type: z.literal('payment.completed'),
+  }),
+  idempotencyKey: {
+    from: 'payload',
+    path: 'id',
+  },
 });
 ```
 
@@ -69,7 +72,7 @@ import { z } from 'zod';
 import { reminderAgent } from './reminder.agent';
 
 const dailyReminderTrigger = cronTrigger({
-  name: 'Daily Reminder Trigger',
+  id: 'daily-reminder-trigger',
   description: 'Runs every morning.',
   input: z.object({
     mode: z.literal('daily'),
@@ -84,7 +87,7 @@ export const dailyReminderTask = new Task({
   id: 'daily-reminder-task',
   name: 'Daily Reminder Task',
   agent: reminderAgent,
-  prompt: 'Send the daily reminder for trigger {{trigger.name}}.',
+  prompt: 'Send the daily reminder for trigger {{trigger.id}}.',
   triggers: [dailyReminderTrigger],
 });
 ```
@@ -97,6 +100,8 @@ Teach this mental model clearly:
 - workflow triggers are listed in `Workflow({ triggers: [...] })`
 - a bare trigger in the array means the trigger payload passes through directly as workflow input
 - calling the trigger as a function with `{ transform }` creates a bound trigger for payload-to-input mapping
+- filtering lives on the trigger as a pure Zod schema, or on a narrowed child trigger with `.narrow({ id, filter })`
+- webhook idempotency is declarative config, not a callback
 - task triggers are listed inline in `Task.triggers`
 - a `MessagingGateway` is not a trigger
 
@@ -106,11 +111,10 @@ Teach these public trigger factory functions from `@keystrokehq/core`:
 - `cronTrigger`
 - `webhookTrigger`
 - `pollingTrigger`
-- `providerTrigger`
 
-Default to cron, webhook, and polling first. Use provider triggers when the user specifically needs provider-event authoring.
+Use webhook triggers with `source: { type: 'app', appRef }` when events are fanned out by a Keystroke-managed provider app. Use `source: { type: 'custom' }` when the platform should create a Keystroke-owned custom webhook surface.
 
-The factories return a `CallableTrigger` — an object with trigger properties (`.name`, `.toManifest()`, etc.) that is also callable as a function to create a bound trigger with optional `transform` and `filter`. Webhook and polling triggers also expose `.filter` and `.idempotencyKey` callbacks; cron triggers do not.
+The factories return a `CallableTrigger` — an object with trigger properties (`.id`, `.toManifest()`, etc.) that is also callable as a function to create a bound trigger with optional `transform`. Bindings carry only `transform`; they do not carry filter or idempotency callbacks.
 
 ## Manual API Execution
 
@@ -140,6 +144,7 @@ Workflow trigger rules:
 - list it in `Workflow({ triggers: [...] })`
 - for a bare trigger (no transform), place it directly: `triggers: [myTrigger]`
 - for a bound trigger with transform, call it: `triggers: [myTrigger({ transform: (payload) => ({...}) })]`
+- for per-workflow filtering, attach a narrowed trigger: `triggers: [myTrigger.narrow({ id: '...', filter: z.object({...}) })({ transform })]`
 - test the mapping by creating a bound trigger and calling `bound.transform?.(payload)`
 
 ## Task triggers
@@ -156,12 +161,13 @@ Task trigger rules:
 ## Trigger rules
 
 - Keep each exported trigger in its own `*.trigger.ts` file.
-- Use `verify` for authenticity or admission checks (webhook triggers only).
-- Use `filter` for event gating (webhook and polling triggers only — cron triggers do not support `filter`).
-- Use `idempotencyKey` for deduplication or stable identity (webhook and polling triggers only — cron triggers do not support `idempotencyKey`).
-- `filter` and `idempotencyKey` receive the typed parsed payload as the first argument. Only `verify` receives credentials.
-- For webhook providers, verify against the raw request data the runtime gives you.
-- Keep the webhook path rooted with `/` and provide only the suffix that follows the organization id in the URL — e.g. `path: '/payments'` is served at `/api/v1/webhooks/{orgId}/payments`. Do **not** include the `/webhooks/` prefix; the router supplies it.
+- Use `id`, not `name`, as the stable authored trigger identity.
+- Use `filter` for event gating on webhook and polling triggers. It must be a pure Zod schema that can be converted to JSON Schema; do not use `.refine()`, `.superRefine()`, `.transform()`, `.preprocess()`, `.pipe()`, or `z.custom()`.
+- Put conditional logic that cannot be expressed as a pure Zod schema at the start of the workflow body, or behind an integration `mapPayload` helper that throws when the declarative filter was too broad.
+- Use `idempotencyKey` only on webhook triggers. It is declarative config such as `{ from: 'payload', path: 'id' }`, `{ from: 'payload', strategy: 'hash' }`, `{ from: 'header', name: 'x-event-id' }`, or `{ from: 'header', strategy: 'hash' }`.
+- Polling triggers do not support idempotency config.
+- `source: { type: 'custom' }` means the platform owns the HTTP surface and authenticates with a Keystroke-issued secret. Do not add `method`, `path`, `verify`, or `response`.
+- `source: { type: 'app', appRef }` means a Keystroke-managed provider app fans out events centrally.
 
 ## Agent Guidelines for Custom Triggers
 
@@ -169,13 +175,13 @@ When an agent needs to write custom triggers, it must follow these rules:
 1. **Always use prebuilt triggers** if they exist before writing custom ones.
 2. **Collect context first**: Do you have all the information you need from the user to build the trigger? If not, ask the user to clarify what they are looking for. **Do Not Guess**.
 3. **Understand API payloads**: If the trigger handles webhooks or fetches from an API endpoint, search the provider's docs to understand the payloads. If possible, hit available endpoints to inspect the actual payloads.
-4. **Always write and run tests**: You must always write tests for custom triggers that handle non-trivial logic in callbacks. Always run the tests to verify that the new triggers run (see `references/testing.md`).
+4. **Always write and run tests**: You must always write tests for custom triggers that handle polling logic, payload mapping, or non-trivial filter schemas. Always run the tests to verify that the new triggers run (see `references/testing.md`).
 5. **Handle missing credentials**: If you cannot run tests because of missing credentials, ask the user to configure them following the `../keystroke-credential-binding/SKILL.md` skill. The user will need to upload credentials before deploying anyway.
 
 ## Testing path
 
 Default trigger testing guidance:
-- test trigger-specific callbacks such as `verify`, `filter`, or `poll` directly on the trigger
+- test declarative filter and idempotency metadata through `trigger.toManifest().runtime`
 - test webhook parsing with `trigger.payload.parse(JSON.parse(request.rawBody))`
 - test polling validation with `trigger.parseResponse(response)`
 - test workflow input mapping by creating a bound trigger and calling `bound.transform?.(payload)`
@@ -185,5 +191,5 @@ Default trigger testing guidance:
 
 Read these files as needed:
 - `references/source-map.md` for the public trigger surface
-- `references/patterns.md` for field-by-field examples, including provider triggers
+- `references/patterns.md` for field-by-field examples, including webhook app sources
 - `references/testing.md` for trigger and bound trigger tests

package/src/keystroke-trigger-authoring/references/patterns.md

@@ -13,11 +13,9 @@ File layout reminder:
 ## Shared advanced fields
 
 ```ts
-import type { ExecutionIdentityPolicy } from '@keystrokehq/core/types';
-
-const executionIdentityPolicy: ExecutionIdentityPolicy = {
+const executionIdentityPolicy = {
   subjectMode: 'requiredWhenUserProvidedCredential',
-};
+} as const;
 ```
 
 Use `executionIdentityPolicy` when the trigger should require a subject only in specific credential cases. Use `modeDefault` when the trigger should default to a specific trigger mode such as `'subscribable'`.
@@ -29,7 +27,7 @@ import { cronTrigger } from '@keystrokehq/core';
 import { z } from 'zod';
 
 export const nightlyDigestTrigger = cronTrigger({
-  name: 'Nightly Digest Trigger',
+  id: 'nightly-digest-trigger',
   description: 'Runs every night.',
   enabled: true,
   modeDefault: 'subscribable',
@@ -67,37 +65,49 @@ import { webhookTrigger } from '@keystrokehq/core';
 import { z } from 'zod';
 
 export const paymentWebhook = webhookTrigger({
-  name: 'Payment Webhook',
+  id: 'payment-webhook',
   description: 'Handles payment events.',
   enabled: true,
   modeDefault: 'subscribable',
   source: {
     type: 'custom',
-    method: 'POST',
-    path: '/payments',
-    verify: async (request) => {
-      if (!request.headers['x-signature']) {
-        throw new Error('Missing signature header');
-      }
-    },
-    response: {
-      successStatus: 202,
-      successBody: {
-        accepted: true,
-      },
-    },
   },
   payload: z.object({
     id: z.string(),
     type: z.string(),
     amount: z.number(),
   }),
-  filter: (payload) => payload.type === 'payment.completed',
-  idempotencyKey: (payload) => payload.id,
+  filter: z.object({
+    type: z.literal('payment.completed'),
+  }),
+  idempotencyKey: {
+    from: 'payload',
+    path: 'id',
+  },
 });
 ```
 
-Use `request.rawBody` in `verify` when a provider expects raw request verification. To parse a webhook body, use `trigger.payload.parse(JSON.parse(request.rawBody))`.
+Use `source: { type: 'custom' }` when the platform should create a Keystroke-owned webhook surface. The platform owns HTTP authentication and response handling for custom webhooks; do not add `method`, `path`, `verify`, or `response`.
+
+Use `source: { type: 'app', appRef }` when a Keystroke-managed provider app fans events out centrally:
+
+```ts
+export const slackMessageWebhook = webhookTrigger({
+  id: 'slack-message',
+  description: 'Receives Slack message events from the platform Slack app.',
+  source: {
+    type: 'app',
+    appRef: 'slack',
+  },
+  payload: z.object({
+    type: z.literal('message'),
+    channel: z.string(),
+    text: z.string(),
+  }),
+});
+```
+
+To parse a webhook body in tests or local checks, use `trigger.payload.parse(JSON.parse(request.rawBody))`.
 
 ## Binding a webhook trigger to a workflow with `transform`
 
@@ -128,7 +138,7 @@ import { pollingTrigger } from '@keystrokehq/core';
 import { z } from 'zod';
 
 export const orderPolling = pollingTrigger({
-  name: 'Order Polling',
+  id: 'order-polling',
   description: 'Polls for the newest order.',
   enabled: true,
   schedule: '*/15 * * * *',
@@ -144,12 +154,14 @@ export const orderPolling = pollingTrigger({
       status: 'created',
     };
   },
-  filter: (payload) => payload.status === 'created',
-  idempotencyKey: (payload) => payload.orderId,
+  filter: z.object({
+    status: z.literal('created'),
+  }),
 });
 ```
 
 Use this when the workflow should be entered from periodic remote-state checks.
+Polling filters are pure Zod schemas. Polling triggers do not support idempotency config.
 
 ## `pollingTrigger.parseResponse(...)`
 
@@ -162,23 +174,6 @@ const parsedResponse = orderPolling.parseResponse({
 
 Use `parseResponse(...)` when you want the trigger's response schema validation without running polling logic.
 
-## `providerTrigger`
-
-```ts
-import { providerTrigger } from '@keystrokehq/core';
-
-export const githubIssueTrigger = providerTrigger({
-  name: 'GitHub Issue Trigger',
-  description: 'Receives GitHub provider events for issue activity.',
-  provider: 'github',
-  eventTypes: ['issues.opened', 'issues.edited'],
-  filter: async (event) => event.type === 'issues.opened',
-  idempotencyKey: async (event) => event.id,
-});
-```
-
-Use a provider trigger when the user is authoring around normalized provider events instead of a raw webhook or polling loop.
-
 ## Bare trigger in workflow (no transform)
 
 ```ts
@@ -206,7 +201,7 @@ Call the trigger as a function with `{ transform }` when the trigger payload and
 
 ```ts
 const largePayments = paymentWebhook.narrow({
-  name: 'large-payments',
+  id: 'large-payments',
   filter: z.object({ amount: z.number().gt(100) }),
 });
 
@@ -231,36 +226,33 @@ Use the task skill when the user needs prompt templating, task lifecycle, or foc
 ## Trigger credentials
 
 ```ts
-import { CredentialSet, webhookTrigger } from '@keystrokehq/core';
+import { CredentialSet, pollingTrigger } from '@keystrokehq/core';
 import { z } from 'zod';
 
-const signingCredentials = new CredentialSet({
-  id: 'webhookSigning',
+const crmCredentials = new CredentialSet({
+  id: 'crmApi',
   auth: z.object({
-    secret: z.string(),
+    apiKey: z.string(),
   }),
 });
 
-const signedWebhook = webhookTrigger({
-  name: 'Signed Webhook',
-  description: 'Verifies a signed webhook.',
-  source: {
-    type: 'custom',
-    method: 'POST',
-    path: '/signed',
-    credentialSets: [signingCredentials],
-    verify: async (_request, ctx) => {
-      if (!ctx.credentials.webhookSigning.secret) {
-        throw new Error('Missing signing secret');
-      }
-    },
-  },
-  payload: z.object({
-    id: z.string(),
+const recentCustomers = pollingTrigger({
+  id: 'recent-customers',
+  description: 'Polls for recently updated customers.',
+  credentialSets: [crmCredentials],
+  schedule: '5m',
+  response: z.object({
+    customers: z.array(z.object({ id: z.string() })),
   }),
+  poll: async (ctx) => {
+    const apiKey = ctx.credentials.crmApi.apiKey;
+    return { customers: [{ id: `customer-for-${apiKey}` }] };
+  },
 });
 ```
 
+Polling triggers can attach credential sets and read credentials in `poll(ctx)`. Webhook triggers do not attach per-trigger credential sets in the current custom/app source model.
+
 ## `describe()` and `toManifest()`
 
 ```ts

package/src/keystroke-trigger-authoring/references/source-map.md

@@ -6,17 +6,16 @@ Use only the public imports a user repo can rely on:
 import {
   cronTrigger,
   pollingTrigger,
-  providerTrigger,
   webhookTrigger,
 } from '@keystrokehq/core';
 import type {
   BoundTrigger,
   CallableTrigger,
-  ExecutionIdentityPolicy,
+  IdempotencyKeyConfig,
   TriggerBindOptions,
-  TriggerEntry,
-  TriggerInstance,
-} from '@keystrokehq/core/types';
+  TriggerManifest,
+  WebhookRequest,
+} from '@keystrokehq/core/trigger';
 ```
 
 When a trigger explanation also needs to talk about workflow steps or agent tools, use the terminology from the other Keystroke skills:
@@ -27,7 +26,7 @@ When a trigger explanation also needs to talk about workflow steps or agent tool
 
 ## Common trigger fields
 
-- `name`
+- `id`
 - `description`
 - `enabled`
 - `credentialSets`
@@ -48,7 +47,7 @@ When a trigger explanation also needs to talk about workflow steps or agent tool
 
 ## `cronTrigger` instance properties
 
-- `.name`
+- `.id`
 - `.payload`
 - `.schedule`
 - `.timezone`
@@ -57,43 +56,83 @@ When a trigger explanation also needs to talk about workflow steps or agent tool
 
 ## `webhookTrigger` fields
 
-- `path`
-- `method`
+- `id`
+- `description`
+- `source`
 - `payload`
-- `verify`
 - `filter`
 - `idempotencyKey`
-- `response`
 
-## `webhookTrigger` instance methods
+### `webhookTrigger.source`
+
+- `{ type: 'custom' }` — Keystroke owns the HTTP surface and authenticates with a Keystroke-issued secret
+- `{ type: 'app', appRef: string }` — a Keystroke-managed provider app fans out events centrally
 
+Do not teach `method`, `path`, `verify`, or `response` on webhook triggers. Those are not part of the current public config.
+
+## `webhookTrigger` instance properties and methods
+
+- `.id`
+- `.source`
+- `.payload`
 - `.payload.parse(data)` — validate parsed body against the payload schema
-- `.verify?(request, ctx)` — raw request + credentials for authenticity checks
-- `.filter?(payload, request?)` — typed parsed body, optional raw request (no credentials)
-- `.idempotencyKey?(payload, request?)` — typed parsed body, optional raw request (no credentials)
+- `.filter` — pure Zod schema metadata, not a callback
+- `.idempotencyKey` — declarative `IdempotencyKeyConfig`, not a callback
+- `.toManifest()`
+- `.describe()`
 
 ## `pollingTrigger` fields
 
+- `id`
+- `description`
 - `schedule`
 - `response`
 - `poll`
 - `filter`
-- `idempotencyKey`
 
-## `pollingTrigger` instance methods
+## `pollingTrigger` instance properties and methods
 
+- `.id`
 - `.poll(ctx)`
 - `.parseResponse(response)`
-- `.filter?(payload)` — typed parsed payload (no credentials)
-- `.idempotencyKey?(payload)` — typed parsed payload (no credentials)
+- `.filter` — pure Zod schema metadata, not a callback
 
-## `providerTrigger` fields
+Polling triggers do not support idempotency config.
 
-- `provider`
-- `eventTypes`
-- `appRef`
-- `filter`
-- `idempotencyKey`
+## Filter schemas
+
+Webhook and polling triggers accept `filter` as a pure Zod schema. The runtime converts it to JSON Schema for server-side evaluation before a VM hop.
+
+Allowed filter schemas are structural schemas such as:
+
+```ts
+z.object({
+  type: z.literal('payment.completed'),
+  amount: z.number().min(100),
+})
+```
+
+Do not use effectful Zod features in filters:
+
+- `.refine()`
+- `.superRefine()`
+- `.transform()`
+- `.preprocess()`
+- `.pipe()`
+- `z.custom()`
+
+For conditional logic that cannot be expressed as a pure schema, do the check at the start of the workflow body or use an integration `mapPayload` helper.
+
+## Webhook idempotency config
+
+Webhook triggers accept declarative `IdempotencyKeyConfig`:
+
+- `{ from: 'payload', path: 'eventId' }`
+- `{ from: 'payload', strategy: 'hash' }`
+- `{ from: 'header', name: 'x-event-id' }`
+- `{ from: 'header', strategy: 'hash' }`
+
+There is no function-style idempotency callback.
 
 ## Calling a trigger (creating a bound trigger)
 
@@ -102,7 +141,7 @@ All factory-created triggers are callable. Calling one returns a `BoundTrigger`:
 - `trigger()` — bare binding (no transform)
 - `trigger({ transform })` — bound with payload-to-input mapping
 
-Bindings carry only `transform`. To filter events for a specific workflow, derive a child with `trigger.narrow({ name, filter })` and attach that — `.narrow()` is the only authoring path for per-target filtering. Binding-level `filter` and `idempotencyKey` are intentionally not part of the API.
+Bindings carry only `transform`. To filter events for a specific workflow, derive a child with `trigger.narrow({ id, filter })` and attach that. Binding-level `filter` and `idempotencyKey` are intentionally not part of the API.
 
 ## `BoundTrigger`
 
@@ -112,7 +151,7 @@ Bindings carry only `transform`. To filter events for a specific workflow, deriv
 
 ## Workflow `triggers` array
 
-`Workflow({ triggers: [...] })` accepts a `TriggerEntry[]`:
+`Workflow({ triggers: [...] })` accepts trigger entries:
 - a bare `CallableTrigger` (trigger payload passes through as workflow input)
 - a `BoundTrigger` (returned by calling the trigger with options)
 
@@ -124,4 +163,4 @@ Bindings carry only `transform`. To filter events for a specific workflow, deriv
 ## Where to read next
 
 - `patterns.md` for trigger field examples
-- `testing.md` for trigger callback and bound trigger tests
+- `testing.md` for trigger metadata, polling, and bound trigger tests

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

@@ -17,7 +17,7 @@ export default defineConfig({
 });
 ```
 
-## Test webhook verification and filtering
+## Test webhook parsing and declarative metadata
 
 ```ts
 const request = {
@@ -34,28 +34,36 @@ const request = {
   path: '/payments',
 };
 
-await paymentWebhook.verify?.(request, {
-  credentials: {},
-  triggerName: paymentWebhook.name,
-  triggerType: 'webhook',
+const payload = paymentWebhook.payload.parse(JSON.parse(request.rawBody));
+
+expect(payload).toEqual({
+  id: 'evt_123',
+  type: 'payment.completed',
+  amount: 5000,
 });
 
-const payload = paymentWebhook.payload.parse(JSON.parse(request.rawBody));
-const shouldRun = paymentWebhook.filter?.(payload, request);
+const runtime = paymentWebhook.toManifest().runtime;
+expect(runtime.filterSchema).toBeDefined();
+expect(runtime.idempotencyConfig).toEqual({
+  from: 'payload',
+  path: 'id',
+});
 ```
 
 This isolates the webhook-only concerns:
 
-- authenticity checks in `verify`
 - parsing via `trigger.payload.parse(JSON.parse(request.rawBody))`
-- event gating in `filter`
+- declarative event gating metadata in `runtime.filterSchema`
+- declarative dedupe metadata in `runtime.idempotencyConfig`
+
+Custom webhook HTTP authentication and responses are platform-owned in the current surface. Do not test `verify`, `method`, `path`, or `response` callbacks on authored webhook triggers.
 
 ## Test polling behavior
 
 ```ts
 const response = await orderPolling.poll({
   credentials: {},
-  triggerName: orderPolling.name,
+  triggerId: orderPolling.id,
   triggerType: 'polling',
   lastPolledAt: new Date().toISOString(),
   lastResponse: {
@@ -65,6 +73,7 @@ const response = await orderPolling.poll({
 });
 
 const payload = orderPolling.parseResponse(response);
+expect(orderPolling.toManifest().runtime.filterSchema).toBeDefined();
 ```
 
 This isolates the polling-only concerns:
@@ -72,6 +81,7 @@ This isolates the polling-only concerns:
 - what `poll(...)` returns
 - how prior state affects the next poll
 - whether the response matches the trigger schema
+- declarative filter metadata when the polling trigger has a filter schema
 
 ## Test bound trigger transform
 
@@ -110,26 +120,19 @@ const workflowInput = bound.transform?.(
 );
 ```
 
-Pass the optional second argument when the transform depends on webhook request data (headers, query params, etc.). Note that only `verify` receives credentials — `transform`, `filter`, and `idempotencyKey` do not.
+Pass the optional second argument when the transform depends on webhook request data such as headers or query params. `transform` does not receive credentials. Filters and idempotency are declarative metadata, not callbacks.
 
 ## Full webhook-to-workflow test
 
 ```ts
 it('maps a valid webhook event into workflow input', async () => {
-  const request = mockRequest({
-    headers: { 'x-signature': 'signed' },
-    rawBody: JSON.stringify({ id: 'evt_123', type: 'payment.completed', amount: 5000 }),
-  });
-
-  await paymentWebhook.verify?.(request, {
-    credentials: {},
-    triggerName: paymentWebhook.name,
-    triggerType: 'webhook',
+  const payload = paymentWebhook.payload.parse({
+    id: 'evt_123',
+    type: 'payment.completed',
+    amount: 5000,
   });
 
-  const payload = paymentWebhook.payload.parse(JSON.parse(request.rawBody));
-  const passed = paymentWebhook.filter?.(payload, request);
-  expect(passed).toBe(true);
+  expect(paymentWebhook.toManifest().runtime.filterSchema).toBeDefined();
 
   const bound = paymentWebhook({
     transform: (p) => ({ eventId: p.id, amount: p.amount }),
@@ -141,8 +144,8 @@ it('maps a valid webhook event into workflow input', async () => {
 
 ## What to validate
 
-- webhook verification success and failure
-- filter behavior
-- idempotency key behavior when defined
+- webhook payload parsing
+- declarative filter metadata
+- webhook idempotency config when defined
 - polling response shape
 - transform correctness from trigger payload to workflow input

package/src/keystroke-workflow-authoring/SKILL.md

@@ -93,6 +93,7 @@ Teach this mental model clearly:
 - `Workflow.run(...)` coordinates steps, child workflows, waits, hooks, and agents
 - `Step.run(...)` does low-level operational work and returns typed output
 - triggers are listed in `Workflow({ triggers: [...] })`; call a trigger with `{ transform }` to bind payload mapping
+- trigger filters are declarative Zod schemas on the trigger or on `.narrow({ id, filter })`, not workflow attachment callbacks
 - tasks are different: use `Task` when the job is “trigger -> prompt -> agent run”
 
 `Step`, `Tool`, and `Operation` are the same class. In this skill, default to `Step` because that matches workflow author language.
@@ -136,7 +137,7 @@ Teach these rules:
 - Use `workflowGlobals` for typed workflow-wide runtime values.
 - Use `CredentialSet` for secrets and integration auth.
 - Do not use `process.env` in authored workflow or step code.
-- Follow Zod v4 syntax in examples and authored code. See `../../../.agents/rules/zod-v4-requirements.md`.
+- Follow Zod v4 syntax in examples and authored code. See `../../../.agents/skills/zod-4/SKILL.md` for deep schema guidance.
 - Workflows can be registered as agent tools. Sync workflows return inline results; suspending workflows yield and resume later.
 - Add `largeResultMode: 'ref'` when a workflow tool may return large data; agents inspect refs with `describe_ref`, `read_ref`, and `slice_ref`.
 - Add `midSessionSnapshot: true` only for workflow tools that have measured benefit from preserving mid-tool-call reasoning state. The default turn-boundary yield path is simpler and should remain the default.

package/src/keystroke-workflow-authoring/references/patterns.md

@@ -48,21 +48,21 @@ import { z } from 'zod';
 const PayloadSchema = z.object({ accountId: z.string() });
 
 const accountCron = cronTrigger({
-  name: 'Nightly Account Sync',
+  id: 'nightly-account-sync',
+  description: 'Runs the account sync every night.',
   schedule: '0 0 * * *',
   input: PayloadSchema,
   payload: { accountId: 'default' },
 });
 
 const accountWebhook = webhookTrigger({
-  name: 'Account Webhook',
+  id: 'account-webhook',
+  description: 'Receives account sync webhook events.',
   source: {
     type: 'custom',
-    method: 'POST',
-    path: '/accounts',
   },
   payload: z.object({ id: z.string(), action: z.string() }),
-  filter: (p) => p.action === 'sync',
+  filter: z.object({ action: z.literal('sync') }),
 });
 
 export const accountSyncWorkflow = new Workflow({
@@ -80,7 +80,7 @@ export const accountSyncWorkflow = new Workflow({
 });
 ```
 
-Bare triggers (like `accountCron` above) pass their payload directly as workflow input. Call the trigger with `{ transform }` when the payload shape differs from the workflow input.
+Bare triggers (like `accountCron` above) pass their payload directly as workflow input. Call the trigger with `{ transform }` when the payload shape differs from the workflow input. Put filtering on the trigger as a pure Zod schema, or use `.narrow({ id, filter })` for workflow-specific filtering.
 
 ## Workflow metadata fields
 

package/src/keystroke-workflow-authoring/references/prebuilt-integrations.md

@@ -249,7 +249,7 @@ Common operation groups:
 - search: `searchCode`, `searchIssues`, `searchRepositories`
 - users and orgs: `getAuthenticatedUser`, `getUser`, `listOrganizations`, `listOrgMembers`
 
-Messaging-specific credential surfaces also exist in this package, but workflow trigger and conversation entry guidance belongs in the trigger and agent skills.
+Messaging-specific credential helpers also exist in this package, but workflow trigger and conversation entry guidance belongs in the trigger and agent skills.
 
 ## `@keystrokehq/google`