@elevasis/sdk 1.8.2 → 1.9.0

package/reference/scaffold/operations/workflow-recipes.md

@@ -1,436 +1,436 @@
----
-title: Workflow Recipes
-description: Anatomy of a workflow, adapter usage, and trigger patterns -- runnable email-notification example replaces the trivial echo workflow. Resolves eval score 2/5 on workflow authoring.
----
-
-# Workflow Recipes
-
-`🟢 Stable` -- Use these patterns as-is against `@elevasis/sdk ^1.4.0`.
-
----
-
-## 1. Anatomy of a Workflow
-
-Every workflow is a `WorkflowDefinition` object with four top-level keys: `config`, `contract`, `steps`, and `entryPoint`. The `email-notification` workflow at `operations/src/email-notification/index.ts` is used as the running example throughout this section.
-
-### Config
-
-```typescript
-config: {
-  resourceId: 'email-notification', // Unique ID -- used in API calls and CLI
-  name: 'Email Notification',       // Human-readable display name
-  type: 'workflow',                  // Always 'workflow' (vs 'agent')
-  description: 'Sends a notification email to a user...',
-  version: '1.0.0',                  // Bump on contract changes
-  status: 'dev'                      // 'dev' or 'prod'
-}
-```
-
-- `resourceId` is the stable identifier used by `pnpm exec elevasis exec` and `/execute` API calls.
-- Bump `version` whenever you change `contract.inputSchema` or `contract.outputSchema`.
-
-### Contract
-
-```typescript
-// foundations/types/index.ts -- shared with frontend
-export const emailNotificationInputSchema = z.object({
-  recipientEmail: z.string().email(),
-  recipientName: z.string().min(1),
-  subject: z.string().min(1).max(200),
-  body: z.string().min(1).max(10000),
-  category: z.string().min(1).default('operations'),
-  actionUrl: z.string().url().optional()
-})
-
-export const emailNotificationOutputSchema = z.object({
-  delivered: z.boolean(),
-  notificationId: z.string().optional(),
-  summary: z.string()
-})
-
-export type EmailNotificationInput = z.infer<typeof emailNotificationInputSchema>
-export type EmailNotificationOutput = z.infer<typeof emailNotificationOutputSchema>
-```
-
-```typescript
-// operations/src/email-notification/index.ts
-import { emailNotificationInputSchema, emailNotificationOutputSchema } from '@foundation/types'
-
-contract: {
-  inputSchema: emailNotificationInputSchema,
-  outputSchema: emailNotificationOutputSchema
-}
-```
-
-**Rules:**
-
-- Define schemas in `foundations/types/index.ts` -- never inline Zod schemas in workflow files.
-- Both runtimes (frontend and platform) import from `@foundation/types`, keeping validation consistent.
-- `@foundation/types` resolves to `foundations/types/index.ts` via the tsconfig path alias.
-
-**Entity-backed workflows:** for workflows that operate on a domain entity, reference the entity contract rather than redeclaring it.
-
-```typescript
-// foundations/types/index.ts
-import { BaseDealSchema } from '@elevasis/core/entities'
-import { DealSchema } from '@foundation/types/entities' // project-local extended version
-
-export const closeDealInputSchema = z.object({
-  deal: DealSchema,
-  closedReason: z.string()
-})
-
-export type CloseDealInput = z.infer<typeof closeDealInputSchema>
-```
-
-`DealSchema` is defined in `foundations/types/entities.ts` by extending `BaseDealSchema` with project-specific metadata. See [../recipes/extend-a-base-entity.md](../recipes/extend-a-base-entity.md) for the pattern.
-
-### Steps
-
-Each step is a `WorkflowStep` with: `id`, `name`, `description`, `handler`, `inputSchema`, `outputSchema`, and `next`.
-
-```typescript
-import { StepType } from '@elevasis/sdk'
-
-steps: {
-  validate: {
-    id: 'validate',
-    name: 'Validate Input',
-    description: 'Validates recipient and content parameters before sending',
-    handler: async (rawInput, context) => {
-      const input = rawInput as EmailNotificationInput
-      context.logger.info(`[validate] Checking recipient: ${input.recipientEmail}`)
-      // ... validation logic ...
-      return input          // Pass validated data to next step
-    },
-    inputSchema: emailNotificationInputSchema,
-    outputSchema: emailNotificationInputSchema,  // Passes full input through to next step
-    next: { type: StepType.LINEAR, target: 'notify' }
-  },
-  notify: {
-    id: 'notify',
-    name: 'Send Notification',
-    handler: async (rawInput, context) => {
-      // ...
-      return { delivered: true, summary: '...' }
-    },
-    inputSchema: emailNotificationInputSchema,
-    outputSchema: emailNotificationOutputSchema,
-    next: null  // Terminal step -- ends the workflow
-  }
-}
-```
-
-**Key rules:**
-
-- `next: null` marks a terminal step.
-- `next: { type: StepType.LINEAR, target: 'stepId' }` chains to another step.
-- Use `context.logger` -- never `console.log`. Platform captures `context.logger.*` only.
-- Cast `rawInput` to your input type: `const input = rawInput as EmailNotificationInput`.
-
-### Entrypoint
-
-```typescript
-entryPoint: 'validate'   // Must match a step id in the steps map
-```
-
-The platform starts execution here. For single-step workflows, `entryPoint` points to the only step (e.g., `echo` points to `'echo'`).
-
-### Optional: Interface Form
-
-Declare `interface.form` to auto-generate an execution form in AI Studio and Command Center:
-
-```typescript
-interface: {
-  form: {
-    title: 'Send Email Notification',
-    description: 'Sends a notification email to a user.',
-    fields: [
-      { name: 'recipientEmail', label: 'Recipient Email', type: 'text', required: true },
-      { name: 'body', label: 'Body', type: 'text', required: true }
-    ],
-    submitButton: { label: 'Send notification', loadingLabel: 'Sending...' }
-  }
-}
-```
-
----
-
-## 2. Adapter Usage
-
-Adapters are typed wrappers over `platform.call()`. Import singletons from `@elevasis/sdk/worker`.
-
-### notifications
-
-Send a platform notification to the current user. `userId` and `organizationId` are injected server-side -- you never supply them.
-
-```typescript
-import { notifications } from '@elevasis/sdk/worker'
-
-await notifications.create({
-  category: 'operations',      // Any string: 'operations', 'delivery', 'acquisition', etc.
-  title: 'Workflow complete',
-  message: 'Your email notification was sent successfully.',
-  actionUrl: '/operations'     // Optional -- link the user can follow
-})
-```
-
-Available methods: `create`.
-
-### llm
-
-Generate text or structured output using a language model.
-
-```typescript
-import { llm } from '@elevasis/sdk/worker'
-
-const response = await llm.generate({
-  provider: 'anthropic',          // 'anthropic' | 'openai' | 'openrouter' | 'google'
-  model: 'claude-sonnet-4-5',
-  messages: [
-    { role: 'user', content: 'Summarize this email body: ' + input.body }
-  ]
-})
-
-const summary = response.output as string
-```
-
-For structured output, pass a JSON Schema as `responseSchema`:
-
-```typescript
-const response = await llm.generate({
-  provider: 'anthropic',
-  model: 'claude-sonnet-4-5',
-  messages: [{ role: 'user', content: 'Extract the key action from: ' + input.body }],
-  responseSchema: {
-    type: 'object',
-    properties: { action: { type: 'string' }, urgency: { type: 'string' } }
-  }
-})
-const { action, urgency } = response.output as { action: string; urgency: string }
-```
-
-Available methods: `generate`.
-
-### storage
-
-Upload and retrieve files scoped to the organization. All paths are automatically prefixed with the organization's storage prefix server-side.
-
-```typescript
-import { storage } from '@elevasis/sdk/worker'
-
-// Upload
-await storage.upload({
-  bucket: 'operations',
-  path: 'email-logs/2026-04-16/batch-01.json',
-  content: Buffer.from(JSON.stringify(logData)).toString('base64'),
-  contentType: 'application/json'
-})
-
-// Download
-const file = await storage.download({
-  bucket: 'operations',
-  path: 'email-logs/2026-04-16/batch-01.json'
-})
-
-// Signed URL for frontend access
-const { signedUrl } = await storage.createSignedUrl({
-  bucket: 'operations',
-  path: 'email-logs/2026-04-16/batch-01.json',
-  expiresIn: 3600
-})
-```
-
-Available methods: `upload`, `download`, `createSignedUrl`, `delete`, `list`.
-
-### scheduler
-
-Schedule future or recurring workflow executions.
-
-```typescript
-import { scheduler } from '@elevasis/sdk/worker'
-
-const schedule = await scheduler.createSchedule({
-  name: 'Daily email digest',
-  target: { resourceType: 'workflow', resourceId: 'email-notification' },
-  scheduleConfig: {
-    type: 'cron',
-    expression: '0 9 * * 1-5'  // 9am weekdays
-  }
-})
-
-context.logger.info(`[schedule] Created schedule: ${schedule.id}`)
-```
-
-Available methods: `createSchedule`, `updateAnchor`, `deleteSchedule`, `getSchedule`, `listSchedules`, `cancelSchedule`, `cancelSchedulesByMetadata`, `cancelScheduleByIdempotencyKey`, `findByIdempotencyKey`, `deleteScheduleByIdempotencyKey`.
-
-**Note on other adapters:** Integration adapters (`createResendAdapter`, `createAttioAdapter`, etc.) follow a factory pattern -- bind a credential once, use the instance for all calls:
-
-```typescript
-import { createResendAdapter } from '@elevasis/sdk/worker'
-
-const resend = createResendAdapter('my-resend-credential')
-await resend.sendEmail({
-  to: input.recipientEmail,
-  subject: input.subject,
-  html: `<p>${input.body}</p>`
-})
-```
-
-See `operations/node_modules/@elevasis/sdk/reference/` for the full adapter reference.
-
----
-
-## 3. Trigger Patterns from Frontend
-
-### (a) API call via `useApiClient`
-
-Use this pattern in React components and hooks. `apiRequest` automatically attaches the auth token and org context.
-
-```typescript
-// ui/src/features/notifications/hooks/useSendEmailNotification.ts
-import { useMutation } from '@tanstack/react-query'
-import { useApiClient } from '@/lib/hooks/useApiClient'
-import type { EmailNotificationInput, EmailNotificationOutput } from '@foundation/types'
-
-export function useSendEmailNotification() {
-  const { apiRequest } = useApiClient()
-
-  return useMutation({
-    mutationFn: async (input: EmailNotificationInput) => {
-      return apiRequest<EmailNotificationOutput>('/execute', {
-        method: 'POST',
-        body: JSON.stringify({
-          resourceType: 'workflow',
-          resourceId: 'email-notification',
-          input
-        })
-      })
-    }
-  })
-}
-```
-
-Usage in a component:
-
-```tsx
-// ui/src/features/notifications/components/SendNotificationButton.tsx
-import { useSendEmailNotification } from '../hooks/useSendEmailNotification'
-
-function SendNotificationButton() {
-  const { mutate, isPending, isSuccess } = useSendEmailNotification()
-
-  return (
-    <Button
-      loading={isPending}
-      onClick={() =>
-        mutate({
-          recipientEmail: 'user@example.com',
-          recipientName: 'Jane Smith',
-          subject: 'Your request is ready',
-          body: 'Hi Jane, your workflow has completed.',
-          category: 'operations'
-        })
-      }
-    >
-      Send Notification
-    </Button>
-  )
-}
-```
-
-For async execution (long-running workflows), use `/execute-async` instead:
-
-```typescript
-return apiRequest<{ executionId: string }>('/execute-async', {
-  method: 'POST',
-  body: JSON.stringify({
-    resourceType: 'workflow',
-    resourceId: 'email-notification',
-    input
-  })
-})
-// Poll /executions/email-notification/:executionId for status
-```
-
-### (b) Direct SDK dispatch (CLI or scripts)
-
-From the project root, use the platform CLI for manual invocations, testing, and scripting:
-
-```bash
-# Describe the schema before executing
-pnpm exec elevasis describe Elevasis/email-notification
-
-# Execute synchronously
-pnpm exec elevasis exec Elevasis/email-notification --input '{
-  "recipientEmail": "user@example.com",
-  "recipientName": "Jane Smith",
-  "subject": "Hello",
-  "body": "Hi Jane, this is a test notification."
-}'
-
-# Execute asynchronously (for long-running workflows)
-pnpm exec elevasis exec Elevasis/email-notification --async --input '{...}'
-
-# View a specific execution
-pnpm exec elevasis execution Elevasis/email-notification <executionId>
-```
-
-The `--prod` flag targets `https://api.elevasis.io` and goes **before** the command:
-
-```bash
-pnpm exec elevasis --prod exec Elevasis/email-notification --input '{...}'
-```
-
----
-
-## 4. Registry Pattern
-
-Workflows are discovered through `operations/src/index.ts`, which exports a `DeploymentSpec` as its default export.
-
-**Pattern:** each feature group in `operations/src/` has its own exports barrel. The top-level spec spreads all groups:
-
-```
-operations/src/
-  index.ts                          # Top-level DeploymentSpec -- never add workflows here directly
-  example/
-    index.ts                        # export const workflows = [echo]; export const agents = []
-    echo.ts                         # WorkflowDefinition for 'echo'
-  email-notification/
-    exports.ts                      # export const workflows = [emailNotification]; export const agents = []
-    index.ts                        # WorkflowDefinition for 'email-notification'
-```
-
-Top-level registry (`operations/src/index.ts`):
-
-```typescript
-import type { DeploymentSpec } from '@elevasis/sdk'
-import * as example from './example/index.js'
-import * as emailNotification from './email-notification/exports.js'
-
-const org: DeploymentSpec = {
-  version: '0.1.0',
-  workflows: [...example.workflows, ...emailNotification.workflows],
-  agents: [...example.agents, ...emailNotification.agents]
-}
-export default org
-```
-
-Feature group barrel (e.g., `email-notification/exports.ts`):
-
-```typescript
-import { emailNotification } from './index.js'
-import type { WorkflowDefinition } from '@elevasis/sdk'
-
-export const workflows: WorkflowDefinition[] = [emailNotification]
-export const agents: never[] = []
-```
-
-**Adding a new workflow:**
-
-1. Create `operations/src/<feature>/index.ts` with the `WorkflowDefinition`.
-2. Create `operations/src/<feature>/exports.ts` with `workflows` and `agents` arrays.
-3. Import the group barrel in `operations/src/index.ts` and spread into `workflows`/`agents`.
-4. Run `pnpm -C operations check` to validate, then `pnpm -C operations deploy` to publish.
-
-**Note:** Use `.js` extensions in imports even though the source is TypeScript. The TypeScript compiler and esbuild bundler both require this for ESM interoperability.
+---
+title: Workflow Recipes
+description: Anatomy of a workflow, adapter usage, and trigger patterns -- runnable email-notification example replaces the trivial echo workflow. Resolves eval score 2/5 on workflow authoring.
+---
+
+# Workflow Recipes
+
+`🟢 Stable` -- Use these patterns as-is against `@elevasis/sdk ^1.4.0`.
+
+---
+
+## 1. Anatomy of a Workflow
+
+Every workflow is a `WorkflowDefinition` object with four top-level keys: `config`, `contract`, `steps`, and `entryPoint`. The `email-notification` workflow at `operations/src/email-notification/index.ts` is used as the running example throughout this section.
+
+### Config
+
+```typescript
+config: {
+  resourceId: 'email-notification', // Unique ID -- used in API calls and CLI
+  name: 'Email Notification',       // Human-readable display name
+  type: 'workflow',                  // Always 'workflow' (vs 'agent')
+  description: 'Sends a notification email to a user...',
+  version: '1.0.0',                  // Bump on contract changes
+  status: 'dev'                      // 'dev' or 'prod'
+}
+```
+
+- `resourceId` is the stable identifier used by `pnpm exec elevasis exec` and `/execute` API calls.
+- Bump `version` whenever you change `contract.inputSchema` or `contract.outputSchema`.
+
+### Contract
+
+```typescript
+// foundations/types/index.ts -- shared with frontend
+export const emailNotificationInputSchema = z.object({
+  recipientEmail: z.string().email(),
+  recipientName: z.string().min(1),
+  subject: z.string().min(1).max(200),
+  body: z.string().min(1).max(10000),
+  category: z.string().min(1).default('operations'),
+  actionUrl: z.string().url().optional()
+})
+
+export const emailNotificationOutputSchema = z.object({
+  delivered: z.boolean(),
+  notificationId: z.string().optional(),
+  summary: z.string()
+})
+
+export type EmailNotificationInput = z.infer<typeof emailNotificationInputSchema>
+export type EmailNotificationOutput = z.infer<typeof emailNotificationOutputSchema>
+```
+
+```typescript
+// operations/src/email-notification/index.ts
+import { emailNotificationInputSchema, emailNotificationOutputSchema } from '@foundation/types'
+
+contract: {
+  inputSchema: emailNotificationInputSchema,
+  outputSchema: emailNotificationOutputSchema
+}
+```
+
+**Rules:**
+
+- Define schemas in `foundations/types/index.ts` -- never inline Zod schemas in workflow files.
+- Both runtimes (frontend and platform) import from `@foundation/types`, keeping validation consistent.
+- `@foundation/types` resolves to `foundations/types/index.ts` via the tsconfig path alias.
+
+**Entity-backed workflows:** for workflows that operate on a domain entity, reference the entity contract rather than redeclaring it.
+
+```typescript
+// foundations/types/index.ts
+import { BaseDealSchema } from '@elevasis/core/entities'
+import { DealSchema } from '@foundation/types/entities' // project-local extended version
+
+export const closeDealInputSchema = z.object({
+  deal: DealSchema,
+  closedReason: z.string()
+})
+
+export type CloseDealInput = z.infer<typeof closeDealInputSchema>
+```
+
+`DealSchema` is defined in `foundations/types/entities.ts` by extending `BaseDealSchema` with project-specific metadata. See [../recipes/extend-a-base-entity.md](../recipes/extend-a-base-entity.md) for the pattern.
+
+### Steps
+
+Each step is a `WorkflowStep` with: `id`, `name`, `description`, `handler`, `inputSchema`, `outputSchema`, and `next`.
+
+```typescript
+import { StepType } from '@elevasis/sdk'
+
+steps: {
+  validate: {
+    id: 'validate',
+    name: 'Validate Input',
+    description: 'Validates recipient and content parameters before sending',
+    handler: async (rawInput, context) => {
+      const input = rawInput as EmailNotificationInput
+      context.logger.info(`[validate] Checking recipient: ${input.recipientEmail}`)
+      // ... validation logic ...
+      return input          // Pass validated data to next step
+    },
+    inputSchema: emailNotificationInputSchema,
+    outputSchema: emailNotificationInputSchema,  // Passes full input through to next step
+    next: { type: StepType.LINEAR, target: 'notify' }
+  },
+  notify: {
+    id: 'notify',
+    name: 'Send Notification',
+    handler: async (rawInput, context) => {
+      // ...
+      return { delivered: true, summary: '...' }
+    },
+    inputSchema: emailNotificationInputSchema,
+    outputSchema: emailNotificationOutputSchema,
+    next: null  // Terminal step -- ends the workflow
+  }
+}
+```
+
+**Key rules:**
+
+- `next: null` marks a terminal step.
+- `next: { type: StepType.LINEAR, target: 'stepId' }` chains to another step.
+- Use `context.logger` -- never `console.log`. Platform captures `context.logger.*` only.
+- Cast `rawInput` to your input type: `const input = rawInput as EmailNotificationInput`.
+
+### Entrypoint
+
+```typescript
+entryPoint: 'validate'   // Must match a step id in the steps map
+```
+
+The platform starts execution here. For single-step workflows, `entryPoint` points to the only step (e.g., `echo` points to `'echo'`).
+
+### Optional: Interface Form
+
+Declare `interface.form` to auto-generate an execution form in AI Studio and Command Center:
+
+```typescript
+interface: {
+  form: {
+    title: 'Send Email Notification',
+    description: 'Sends a notification email to a user.',
+    fields: [
+      { name: 'recipientEmail', label: 'Recipient Email', type: 'text', required: true },
+      { name: 'body', label: 'Body', type: 'text', required: true }
+    ],
+    submitButton: { label: 'Send notification', loadingLabel: 'Sending...' }
+  }
+}
+```
+
+---
+
+## 2. Adapter Usage
+
+Adapters are typed wrappers over `platform.call()`. Import singletons from `@elevasis/sdk/worker`.
+
+### notifications
+
+Send a platform notification to the current user. `userId` and `organizationId` are injected server-side -- you never supply them.
+
+```typescript
+import { notifications } from '@elevasis/sdk/worker'
+
+await notifications.create({
+  category: 'operations',      // Any string: 'operations', 'delivery', 'acquisition', etc.
+  title: 'Workflow complete',
+  message: 'Your email notification was sent successfully.',
+  actionUrl: '/operations'     // Optional -- link the user can follow
+})
+```
+
+Available methods: `create`.
+
+### llm
+
+Generate text or structured output using a language model.
+
+```typescript
+import { llm } from '@elevasis/sdk/worker'
+
+const response = await llm.generate({
+  provider: 'anthropic',          // 'anthropic' | 'openai' | 'openrouter' | 'google'
+  model: 'claude-sonnet-4-5',
+  messages: [
+    { role: 'user', content: 'Summarize this email body: ' + input.body }
+  ]
+})
+
+const summary = response.output as string
+```
+
+For structured output, pass a JSON Schema as `responseSchema`:
+
+```typescript
+const response = await llm.generate({
+  provider: 'anthropic',
+  model: 'claude-sonnet-4-5',
+  messages: [{ role: 'user', content: 'Extract the key action from: ' + input.body }],
+  responseSchema: {
+    type: 'object',
+    properties: { action: { type: 'string' }, urgency: { type: 'string' } }
+  }
+})
+const { action, urgency } = response.output as { action: string; urgency: string }
+```
+
+Available methods: `generate`.
+
+### storage
+
+Upload and retrieve files scoped to the organization. All paths are automatically prefixed with the organization's storage prefix server-side.
+
+```typescript
+import { storage } from '@elevasis/sdk/worker'
+
+// Upload
+await storage.upload({
+  bucket: 'operations',
+  path: 'email-logs/2026-04-16/batch-01.json',
+  content: Buffer.from(JSON.stringify(logData)).toString('base64'),
+  contentType: 'application/json'
+})
+
+// Download
+const file = await storage.download({
+  bucket: 'operations',
+  path: 'email-logs/2026-04-16/batch-01.json'
+})
+
+// Signed URL for frontend access
+const { signedUrl } = await storage.createSignedUrl({
+  bucket: 'operations',
+  path: 'email-logs/2026-04-16/batch-01.json',
+  expiresIn: 3600
+})
+```
+
+Available methods: `upload`, `download`, `createSignedUrl`, `delete`, `list`.
+
+### scheduler
+
+Schedule future or recurring workflow executions.
+
+```typescript
+import { scheduler } from '@elevasis/sdk/worker'
+
+const schedule = await scheduler.createSchedule({
+  name: 'Daily email digest',
+  target: { resourceType: 'workflow', resourceId: 'email-notification' },
+  scheduleConfig: {
+    type: 'cron',
+    expression: '0 9 * * 1-5'  // 9am weekdays
+  }
+})
+
+context.logger.info(`[schedule] Created schedule: ${schedule.id}`)
+```
+
+Available methods: `createSchedule`, `updateAnchor`, `deleteSchedule`, `getSchedule`, `listSchedules`, `cancelSchedule`, `cancelSchedulesByMetadata`, `cancelScheduleByIdempotencyKey`, `findByIdempotencyKey`, `deleteScheduleByIdempotencyKey`.
+
+**Note on other adapters:** Integration adapters (`createResendAdapter`, `createAttioAdapter`, etc.) follow a factory pattern -- bind a credential once, use the instance for all calls:
+
+```typescript
+import { createResendAdapter } from '@elevasis/sdk/worker'
+
+const resend = createResendAdapter('my-resend-credential')
+await resend.sendEmail({
+  to: input.recipientEmail,
+  subject: input.subject,
+  html: `<p>${input.body}</p>`
+})
+```
+
+See `operations/node_modules/@elevasis/sdk/reference/` for the full adapter reference.
+
+---
+
+## 3. Trigger Patterns from Frontend
+
+### (a) API call via `useApiClient`
+
+Use this pattern in React components and hooks. `apiRequest` automatically attaches the auth token and org context.
+
+```typescript
+// ui/src/features/notifications/hooks/useSendEmailNotification.ts
+import { useMutation } from '@tanstack/react-query'
+import { useApiClient } from '@/lib/hooks/useApiClient'
+import type { EmailNotificationInput, EmailNotificationOutput } from '@foundation/types'
+
+export function useSendEmailNotification() {
+  const { apiRequest } = useApiClient()
+
+  return useMutation({
+    mutationFn: async (input: EmailNotificationInput) => {
+      return apiRequest<EmailNotificationOutput>('/execute', {
+        method: 'POST',
+        body: JSON.stringify({
+          resourceType: 'workflow',
+          resourceId: 'email-notification',
+          input
+        })
+      })
+    }
+  })
+}
+```
+
+Usage in a component:
+
+```tsx
+// ui/src/features/notifications/components/SendNotificationButton.tsx
+import { useSendEmailNotification } from '../hooks/useSendEmailNotification'
+
+function SendNotificationButton() {
+  const { mutate, isPending, isSuccess } = useSendEmailNotification()
+
+  return (
+    <Button
+      loading={isPending}
+      onClick={() =>
+        mutate({
+          recipientEmail: 'user@example.com',
+          recipientName: 'Jane Smith',
+          subject: 'Your request is ready',
+          body: 'Hi Jane, your workflow has completed.',
+          category: 'operations'
+        })
+      }
+    >
+      Send Notification
+    </Button>
+  )
+}
+```
+
+For async execution (long-running workflows), use `/execute-async` instead:
+
+```typescript
+return apiRequest<{ executionId: string }>('/execute-async', {
+  method: 'POST',
+  body: JSON.stringify({
+    resourceType: 'workflow',
+    resourceId: 'email-notification',
+    input
+  })
+})
+// Poll /executions/email-notification/:executionId for status
+```
+
+### (b) Direct SDK dispatch (CLI or scripts)
+
+From the project root, use the platform CLI for manual invocations, testing, and scripting:
+
+```bash
+# Describe the schema before executing
+pnpm exec elevasis describe Elevasis/email-notification
+
+# Execute synchronously
+pnpm exec elevasis exec Elevasis/email-notification --input '{
+  "recipientEmail": "user@example.com",
+  "recipientName": "Jane Smith",
+  "subject": "Hello",
+  "body": "Hi Jane, this is a test notification."
+}'
+
+# Execute asynchronously (for long-running workflows)
+pnpm exec elevasis exec Elevasis/email-notification --async --input '{...}'
+
+# View a specific execution
+pnpm exec elevasis execution Elevasis/email-notification <executionId>
+```
+
+The `--prod` flag targets `https://api.elevasis.io` and goes **before** the command:
+
+```bash
+pnpm exec elevasis --prod exec Elevasis/email-notification --input '{...}'
+```
+
+---
+
+## 4. Registry Pattern
+
+Workflows are discovered through `operations/src/index.ts`, which exports a `DeploymentSpec` as its default export.
+
+**Pattern:** each feature group in `operations/src/` has its own exports barrel. The top-level spec spreads all groups:
+
+```
+operations/src/
+  index.ts                          # Top-level DeploymentSpec -- never add workflows here directly
+  example/
+    index.ts                        # export const workflows = [echo]; export const agents = []
+    echo.ts                         # WorkflowDefinition for 'echo'
+  email-notification/
+    exports.ts                      # export const workflows = [emailNotification]; export const agents = []
+    index.ts                        # WorkflowDefinition for 'email-notification'
+```
+
+Top-level registry (`operations/src/index.ts`):
+
+```typescript
+import type { DeploymentSpec } from '@elevasis/sdk'
+import * as example from './example/index.js'
+import * as emailNotification from './email-notification/exports.js'
+
+const org: DeploymentSpec = {
+  version: '0.1.0',
+  workflows: [...example.workflows, ...emailNotification.workflows],
+  agents: [...example.agents, ...emailNotification.agents]
+}
+export default org
+```
+
+Feature group barrel (e.g., `email-notification/exports.ts`):
+
+```typescript
+import { emailNotification } from './index.js'
+import type { WorkflowDefinition } from '@elevasis/sdk'
+
+export const workflows: WorkflowDefinition[] = [emailNotification]
+export const agents: never[] = []
+```
+
+**Adding a new workflow:**
+
+1. Create `operations/src/<feature>/index.ts` with the `WorkflowDefinition`.
+2. Create `operations/src/<feature>/exports.ts` with `workflows` and `agents` arrays.
+3. Import the group barrel in `operations/src/index.ts` and spread into `workflows`/`agents`.
+4. Run `pnpm -C operations check` to validate, then `pnpm -C operations deploy` to publish.
+
+**Note:** Use `.js` extensions in imports even though the source is TypeScript. The TypeScript compiler and esbuild bundler both require this for ESM interoperability.