@elevasis/sdk 1.25.0 → 1.26.0

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

@@ -3,7 +3,7 @@
 
 ---
 title: Build and Extend Lead Gen
-description: Map the lead-gen platform primitives available to SDK projects: shared UI pages, sidebar composition, data hooks, list/member state, artifacts, workflow adapters, contracts, and org-model extension boundaries.
+description: Map the lead-gen platform primitives available to SDK projects: shared UI pages, provider-injected Organization Model config, data hooks, list/member state, artifacts, workflow adapters, contracts, and tenant-owned extension boundaries.
 ---
 
 # Build and Extend Lead Gen
@@ -19,42 +19,48 @@ Good trigger phrases:
 - "Read or update lead-gen lists from a workflow."
 - "Change the lead-gen lifecycle for this business."
 
-Lead gen is a layered platform surface, not one component:
-
-- **Organization OS:** prospecting semantics, System access, pipeline labels, and quick access live in the organization model.
-- **Shared UI:** lead-gen overview, lists, list detail, companies, contacts, sidebars, and drawer components live in `@elevasis/ui`.
-- **Headless hooks:** lists, companies, contacts, artifacts, list members, transitions, and derived actions live under `@elevasis/ui/hooks`.
-- **Acquisition substrate:** `acq_lists`, `acq_companies`, `acq_contacts`, `acq_artifacts`, list members, list companies, telemetry, and stateful transition shapes are exposed through generated contracts.
-- **Workflow adapters:** `acqDb` and `list` from `@elevasis/sdk/worker` let workflows read and mutate lead-gen data through platform tools.
-- **Contracts:** generated contract docs expose the current lead-gen shapes in `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`.
+Lead gen is a layered platform surface, not one component. Shared packages own shapes, readers, runtime mechanics, and reusable UI. Tenant projects own the values that make a list builder specific to a business.
+
+- **Organization OS:** prospecting semantics, System access, pipeline labels, quick access, stage catalogs, build templates, workflow actions, resources, and topology live in the tenant organization model.
+- **Shared UI:** lead-gen overview, lists, list detail, companies, contacts, sidebars, drawer components, `useLeadGenConfig`, and list-builder state derivation live in `@elevasis/ui`.
+- **Headless hooks:** lists, companies, contacts, artifacts, list members, transitions, and derived actions live under `@elevasis/ui/hooks`.
+- **Acquisition substrate:** `acq_lists`, `acq_companies`, `acq_contacts`, `acq_artifacts`, list members, list companies, telemetry, and stateful transition shapes are exposed through generated contracts.
+- **Core readers:** `getLeadGenStageCatalog`, `getAllBuildTemplates`, `getProspectingBuildTemplateOptions`, and `createBuildPlanSnapshotFromTemplateId` from `@elevasis/core` read caller-supplied Organization Model/template values. They do not ship tenant catalogs or default templates.
+- **Workflow adapters:** `acqDb`, `list`, and `listBuilderWorkflow` from `@elevasis/sdk/worker` let workflows read and mutate lead-gen data through platform tools.
+- **Contracts:** generated contract docs expose the current lead-gen shapes in `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`.
 
 ## Decision Table
 
 | User wants                                                                                              | Start here                                                                                                                                      | Notes                                                                                                           |
 | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| Change lead-gen System availability, labels, quick access, pipeline semantics, or resource descriptors | `core/config/organization-model.ts`                                                                                                             | Treat this as Organization OS work. Use the project's configure ceremony if available.                          |
-| Add lead-gen sidebar nav or a lead-gen route                                                            | `@elevasis/ui/features/lead-gen` and `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.         |
-| Render artifacts or list-member detail                                                                  | `LeadGenListDetailPage`, `useArtifacts`, `useCreateArtifact`, `useListMember`                                                                   | Artifacts are a substrate primitive. Keep vertical-specific rendering local until there are repeated use cases. |
-| Read or mutate lead-gen data inside a workflow                                                          | `acqDb` or `list` from `@elevasis/sdk/worker`                                                                                                   | `organizationId` is injected server-side by the platform dispatcher. Do not pass it from workflow code.         |
-| Add a new persisted lead-gen field, artifact kind, or transition API                                    | Platform/API migration work, not just scaffold work                                                                                             | Update DB, core schemas/types, API service/handlers, hooks, docs, and scaffold contracts together.              |
+| Change lead-gen System availability, labels, quick access, stage catalogs, build templates, workflow actions, resources, or topology | `core/config/organization-model.ts`                                                                                                             | Treat this as Organization OS work. Tenant projects own these values. Use the project's configure ceremony if available. |
+| Add lead-gen sidebar nav or a lead-gen route                                                            | `@elevasis/ui/features/lead-gen` and `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. |
+| Render artifacts or list-member detail                                                                  | `LeadGenListDetailPage`, `useArtifacts`, `useCreateArtifact`, `useListMember`                                                                   | Artifacts are a substrate primitive. Keep vertical-specific rendering local until there are repeated use cases. |
+| Read or mutate lead-gen data inside a workflow                                                          | `acqDb` or `list` from `@elevasis/sdk/worker`                                                                                                   | `organizationId` is injected server-side by the platform dispatcher. Do not pass it from workflow code.         |
+| Add a new persisted lead-gen field, artifact kind, or transition API                                    | Platform/API migration work, not just scaffold work                                                                                             | Update DB, core schemas/types, API service/handlers, hooks, docs, and scaffold contracts together.              |
 
 ## Published Lead-Gen Surfaces
 
 | Surface                                                                                                                                                      | Import from                      | Use for                                                                                                                                                                   |
 | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `leadGenManifest`, `LEAD_GEN_ITEMS`, `LeadGenSidebar`, `LeadGenSidebarTop`, `LeadGenSidebarMiddle`                                                           | `@elevasis/ui/features/lead-gen` | Feature registration and sidebar composition                                                                                                                              |
-| `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `ListBuilderPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`                         | `@elevasis/ui/features/lead-gen` | Shared lead-gen pages you can route to or wrap                                                                                                                            |
-| `ListActionsProvider`, `useListActions`, `ListBuilderWorkflow`, `ListBuilderRegistry`, `LeadGenActionKey`                                                    | `@elevasis/ui/features/lead-gen` | List Builder workflow registry, slot-based field contracts, and project-owned action wiring                                                                               |
-| `LeadGenRouteShell`, `LIST_TEMPLATE_OPTIONS`, `buildListConfig`                                                                                              | `@elevasis/ui/features/lead-gen` | Route shell helpers and list creation config helpers (contact/company detail surfaces are now `ContactDetailPage` / `CompanyDetailPage` from `@elevasis/ui/features/crm`) |
-| `useLists`, `useList`, `useListsTelemetry`, `useListProgress`, `useListExecutions`, `useCreateList`, `useUpdateList`, `useUpdateListConfig`, `useDeleteList` | `@elevasis/ui/hooks`             | Headless list and telemetry data access                                                                                                                                   |
+| `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `ListBuilderPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`                         | `@elevasis/ui/features/lead-gen` | Shared lead-gen pages you can route to or wrap                                                                                                                            |
+| `useLeadGenConfig`, `LeadGenBuildConfig`, build-state helpers                                                                                                  | `@elevasis/ui/features/lead-gen` | Provider-backed derivation of stage catalog, build templates, default build steps, default template id, and export workflow id                                             |
+| `ListActionsProvider`, `useListActions`, `ListBuilderWorkflow`, `ListBuilderRegistry`, `LeadGenActionKey`                                                    | `@elevasis/ui/features/lead-gen` | List Builder workflow registry, slot-based field contracts, and project-owned action wiring                                                                               |
+| `LeadGenRouteShell`                                                                                                                                            | `@elevasis/ui/features/lead-gen` | Route shell helper (contact/company detail surfaces are now `ContactDetailPage` / `CompanyDetailPage` from `@elevasis/ui/features/crm`)                                  |
+| `useLists`, `useList`, `useListsTelemetry`, `useListProgress`, `useListExecutions`, `useCreateList`, `useUpdateList`, `useUpdateListConfig`, `useDeleteList` | `@elevasis/ui/hooks`             | Headless list and telemetry data access                                                                                                                                   |
 | `useWorkflowExecution`, `useExecutionSSE`, `useAddCompaniesToList`, `useRemoveCompaniesFromList`, `useAddContactsToList`                                     | `@elevasis/ui/hooks`             | List Builder workflow triggering, live execution tailing, and list membership mutations                                                                                   |
 | `useCompanies`, `useCompany`, `useContacts`, `useContact`                                                                                                    | `@elevasis/ui/hooks`             | Acquisition company/contact data access                                                                                                                                   |
 | `useArtifacts`, `useCreateArtifact`, `useListMembers`, `useListMember`                                                                                       | `@elevasis/ui/hooks`             | Lead-gen substrate data access                                                                                                                                            |
 | `useTransitionList`, `useTransitionListMember`, `useTransitionListCompany`, `useDeriveActions`                                                               | `@elevasis/ui/hooks`             | Stateful transition mutations and contextual action derivation                                                                                                            |
-| `ElevasisUIProvider`, `ElevasisCoreProvider`, `useElevasisServices`                                                                                          | `@elevasis/ui/provider`          | Provider setup, API access, organization context, and `listActions` registry injection                                                                                    |
-| `acqDb`, `list`                                                                                                                                              | `@elevasis/sdk/worker`           | Workflow-side acquisition and list-scoped platform adapters                                                                                                               |
+| `ElevasisUIProvider`, `ElevasisCoreProvider`, `useElevasisServices`                                                                                          | `@elevasis/ui/provider`          | Provider setup, API access, organization context, and `listActions` registry injection                                                                                    |
+| `ElevasisSystemsProvider`, `ElevasisAuthenticatedShell`                                                                                                      | `@elevasis/ui/provider`, `@elevasis/ui/app` | Organization Model injection for system-aware surfaces such as lead-gen config, sidebar projection, and Organization OS views                                             |
+| `getLeadGenStageCatalog`, `getAllBuildTemplates`, `getProspectingBuildTemplateOptions`, `createBuildPlanSnapshotFromTemplateId`                              | `@elevasis/core`                 | Generic Organization Model and template readers. Supply tenant templates/model values from the project.                                                                   |
+| `listBuilderWorkflow`                                                                                                                                        | `@elevasis/sdk/worker`           | Generic list-builder workflow runtime for tenant-owned step handlers                                                                                                      |
+| `acqDb`, `list`                                                                                                                                              | `@elevasis/sdk/worker`           | Workflow-side acquisition and list-scoped platform adapters                                                                                                               |
 
 Read the generated contracts before changing typed boundaries:
 
@@ -137,7 +143,7 @@ function ListDetailRoute() {
 
 Use the same wrapping pattern for `LeadGenOverviewPage`, `LeadGenCompaniesPage`, and `LeadGenContactsPage`.
 
-For the real-time List Builder workspace, add a thin route that passes the route param into `ListBuilderPage`:
+For the real-time List Builder workspace, add a thin route that passes the route param into `ListBuilderPage`:
 
 ```tsx
 import { createFileRoute } from '@tanstack/react-router'
@@ -153,26 +159,65 @@ function ListBuilderRoute() {
 }
 ```
 
-Register project workflow actions at the provider boundary. The shared UI owns the contract; each project owns workflow ids, action keys, default inputs, and field components.
+Register project workflow actions at the provider boundary. The shared UI owns the contract; each project owns workflow ids, action keys, default inputs, and field components.
+
+The shared pages call `useLeadGenConfig()` internally. That hook reads the provider-injected `organizationModel` and derives:
+
+- `stageCatalog` from `getLeadGenStageCatalog(organizationModel)`
+- `buildTemplates` and `defaultBuildSteps` from `getAllBuildTemplates(organizationModel)`
+- `defaultBuildTemplateId` from the `sales.lead-gen` system config or first available template
+- `exportWorkflowId` from the lead-gen workflow resource whose action matches export semantics
+
+If the provider has no Organization Model, shared UI renders with empty config instead of falling back to Elevasis-owned defaults. A tenant that wants list creation and the build runner to be useful must provide lead-gen catalogs/templates/actions/resources/topology in `core/config/organization-model.ts`.
+
+In external projects, pass the local list-action registry through the app factory and the tenant Organization Model through the authenticated shell:
+
+```tsx
+// ui/src/main.tsx
+import { createElevasisApp } from '@elevasis/ui/app'
+import { listActions } from '@/config/listActions'
+
+const App = createElevasisApp({
+  listActions,
+  // other app config...
+})
+```
+
+```tsx
+// ui/src/routes/__root.tsx
+import { ElevasisAuthenticatedShell } from '@elevasis/ui/app'
+import { canonicalOrganizationModel } from '@core/config/organization-model'
+
+export function RootLayout() {
+  return (
+    <ElevasisAuthenticatedShell
+      systems={SYSTEM_MANIFESTS}
+      organizationModel={canonicalOrganizationModel}
+      // other shell config...
+    />
+  )
+}
+```
+
+Data sourcing mode is list-wide. Read `list.pipelineConfig.dataMode` or the workflow-side `list.getConfig()` result when a workflow must choose mock versus live sourcing. Do not add per-action `mock` / `live` controls for Apollo, crawl, enrichment, or scoring steps. Export mode is separate: `preview` versus `export` controls whether a destination write happens.
 
-Each registry entry declares a Zod `schema` and a `layout` of declarative field hints (`StepConfigLayout<Input>`). The shared `StepConfigForm` renders the layout, validates against the schema, and wires `value`/`onChange` for you — no per-action React components. The List Builder right column renders the form as `Configuration | Advanced | Runs` tabs with a sticky action footer; `RunWorkflowModal` renders the same form inline. Omit the `advanced:` section when a step has none.
+Each registry entry declares a Zod `schema` and a `layout` of declarative field hints (`StepConfigLayout<Input>`). The shared `StepConfigForm` renders the layout, validates against the schema, and wires `value`/`onChange` for you — no per-action React components. The List Builder right column renders the form as `Configuration | Advanced | Runs` tabs with a sticky action footer. Omit the `advanced:` section when a step has none.
 
 Available field component variants: `textinput`, `textarea`, `numberinput`, `switch`, `segmented`, `select`, `multiselect`, `tags`, `json`. Field hints support `label`, `description`, `placeholder`, `min`/`max`/`step` (numbers), `options` (selects), and `when: (values) => boolean` for conditional visibility.
 
 ```tsx
-import * as z from 'zod'
-import { type ListBuilderRegistry } from '@elevasis/ui/features/lead-gen'
-import type { StepConfigLayout } from '@elevasis/ui/components/forms'
-import { ElevasisUIProvider } from '@elevasis/ui/provider'
-import { resourceDescriptors } from '@core/config/organization-model'
-
-const companyCleanupInputSchema = z.object({
-  listId: z.string().uuid(),
-  targetDescription: z.string(),
-  dryRun: z.boolean().default(true),
-  batchSize: z.number().int().min(1).default(20),
-  mode: z.enum(['mock', 'live']).default('live')
-})
+import * as z from 'zod'
+import { leadGenManifest, type ListBuilderRegistry } from '@elevasis/ui/features/lead-gen'
+import type { StepConfigLayout } from '@elevasis/ui/components/forms'
+import { ElevasisSystemsProvider, ElevasisUIProvider } from '@elevasis/ui/provider'
+import { organizationModel, resourceDescriptors } from '@core/config/organization-model'
+
+const companyCleanupInputSchema = z.object({
+  listId: z.string().uuid(),
+  targetDescription: z.string(),
+  dryRun: z.boolean().default(true),
+  batchSize: z.number().int().min(1).default(20)
+})
 
 type CompanyCleanupInput = z.infer<typeof companyCleanupInputSchema>
 const companyCleanupResource = resourceDescriptors.companyCleanup
@@ -192,24 +237,13 @@ const companyCleanupLayout: StepConfigLayout<CompanyCleanupInput> = {
       ]
     }
   ],
-  advanced: {
-    id: 'advanced',
-    fields: [
-      { path: 'batchSize', component: 'numberinput', label: 'Batch size', min: 1 },
-      {
-        path: 'mode',
-        component: 'segmented',
-        options: [
-          { value: 'mock', label: 'Mock' },
-          { value: 'live', label: 'Live' }
-        ],
-        when: () => import.meta.env.DEV
-      }
-    ]
-  }
-}
+  advanced: {
+    id: 'advanced',
+    fields: [{ path: 'batchSize', component: 'numberinput', label: 'Batch size', min: 1 }]
+  }
+}
 
-const listActions: ListBuilderRegistry = [
+const listActions: ListBuilderRegistry = [
   {
     resourceId: companyCleanupResource.id,
     workflowId: companyCleanupResource.id,
@@ -226,24 +260,33 @@ const listActions: ListBuilderRegistry = [
       dryRun: true,
       batchSize: 20
     })
-  }
-]
-
-export function App() {
-  return (
-    <ElevasisUIProvider listActions={listActions} {...providerProps}>
-      {children}
-    </ElevasisUIProvider>
-  )
-}
-```
-
-Author the `schema` in a browser-safe sibling file (no Node-only imports) so it can be reused by the workflow runtime AND the UI form. See `apollo-import-schema.ts` in the platform for the canonical split pattern.
+  }
+]
+
+const SYSTEM_MANIFESTS = [
+  leadGenManifest,
+  // Add any other shared/local system manifests here.
+]
+
+export function App() {
+  return (
+    <ElevasisUIProvider listActions={listActions} {...providerProps}>
+      <ElevasisSystemsProvider systems={SYSTEM_MANIFESTS} organizationModel={organizationModel}>
+        {children}
+      </ElevasisSystemsProvider>
+    </ElevasisUIProvider>
+  )
+}
+```
+
+Author the `schema` in a browser-safe sibling file (no Node-only imports) so it can be reused by the workflow runtime AND the UI form. See `apollo-import-schema.ts` in the platform for the canonical split pattern.
+
+Keep the registry in the external project, usually `ui/src/config/listActions.ts`. Do not add client workflow ids, client action keys, or client default inputs to `@elevasis/ui`.
 
 Per-section split rule (operator-grade vs power-user):
 
-- **Configuration:** target/limit, dry-run toggle, mode (preview/finalize), and any field an operator changes between runs.
-- **Advanced:** concurrency, batch size, timeouts, credential names, workflow chaining, dev-only mode toggles. Omit the `advanced:` key entirely when a step has none.
+- **Configuration:** target/limit, dry-run toggle, export mode (`preview` / `export`) when the action writes to an external destination, and any field an operator changes between runs.
+- **Advanced:** concurrency, batch size, timeouts, credential names, and workflow chaining. Do not put mock/live controls here; data sourcing mode is list-wide. Omit the `advanced:` key entirely when a step has none.
 - **`defaultInput`:** seeds the form before the user touches anything; must include `listId: list.id`.
 
 ## 3. Build a Custom Campaign Workspace
@@ -367,13 +410,23 @@ Keep these boundaries straight:
 - `organizationId` is injected by the platform dispatcher. Do not pass it from workflow code.
 - Persisted API shapes are owned by core/API contracts, not route-local TypeScript.
 
-## 5. Customize Lead-Gen Semantics
-
-The lead-gen shell module key is `lead-gen`, the Organization OS System id is `sales.lead-gen`, and the action currently used by the shared manifest is `leadgen.lists.manage`.
-
-For feature toggles, labels, lifecycle semantics, or resource descriptors, update the project model:
-
-`core/config/organization-model.ts`
+## 5. Customize Lead-Gen Semantics
+
+The lead-gen shell module key is `lead-gen`, the Organization OS System id is `sales.lead-gen`, and the action currently used by the shared manifest is `leadgen.lists.manage`.
+
+For feature toggles, labels, lifecycle semantics, stage catalogs, build templates, actions, resource descriptors, or runtime topology, update the project model:
+
+`core/config/organization-model.ts`
+
+Tenant-owned list-builder values belong in the main Organization Model:
+
+- stage vocabulary in lead-gen ontology catalogs
+- build templates and template-step catalogs in lead-gen ontology catalogs
+- action ids in the tenant action layer
+- workflow resources in the tenant resources map with ontology bindings and `primaryAction`
+- topology relationships in the tenant topology map
+
+Use `core/config/extensions/*` for entity schema variants, not for list-builder stage catalogs or workflow bindings.
 
 The platform-side lead-gen stateful vocabulary is defined for: