@elevasis/sdk 1.44.2 → 1.45.0

package/reference/scaffold/recipes/extend-a-base-entity.md

@@ -1,143 +1,159 @@
----
-title: Extend a Base Entity
-description: Add project-specific metadata to the canonical entity shapes (Project, Deal, Company, etc.) from @elevasis/core/entities using the TMeta extension slot.
----
+---
+title: Extend a Base Entity
+description: Add project-specific metadata to the canonical entity shapes (Project, Deal, Company, etc.) from @elevasis/core/entities using the TMeta extension slot.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-# Extend a Base Entity
-
-Workflows and UI features often operate on domain entities such as projects, deals, companies, or contacts. Rather than each project declaring its own shape from scratch, `@elevasis/core/entities` provides typed base interfaces generic over a `<TMeta>` slot. External projects extend these to add project-specific fields while keeping the canonical shape stable and interoperable with platform tooling.
-
-The canonical demo lives in `core/types/entities.ts` of any scaffold project.
-
----
-
-## Available Base Entities
-
-Each entity ships as a TypeScript interface, a Zod schema, and an Input type:
-
-| Set                                                            | Description                                 |
-| -------------------------------------------------------------- | ------------------------------------------- |
-| `BaseProject` / `BaseProjectSchema` / `BaseProjectInput`       | Client or internal project record           |
-| `BaseMilestone` / `BaseMilestoneSchema` / `BaseMilestoneInput` | Milestone within a project                  |
-| `BaseTask` / `BaseTaskSchema` / `BaseTaskInput`                | Discrete task within a project or milestone |
-| `BaseDeal` / `BaseDealSchema` / `BaseDealInput`                | Sales or partnership deal record            |
-| `BaseCompany` / `BaseCompanySchema` / `BaseCompanyInput`       | Company / account record                    |
-| `BaseContact` / `BaseContactSchema` / `BaseContactInput`       | Individual contact record                   |
-
-All imports come from `@elevasis/core/entities`.
-
----
-
-## Recipe 1 -- Extend a base entity with custom metadata
-
-Place this in `core/types/entities.ts`. This is the primary pattern -- the scaffold template ships this exact example.
-
-```ts
-import { z } from 'zod'
-import type { BaseProject, BaseDeal } from '@elevasis/core/entities'
-import { BaseProjectSchema, BaseDealSchema } from '@elevasis/core/entities'
-
-// -- Project: extending metadata on a base entity --
-
-export const ProjectMetaSchema = z.object({
-  budget: z.number().nonnegative(),
-  clientPriority: z.enum(['low', 'medium', 'high'])
-})
-
-export type ProjectMeta = z.infer<typeof ProjectMetaSchema>
-
-export const ProjectSchema = BaseProjectSchema.extend({ metadata: ProjectMetaSchema })
-
-export type Project = BaseProject<ProjectMeta>
-```
-
-Key points:
-
-- `BaseProjectSchema.extend({ metadata: ... })` merges your metadata Zod schema into the validated shape. Zod handles the rest.
-- `BaseProject<ProjectMeta>` infers the TypeScript type with your metadata typed correctly.
-- Only the `metadata` field is extended -- all other base fields (`id`, `organizationId`, `name`, `status`, `createdAt`, `updatedAt`, etc.) are inherited unchanged.
-- This file is the single source of truth for entity shapes across `core/`, `operations/`, and `ui/`.
-
----
-
-## Recipe 2 -- Use a base entity as-is
-
-When the base shape covers everything the project needs, skip the extension entirely:
-
-```ts
-import type { BaseDeal } from '@elevasis/core/entities'
-import { BaseDealSchema } from '@elevasis/core/entities'
-
-export const DealSchema = BaseDealSchema
-
-export type Deal = BaseDeal
-```
-
-`BaseDeal` without a type argument defaults `TMeta` to an empty object (`{}`), which Zod validates as `z.object({})`. Use this path when the project has no per-deal custom fields -- you still get the canonical shape and full Zod validation for free.
-
----
-
-## Recipe 3 -- Reference entity types from a workflow input schema
-
-Workflows that operate on projects or deals should reference the project-local entity types rather than redeclaring the shape. Add this to `operations/src/<workflow>/workflow.ts`:
-
-```ts
-import { z } from 'zod'
-import type { WorkflowDefinition } from '@elevasis/sdk'
-import { ProjectSchema } from '@core/types/entities'
-
-export const myWorkflow: WorkflowDefinition = {
-  id: 'my-workflow',
-  inputSchema: z.object({
-    project: ProjectSchema,
-    notes: z.string().optional()
-  }),
-  // ...
-}
-```
-
-The `@core/*` alias maps to the `core/` workspace package. This keeps entity contracts in one place and ensures the workflow input type matches whatever the UI passes as the execution payload.
-
----
-
-## Recipe 4 -- Reference entity types from the UI
-
-UI components accept entity types directly in props. The entity type flows from the `core` package through the component into the workflow execution payload:
-
-```tsx
-import type { Project } from '@core/types/entities'
-
-interface ProjectCardProps {
-  project: Project
-  onExecute?: (project: Project) => void
-}
-
-export function ProjectCard({ project, onExecute }: ProjectCardProps) {
-  return (
-    <button onClick={() => onExecute?.(project)}>
-      Run workflow for {project.name}
-    </button>
-  )
-}
-```
-
-When wiring this to a `RunResourceButton`, the entity instance becomes the workflow input. See UI Recipes recipe 6 (`Execute a Resource from a Surface`) at `../ui/recipes.md` for the end-to-end pattern where the entity type flows into a resource execution via `RunResourceButton`.
-
----
-
-## Verification
-
-- **Test core contracts:** `pnpm -C core test` runs the Vitest suite. The template ships `core/types/entities.test.ts` as a working smoke-check -- it `safeParse`s a valid project (expects success) and an invalid one (expects failure). Run this after any schema change.
-- **Round-trip safeParse:** Call `ProjectSchema.safeParse(candidateObject)` in a test or REPL to confirm the Zod shape accepts the data your workflows and UI will produce.
-- **Cross-package type check:** `pnpm -C ui build` will surface any TypeScript errors if a UI component or hook passes a mismatched entity type to a workflow input.
-
----
-
-## Cross-references
-
-- [./add-a-resource.md](./add-a-resource.md) -- resource authoring that consumes entity types in `inputSchema`
-- [../ui/recipes.md](../ui/recipes.md) recipe 6 -- execute a resource from a surface, with entity-typed input via `RunResourceButton`
-- [../reference/contracts.md](../reference/contracts.md) -- auto-generated TypeScript contract shapes for all Organization OS types
+
+# Extend a Base Entity
+
+Workflows and UI features often operate on domain entities such as projects, deals, companies, or contacts. Rather than each project declaring its own shape from scratch, `@elevasis/core/entities` provides typed base interfaces generic over a `<TMeta>` slot. External projects extend these to add project-specific fields while keeping the canonical shape stable and interoperable with platform tooling.
+
+The canonical demo lives in `core/types/entities.ts` of any scaffold project.
+
+---
+
+## Available Base Entities
+
+Each entity ships as a TypeScript interface, a Zod schema, and an Input type:
+
+| Set                                                            | Description                                 |
+| -------------------------------------------------------------- | ------------------------------------------- |
+| `BaseProject` / `BaseProjectSchema` / `BaseProjectInput`       | Client or internal project record           |
+| `BaseMilestone` / `BaseMilestoneSchema` / `BaseMilestoneInput` | Milestone within a project                  |
+| `BaseTask` / `BaseTaskSchema` / `BaseTaskInput`                | Discrete task within a project or milestone |
+| `BaseDeal` / `BaseDealSchema` / `BaseDealInput`                | Sales or partnership deal record            |
+| `BaseCompany` / `BaseCompanySchema` / `BaseCompanyInput`       | Company / account record                    |
+| `BaseContact` / `BaseContactSchema` / `BaseContactInput`       | Individual contact record                   |
+
+All imports come from `@elevasis/core/entities`.
+
+---
+
+## Recipe 1 -- Extend a base entity with custom metadata
+
+Place this in `core/types/entities.ts`. This is the primary pattern -- the scaffold template ships this exact example.
+
+```ts
+import { z } from 'zod'
+import type { BaseProject, BaseDeal } from '@elevasis/core/entities'
+import { BaseProjectSchema, BaseDealSchema } from '@elevasis/core/entities'
+
+// -- Project: extending metadata on a base entity --
+
+export const ProjectMetaSchema = z.object({
+  budget: z.number().nonnegative(),
+  clientPriority: z.enum(['low', 'medium', 'high'])
+})
+
+export type ProjectMeta = z.infer<typeof ProjectMetaSchema>
+
+export const ProjectSchema = BaseProjectSchema.extend({ metadata: ProjectMetaSchema })
+
+export type Project = BaseProject<ProjectMeta>
+```
+
+Key points:
+
+- `BaseProjectSchema.extend({ metadata: ... })` merges your metadata Zod schema into the validated shape. Zod handles the rest.
+- `BaseProject<ProjectMeta>` infers the TypeScript type with your metadata typed correctly.
+- Only the `metadata` field is extended -- all other base fields (`id`, `organizationId`, `name`, `status`, `createdAt`, `updatedAt`, etc.) are inherited unchanged.
+- This file is the single source of truth for entity shapes across `core/`, `operations/`, and `ui/`.
+
+---
+
+## Recipe 2 -- Use a base entity as-is
+
+When the base shape covers everything the project needs, skip the extension entirely:
+
+```ts
+import type { BaseDeal } from '@elevasis/core/entities'
+import { BaseDealSchema } from '@elevasis/core/entities'
+
+export const DealSchema = BaseDealSchema
+
+export type Deal = BaseDeal
+```
+
+`BaseDeal` without a type argument defaults `TMeta` to an empty object (`{}`), which Zod validates as `z.object({})`. Use this path when the project has no per-deal custom fields -- you still get the canonical shape and full Zod validation for free.
+
+---
+
+## Recipe 3 -- Reference entity types from a workflow input schema
+
+Workflows that operate on projects or deals should reference the project-local entity types rather than redeclaring the shape. Add this to `operations/src/<workflow>/workflow.ts`:
+
+<!-- doc-snippet:skip: illustrative excerpt -- `resourceDescriptors` names the project's own resource-descriptors export, and `steps` is shown unimported for readability -->
+
+```ts
+import { z } from 'zod'
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { ProjectSchema } from '@core/types/entities'
+import { resourceDescriptors } from '@core/config/organization-model'
+
+const inputSchema = z.object({
+  project: ProjectSchema,
+  notes: z.string().optional()
+})
+const outputSchema = z.object({ ok: z.boolean() })
+
+export const myWorkflow: WorkflowDefinition = {
+  config: {
+    resource: resourceDescriptors.myWorkflow,
+    resourceId: resourceDescriptors.myWorkflow.id,
+    name: 'My Workflow',
+    description: 'Runs against a project entity.',
+    type: resourceDescriptors.myWorkflow.kind,
+    version: '1.0.0',
+    status: 'dev',
+    category: 'production'
+  },
+  contract: { inputSchema, outputSchema },
+  steps,
+  entryPoint: 'run'
+}
+```
+
+The `@core/*` alias maps to the `core/` workspace package. This keeps entity contracts in one place and ensures the workflow input type matches whatever the UI passes as the execution payload.
+
+---
+
+## Recipe 4 -- Reference entity types from the UI
+
+UI components accept entity types directly in props. The entity type flows from the `core` package through the component into the workflow execution payload:
+
+```tsx
+import type { Project } from '@core/types/entities'
+
+interface ProjectCardProps {
+  project: Project
+  onExecute?: (project: Project) => void
+}
+
+export function ProjectCard({ project, onExecute }: ProjectCardProps) {
+  return (
+    <button onClick={() => onExecute?.(project)}>
+      Run workflow for {project.name}
+    </button>
+  )
+}
+```
+
+When wiring this to a `RunResourceButton`, the entity instance becomes the workflow input. See UI Recipes recipe 6 (`Execute a Resource from a Surface`) at `../ui/recipes.md` for the end-to-end pattern where the entity type flows into a resource execution via `RunResourceButton`.
+
+---
+
+## Verification
+
+- **Test core contracts:** `pnpm -C core test` runs the Vitest suite. The template ships `core/types/entities.test.ts` as a working smoke-check -- it `safeParse`s a valid project (expects success) and an invalid one (expects failure). Run this after any schema change.
+- **Round-trip safeParse:** Call `ProjectSchema.safeParse(candidateObject)` in a test or REPL to confirm the Zod shape accepts the data your workflows and UI will produce.
+- **Cross-package type check:** `pnpm -C ui build` will surface any TypeScript errors if a UI component or hook passes a mismatched entity type to a workflow input.
+
+---
+
+## Cross-references
+
+- [./add-a-resource.md](./add-a-resource.md) -- resource authoring that consumes entity types in `inputSchema`
+- [../ui/recipes.md](../ui/recipes.md) recipe 6 -- execute a resource from a surface, with entity-typed input via `RunResourceButton`
+- [../reference/contracts.md](../reference/contracts.md) -- auto-generated TypeScript contract shapes for all Organization OS types

package/reference/scaffold/recipes/extend-crm.md

@@ -29,15 +29,15 @@ CRM is a layered platform surface, not one component:
 
 ## Decision Table
 
-| User wants                                                                       | Start here                                                                                          | Notes                                                                                                                                                             |
-| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Change CRM System availability, labels, pipeline stages, resource descriptors, or API readiness | `core/config/organization-model.ts`                                                                 | Treat this as Organization OS work. Mark `sales.crm.apiInterface` active only when scoped CRM resources and ontology are ready for API-backed actions.             |
-| Add CRM sidebar nav or a CRM route                                               | `@elevasis/ui/features/crm` and `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` | Prefer manifest/sidebar composition. Do not fork shared source first.                                                                                             |
-| Wrap a shared CRM page with project chrome                                       | `DealsListPage`, `DealDetailPage`, `CrmOverview` from `@elevasis/ui/features/crm`                   | Keep route files thin and put project-specific logic in local feature modules.                                                                                    |
-| Build a custom deal page                                                         | `useDealDetail`, `useDealNotes`, `useDealTasks`, `useExecuteAction` from `@elevasis/ui/hooks`       | Use hooks for platform data and compose your own UI.                                                                                                              |
-| Add, hide, or replace deal action buttons                                        | [customize-crm-actions.md](customize-crm-actions.md)                                                | Start with the shared `crmActions` provider path; use project-owned UI when a custom workflow path is outside platform-known/default action dispatch constraints. |
-| Read or mutate CRM data inside a workflow                                        | `crm` or `acqDb` from `@elevasis/sdk/worker`                                                        | `organizationId` is injected server-side by the platform dispatcher. Do not pass it from workflow code.                                                           |
-| Add a new persisted CRM column or table                                          | Platform/API migration work, not just scaffold work                                                 | Update DB, core schemas/types, API service/handlers, hooks, docs, and scaffold contracts together.                                                                |
+| User wants                                                                                      | Start here                                                                                                     | Notes                                                                                                                                                             |
+| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Change CRM System availability, labels, pipeline stages, resource descriptors, or API readiness | `core/config/organization-model.ts`                                                                            | Treat this as Organization OS work. Mark `sales.crm.apiInterface` active only when scoped CRM resources and ontology are ready for API-backed actions.            |
+| Add CRM sidebar nav or a CRM route                                                              | `@elevasis/ui/features/crm` and `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` | Prefer manifest/sidebar composition. Do not fork shared source first.                                                                                             |
+| Wrap a shared CRM page with project chrome                                                      | `DealsListPage`, `DealDetailPage`, `CrmOverview` from `@elevasis/ui/features/crm`                              | Keep route files thin and put project-specific logic in local feature modules.                                                                                    |
+| Build a custom deal page                                                                        | `useDealDetail`, `useDealNotes`, `useDealTasks`, `useExecuteAction` from `@elevasis/ui/hooks`                  | Use hooks for platform data and compose your own UI.                                                                                                              |
+| Add, hide, or replace deal action buttons                                                       | [customize-crm-actions.md](customize-crm-actions.md)                                                           | Start with the shared `crmActions` provider path; use project-owned UI when a custom workflow path is outside platform-known/default action dispatch constraints. |
+| Read or mutate CRM data inside a workflow                                                       | `crm` or `acqDb` from `@elevasis/sdk/worker`                                                                   | `organizationId` is injected server-side by the platform dispatcher. Do not pass it from workflow code.                                                           |
+| Add a new persisted CRM column or table                                                         | Platform/API migration work, not just scaffold work                                                            | Update DB, core schemas/types, API service/handlers, hooks, docs, and scaffold contracts together.                                                                |
 
 ## Published CRM Surfaces
 
@@ -162,6 +162,8 @@ export function CustomDealWorkspace({ dealId }: { dealId: string }) {
 
 Inside deployed workflows, use worker adapters instead of browser hooks or direct database access:
 
+<!-- doc-snippet:skip: illustrative excerpt -- `resourceDescriptors` names the project's own resource-descriptors export -->
+
 ```ts
 // operations/src/sales/follow-up-stale-deals.ts
 import type { WorkflowDefinition } from '@elevasis/sdk'
@@ -182,6 +184,7 @@ export const followUpStaleDealsWorkflow: WorkflowDefinition = {
     resource: resourceDescriptors.followUpStaleDeals,
     resourceId: resourceDescriptors.followUpStaleDeals.id,
     name: 'Follow Up Stale Deals',
+    description: 'Creates follow-up tasks for deals that have gone stale in a stage.',
     type: resourceDescriptors.followUpStaleDeals.kind,
     version: '1.0.0',
     status: 'dev',
@@ -191,10 +194,12 @@ export const followUpStaleDealsWorkflow: WorkflowDefinition = {
     followUp: {
       id: 'followUp',
       name: 'Follow Up',
+      description: 'Lists stale deals in the target stage and creates a follow-up task for each.',
       inputSchema,
       outputSchema,
       next: null,
-      handler: async (input) => {
+      handler: async (rawInput, context) => {
+        const input = rawInput as z.infer<typeof inputSchema>
         const deals = await crm.listDeals({ stage: input.stage })
 
         for (const deal of deals) {
@@ -245,7 +250,7 @@ Keep these boundaries straight:
 Run the checks for the surfaces you touched:
 
 ```bash
-pnpm -C ui run check
+pnpm -C ui run check-types
 pnpm -C operations run check
 pnpm -C operations exec elevasis-sdk check
 ```

package/reference/scaffold/recipes/extend-lead-gen.md

@@ -34,7 +34,7 @@ Lead gen is a layered platform surface, not one component. Shared packages own s
 | User wants                                                                                                                                          | Start here                                                                                                                                      | Notes                                                                                                                                                                                              |
 | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Change lead-gen System availability, labels, quick access, stage catalogs, build templates, workflow actions, resources, topology, or API readiness | `core/config/organization-model.ts`                                                                                                             | Treat this as Organization OS work. Tenant projects own these values. Mark `sales.lead-gen.apiInterface` active only when scoped resources and ontology are ready for API-backed lead-gen actions. |
-| Add lead-gen sidebar nav or a lead-gen route                                                                                                        | `@elevasis/ui/features/lead-gen` and `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`                                        | Prefer manifest/sidebar composition. Do not fork shared source first.                                                                                                                              |
+| Add lead-gen sidebar nav or a lead-gen route                                                                                                        | `@elevasis/ui/features/lead-gen` and `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`                             | Prefer manifest/sidebar composition. Do not fork shared source first.                                                                                                                              |
 | Wrap a shared lead-gen page with project chrome                                                                                                     | `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `ListBuilderPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`            | Keep route files thin and put project-specific behavior in local feature modules.                                                                                                                  |
 | Build a custom campaign/list workspace                                                                                                              | `ListBuilderPage`, `useLists`, `useList`, `useListProgress`, `useListExecutions`, `useWorkflowExecution`, `useExecutionSSE` from `@elevasis/ui` | Use the shared builder when possible; otherwise compose hooks for platform data and workflow execution.                                                                                            |
 | Add or change list-builder workflow buttons/forms                                                                                                   | `ui/src/config/listActions.ts` plus `ElevasisUIProvider listActions={listActions}` / `createElevasisApp({ listActions })`                       | The shared UI owns the registry contract. The project owns workflow ids, action keys, Zod schemas, layouts, and default inputs.                                                                    |
@@ -209,7 +209,7 @@ Available field component variants: `textinput`, `textarea`, `numberinput`, `swi
 ```tsx
 import * as z from 'zod'
 import { leadGenManifest, type ListBuilderRegistry } from '@elevasis/ui/features/lead-gen'
-import type { StepConfigLayout } from '@elevasis/ui/components/forms'
+import type { StepConfigLayout } from '@elevasis/ui/components'
 import { ElevasisSystemsProvider, ElevasisUIProvider } from '@elevasis/ui/provider'
 import { organizationModel, resourceDescriptors } from '@core/config/organization-model'
 
@@ -351,6 +351,8 @@ Inside deployed workflows, use worker adapters instead of browser hooks or direc
 
 External projects should define workflow input/output schemas in `@shared/types`; the example below assumes those shared schemas already exist.
 
+<!-- doc-snippet:skip: illustrative excerpt -- `@shared/types` is a project-local alias for the reader's own shared schema module, `resourceDescriptors` names the project's own resource-descriptors export, and `z` (zod) is shown unimported -->
+
 ```ts
 // operations/src/sales/qualify-list.ts
 import type { WorkflowDefinition } from '@elevasis/sdk'
@@ -363,6 +365,7 @@ export const qualifyListWorkflow: WorkflowDefinition = {
     resource: resourceDescriptors.qualifyList,
     resourceId: resourceDescriptors.qualifyList.id,
     name: 'Qualify List',
+    description: 'Marks list contacts as verified based on qualification checks.',
     type: resourceDescriptors.qualifyList.kind,
     version: '1.0.0',
     status: 'dev',
@@ -372,10 +375,12 @@ export const qualifyListWorkflow: WorkflowDefinition = {
     qualify: {
       id: 'qualify',
       name: 'Qualify',
+      description: 'Fetches list contacts and marks each verified.',
       inputSchema: qualifyListInputSchema,
       outputSchema: qualifyListOutputSchema,
       next: null,
-      handler: async (input, context) => {
+      handler: async (rawInput, context) => {
+        const input = rawInput as z.infer<typeof qualifyListInputSchema>
         const config = await list.getConfig({ listId: input.listId })
         const contacts = await acqDb.listContacts({ listId: input.listId, limit: 100, offset: 0 })
 
@@ -490,7 +495,7 @@ export const organizationModel = {
 }
 ```
 
-`readinessContract.requiredObjects` and `requiredCatalogs` are arrays of ontology IDs owned by this system. The platform validates that each declared object type exists in the OM and that each declared catalog type has at least one entry. The `requiredKinds` field is reserved for future profile extensions; omit it today.
+`readinessContract.requiredObjects` and `requiredCatalogs` are arrays of ontology IDs owned by this system. The platform validates that each declared object type exists in the OM and that each declared catalog type has at least one entry. `requiredCatalogs` must declare at least one entry — an empty contract asserts nothing and is rejected.
 
 Built-in profile ids (`sales.lead-gen.api`, etc.) derive their requirements from platform code. If you use a built-in profile on a custom system, you do not need a `readinessContract`.
 
@@ -500,17 +505,21 @@ The `lookupReadinessProfile`, `registerReadinessProfile`, and `isBuiltInReadines
 
 The export channel — ClickUp, CSV/XLSX file, platform push, or a custom destination — is an action + credential choice declared in your tenant OM. The platform owns the list-builder workflow primitive and the file storage adapters; you own which workflow id handles export and which credential it uses.
 
+<!-- doc-snippet:skip: illustrative excerpt -- `@shared/types` is a project-local alias for the reader's own shared schema module, and `buildCsvFromContacts` is a tenant-authored helper this recipe does not define -->
+
 ```ts
 // operations/src/sales/prospecting/export-list.ts
 import type { WorkflowDefinition } from '@elevasis/sdk'
-import { list, storage } from '@elevasis/sdk/worker'
+import { acqDb, list, storage } from '@elevasis/sdk/worker'
 import { exportListInputSchema, exportListOutputSchema } from '@shared/types'
+import { resourceDescriptors } from '@core/config/organization-model'
 
 export const exportListWorkflow: WorkflowDefinition = {
   config: {
     resource: resourceDescriptors.exportList,
     resourceId: resourceDescriptors.exportList.id,
     name: 'Export List',
+    description: 'Exports list contacts to a CSV file in project storage.',
     type: 'workflow',
     version: '1.0.0',
     status: 'prod'
@@ -520,10 +529,13 @@ export const exportListWorkflow: WorkflowDefinition = {
     export: {
       id: 'export',
       name: 'Export',
+      description: 'Fetches list contacts, builds a CSV, and uploads it to storage.',
       inputSchema: exportListInputSchema,
       outputSchema: exportListOutputSchema,
       next: null,
-      handler: async (input, context) => {
+      handler: async (rawInput, context) => {
+        const input = rawInput as z.infer<typeof exportListInputSchema>
+
         // Fetch contacts from the acquisition substrate
         const contacts = await acqDb.listContacts({ listId: input.listId, limit: 5000, offset: 0 })
 
@@ -560,6 +572,8 @@ The `ListTelemetry.stageCounts` field is now a `Record<string, number>` — one
 
 To define custom stages, author them in the `catalogTypes` scope of your lead-gen system:
 
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
 ```ts
 ontology: {
   catalogTypes: {
@@ -582,6 +596,8 @@ ontology: {
 
 **`readinessTarget` — declaring the pipeline objective.** To tell the platform which stage is the "ready / next-focus" milestone for your pipeline, mark exactly one catalog entry with `readinessTarget: true`:
 
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
 ```ts
 entries: {
   'sourced':   { label: 'Sourced',   order: 10 },
@@ -597,6 +613,8 @@ The `LeadGenOverviewPage` uses this field to derive a "contacts ready for \<stag
 
 Point the `listBuilderWorkflow` factory at your tenant resource and step handlers. The factory validates `stageKey` inputs against your catalog at construction time, not at runtime:
 
+<!-- doc-snippet:skip: illustrative excerpt -- `resourceDescriptors` names the project's own resource-descriptors export, and `sourceCompaniesStep`/`enrichCompaniesStep`/`qualifyCompaniesStep` are the reader's own step handlers, not defined in this excerpt -->
+
 ```ts
 // operations/src/sales/prospecting/list-builder.ts
 import { listBuilderWorkflow } from '@elevasis/sdk/worker'
@@ -619,7 +637,7 @@ Register this workflow in `DeploymentSpec.workflows` alongside the export workfl
 Run the checks for the surfaces you touched:
 
 ```bash
-pnpm -C ui run check
+pnpm -C ui run check-types
 pnpm -C operations run check
 pnpm -C operations exec elevasis-sdk check
 ```