@keystrokehq/skills 0.0.3 → 0.0.6

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# @keystrokehq/skills
+
+## 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
+
+- bb9fea0: Fix: Removing callbacks from triggers (except polling)
+
+## 0.0.3
+
+### Patch Changes
+
+- c4870ce: Update public package references and authoring guidance for the provider-name integration packages.
+
+## 0.0.2
+
+### Patch Changes
+
+- 761d44e: Add `keystroke workflows run` for manually invoking workflows from a project's current deployment, including input and workflow globals parsing plus wait/follow support.
+
+  Update Keystroke CLI and workflow authoring skills with guidance for deployed workflow manual runs.
+
+## 0.0.1
+
+### Patch Changes
+
+- 2ff9004: Publish Keystroke skills as an npm package and let the CLI use its installed skills package as a fallback when syncing skills into projects.

package/README.md

@@ -19,34 +19,43 @@ The packaged skills are:
 
 ## Editing
 
-Edit the source files in `packages/skills/`.
+Edit shipped skill content in `packages/skills/src/`.
 
-Do not treat local editor skill directories as the source of truth for these packaged skills. Edit the canonical files in `packages/skills/` first, then use the Keystroke CLI skill sync flow when local `.cursor/skills` or `.claude/skills` copies need to be refreshed.
+Do not treat local editor skill directories as the source of truth for these packaged skills. Edit the canonical files in `packages/skills/src/` first, then use the Keystroke CLI skill sync flow when project-installed skill copies need to be refreshed.
+
+Evaluation prompts and notes live in `packages/skills/evals/`. They are repo-only authoring assets and are not published to npm or copied into user projects.
 
 ## Structure
 
-Each skill follows this structure:
+The publishable package content follows this structure:
 
 ```text
-<skill-name>/
-├── SKILL.md
-├── references/
-│   ├── source-map.md
-│   └── ...
-└── evals/
-    └── evals.json
+src/
+├── _AGENTS.md
+├── <skill-name>/
+│   ├── SKILL.md
+│   └── references/
+│       ├── source-map.md
+│       └── ...
+└── ...
 ```
 
+- `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/evals.json` stores the initial evaluation prompts used with `.agents/skills/skill-creator/`.
+- `evals/<skill-name>/evals.json` stores the initial evaluation prompts used with `.agents/skills/skill-creator/`.
 
 ## Wiring
 
-These packaged skills are intended to be copied into local editor skill directories through the Keystroke CLI:
+These packaged skills are installed into project agent skill directories through the Keystroke CLI:
 
-- packaged skills are authored here
-- `keystroke skills sync` copies them into `.cursor/skills` and `.claude/skills`
+- packaged skills are authored in `src/`
+- `keystroke init` always copies them into the canonical project path `.agents/skills`
+- `keystroke init --agent <agent> --method symlink` provisions selected agent-specific paths by linking back to `.agents/skills`
+- `keystroke init --agent <agent> --method copy` provisions selected agent-specific paths with independent copies
+- `keystroke skills sync` refreshes an existing project using the same `--agent` and `--method` flags
+- eval assets stay in `evals/` and are excluded from published packages and synced project skills
 
 If the discovery story changes later, update this package and the sync flow together. Until then, edit the packaged skills here first.
 
@@ -57,7 +66,7 @@ Because these are repo-authored local skills rather than externally installed sk
 Draft and refine these skills with the existing `.agents/skills/skill-creator/` workflow:
 
 1. Draft the skill
-2. Add realistic eval prompts to `evals/evals.json`
+2. Add realistic eval prompts to `evals/<skill-name>/evals.json`
 3. Run at least one evaluation pass
 4. Revise the skill based on results
 5. Improve the `description` once the body is stable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keystrokehq/skills",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "private": false,
   "type": "module",
   "publishConfig": {
@@ -9,15 +9,8 @@
   },
   "files": [
     "README.md",
-    "AGENTS-blurb.md",
-    "keystroke-workflow-authoring",
-    "keystroke-agent-authoring",
-    "keystroke-data-toolkit",
-    "keystroke-workflow-as-tool-debugging",
-    "keystroke-credential-binding",
-    "keystroke-trigger-authoring",
-    "keystroke-task-authoring",
-    "keystroke-cli-workspace"
+    "CHANGELOG.md",
+    "src"
   ],
   "scripts": {
     "build": "node -e \"process.exit(0)\"",

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

@@ -103,7 +103,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/{keystroke-agent-authoring → 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/{keystroke-agent-authoring → 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/{keystroke-agent-authoring → src/keystroke-agent-authoring}/references/testing.md

@@ -17,7 +17,7 @@ Default testing targets:
 
 ```ts
 import { defineConfig } from 'vitest/config';
-import { keystrokeTestPlugin } from '@keystrokehq/testing/vitest';
+import { keystrokeTestPlugin } from '@keystrokehq/testing';
 
 export default defineConfig({
   plugins: [keystrokeTestPlugin()],

package/{keystroke-cli-workspace → src/keystroke-cli-workspace}/SKILL.md

@@ -87,7 +87,7 @@ Important distinctions:
 - Use `keystroke connect <integration>` for official integration connection flows.
 - Use `keystroke credentials ...` for credential inspection and upload flows.
 - Use `keystroke skills sync` to copy `@keystrokehq/skills` into local editor skill directories.
-- Use `keystroke workflows run <authoredWorkflowId>` for deployed-workflow manual invocation; use `try-deploy` only when testing a temporary build artifact.
+- Use `keystroke workflows run <authoredWorkflowId>` for deployed-workflow manual invocation; use `keystroke workflows test <workflow>` when testing a temporary build artifact.
 
 ## References
 

package/{keystroke-cli-workspace → src/keystroke-cli-workspace}/references/command-map.md

@@ -36,8 +36,8 @@ Root help shows these directly. Subcommand help focuses on the local flags for t
 - `projects`: inspect cached project state
 - `connect`: connect official integrations through OAuth
 - `credentials`: list requirements and upload credentials
-- `workflows`: build, validate, inspect, diff, env, logs, paused, run, try-deploy
-- `test`: test workflows and agent-callable tools
+- `workflows`: build, validate, inspect, diff, env, logs, paused, test, run
+- `test`: test agent-callable tools
 - `deploy`: deploy workflows, agents, tasks, or focused targets via `--target <file>`
 - `sync`: local sync operations
 - `skills`: Keystroke skills sync flows
@@ -47,7 +47,7 @@ Root help shows these directly. Subcommand help focuses on the local flags for t
 
 - `keystroke workflows logs` is different from `keystroke logs`
 - `keystroke workflows run <authoredWorkflowId>` executes the current deployed workflow snapshot via the workflow execute API; it does not build or upload local code
-- `keystroke workflows try-deploy <workflow>` builds local code, uploads or references a test bundle, and runs that temporary artifact
+- `keystroke workflows test <workflow>` builds local code, uploads or references a test bundle, and runs that temporary artifact
 - `keystroke deploy --target <file>` is the focused deploy path
 - many commands support `--json`
 

package/{keystroke-cli-workspace → src/keystroke-cli-workspace}/references/project-lifecycle.md

@@ -77,7 +77,7 @@ keystroke workflows run wf_onboard_user --input '{"email":"user@example.com"}'
 
 Notes:
 - `workflows run` executes the current deployed snapshot through `client.workflows.execute()` / `POST /api/v1/workflows/execute`
-- it does not build or upload local source; use `workflows try-deploy` for temporary local artifact testing
+- it does not build or upload local source; use `workflows test` for temporary local artifact testing
 - pass `--project-id <uuid>` outside a project checkout, otherwise the CLI resolves `projectId` from `keystroke.config.ts`
 - pass `--workflow-globals` or `--workflow-globals-file` when the deployed manifest declares required workflow globals without defaults
 - use `--wait` to poll to a terminal status and `--follow` to poll logs/events while waiting

package/{keystroke-credential-binding → 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/{keystroke-credential-binding → 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/{keystroke-credential-binding → 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/{keystroke-task-authoring → 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/{keystroke-task-authoring → 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/{keystroke-task-authoring → 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/{keystroke-trigger-authoring → 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