@elevasis/sdk 1.12.0 → 1.13.1

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

@@ -0,0 +1,255 @@
+---
+title: Build and Extend CRM
+description: Map the CRM platform primitives available to SDK projects: shared UI pages, sidebar composition, data hooks, action definitions, workflow adapters, contracts, and org-model extension boundaries.
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Build and Extend CRM
+
+Use this recipe when a downstream project wants to build on the shared CRM instead of forking it.
+
+Good trigger phrases:
+
+- "Add a CRM reports page."
+- "Build a custom deal workspace."
+- "Read and update deals from a workflow."
+- "Add a Send Quote button."
+- "Change the CRM pipeline stages for this business."
+
+CRM is a layered platform surface, not one component:
+
+- **Organization OS:** feature gates, sales pipeline semantics, quick access, and labels live in the organization model.
+- **Shared UI:** CRM pages, sidebars, workbench panels, overview widgets, and Kanban/detail components live in `@elevasis/ui`.
+- **Headless hooks:** deal, company, contact, note, task, list, transition, and action hooks live under `@elevasis/ui/hooks`.
+- **Action system:** `ActionDef`, `DEFAULT_CRM_ACTIONS`, `deriveActions`, and provider-level `crmActions` configure deal actions.
+- **Workflow adapters:** `crm` and `acqDb` from `@elevasis/sdk/worker` let workflows read and mutate CRM/acquisition data through platform tools.
+- **Contracts:** generated contract docs expose the current CRM shapes in `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`.
+
+## Decision Table
+
+| User wants | Start here | Notes |
+| --- | --- | --- |
+| Change CRM feature availability, labels, or pipeline stages | `core/config/organization-model.ts` plus `core/config/organization-model.examples.ts` | Treat this as Organization OS work. Use the project's configure ceremony if available. |
+| Add CRM sidebar nav or a CRM route | `@elevasis/ui/features/crm` and `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
+
+| Surface | Import from | Use for |
+| --- | --- | --- |
+| `crmManifest`, `CRM_ITEMS`, `CrmSidebar`, `CrmSidebarTop`, `CrmSidebarMiddle` | `@elevasis/ui/features/crm` | Feature registration and sidebar composition |
+| `CrmOverview`, `DealsListPage`, `DealDetailPage`, `CompanyDetailPage` | `@elevasis/ui/features/crm` | Shared CRM pages you can route to or wrap |
+| `MyTasksPanel`, `SavedViewsPanel`, `QuickCreateActions` | `@elevasis/ui/features/crm` | Workbench/sidebar panels for custom CRM sidebars |
+| `PipelineFunnelWidget`, `ActivityFeedWidget`, `MetricsStrip` | `@elevasis/ui/features/crm` | Overview widgets for custom dashboards |
+| `KanbanBoard`, `DealKanbanCard`, `DealDrawer` | `@elevasis/ui/components` | Lower-level CRM deal UI primitives |
+| `useDeals`, `useDealDetail`, `useTransitionItem`, `useExecuteAction`, `useDealNotes`, `useDealTasks` | `@elevasis/ui/hooks` | Headless deal and task data access |
+| `useCompanies`, `useContacts`, `useLists`, `useBatchTelemetry` | `@elevasis/ui/hooks` | Acquisition substrate data access |
+| `ElevasisUIProvider`, `ElevasisCoreProvider`, `useElevasisServices` | `@elevasis/ui/provider` | Provider setup, API access, and organization context |
+| `ActionDef`, `DEFAULT_CRM_ACTIONS`, `deriveActions` | `@elevasis/sdk` | Deal action configuration and render-time derivation |
+| `crm`, `acqDb` | `@elevasis/sdk/worker` | Workflow-side CRM/acquisition platform adapters |
+
+Read the generated contracts before changing typed boundaries:
+
+`node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+
+Look for the **CRM Platform Primitives** section. It includes deal stages, deal rows, task shapes, API schemas, action definitions, and the focused CRM workflow adapter map. The broader acquisition/list adapter maps live under **Lead Gen Platform Primitives**.
+
+## 1. Extend CRM Navigation or Sidebar
+
+For a simple nav addition, extend `CRM_ITEMS` and override the CRM feature manifest:
+
+```tsx
+// ui/src/routes/__root.tsx
+import { crmManifest, CRM_ITEMS, CrmSidebar, CrmSidebarMiddle } from '@elevasis/ui/features/crm'
+import type { FeatureModule } from '@elevasis/ui/provider'
+import type { NavItem } from '@elevasis/ui/layout'
+import { IconFileText } from '@tabler/icons-react'
+
+const customCrmItems: NavItem[] = [
+  ...CRM_ITEMS,
+  { label: 'Reports', to: '/crm/reports', icon: IconFileText, exact: false }
+]
+
+const CustomCrmSidebar = () => (
+  <CrmSidebar>
+    <CrmSidebarMiddle items={customCrmItems} />
+  </CrmSidebar>
+)
+
+export const customCrmManifest: FeatureModule = {
+  ...crmManifest,
+  sidebar: CustomCrmSidebar
+}
+```
+
+Then replace `crmManifest` with `customCrmManifest` in the local `FEATURE_MANIFESTS` array and add the matching route under `ui/src/routes/crm/`.
+
+For structural changes, compose `CrmSidebarTop`, `SubshellNavList`, `SubshellSidebarSection`, `MyTasksPanel`, and `QuickCreateActions`. The full sidebar decision tree lives in `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`.
+
+## 2. Wrap Shared CRM Pages
+
+If the shared page is close, keep it and wrap it:
+
+```tsx
+// ui/src/routes/crm/deals.index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { DealsListPage } from '@elevasis/ui/features/crm'
+import { Stack } from '@mantine/core'
+import { ProjectAnnouncementBanner } from '@/lib/components/ProjectAnnouncementBanner'
+
+export const Route = createFileRoute('/crm/deals/')({
+  component: DealsRoute
+})
+
+function DealsRoute() {
+  return (
+    <Stack gap={0}>
+      <ProjectAnnouncementBanner context="crm-deals" />
+      <DealsListPage />
+    </Stack>
+  )
+}
+```
+
+Use the same pattern for `CrmOverview`, `DealDetailPage`, and `CompanyDetailPage`.
+
+## 3. Build a Custom Deal Page
+
+When the project needs custom layout or additional workflows, use the hooks directly:
+
+```tsx
+import { Button, Group, Stack, Textarea } from '@mantine/core'
+import { useState } from 'react'
+import { useDealDetail, useDealNotes, useCreateDealNote, useExecuteAction } from '@elevasis/ui/hooks'
+
+export function CustomDealWorkspace({ dealId }: { dealId: string }) {
+  const { data: deal, isLoading } = useDealDetail(dealId)
+  const { data: notes = [] } = useDealNotes(dealId)
+  const createNote = useCreateDealNote()
+  const executeAction = useExecuteAction({ dealId })
+  const [body, setBody] = useState('')
+
+  if (isLoading) return null
+  if (!deal) return <div>Deal not found</div>
+
+  return (
+    <Stack>
+      <h1>{deal.contact_email}</h1>
+      <Group>
+        <Button onClick={() => executeAction.mutate({ key: 'move_to_proposal' })}>
+          Move to Proposal
+        </Button>
+      </Group>
+      <Textarea value={body} onChange={(event) => setBody(event.currentTarget.value)} />
+      <Button onClick={() => createNote.mutate({ dealId, body })}>Add Note</Button>
+      <pre>{JSON.stringify(notes, null, 2)}</pre>
+    </Stack>
+  )
+}
+```
+
+`useExecuteAction` is for platform-known/default action keys. Start custom action UI with the shared `crmActions` provider path; when a project-owned workflow is outside that server-dispatched action set, call `/execute` or `/execute-async` through `useElevasisServices`, or follow [customize-crm-actions.md](customize-crm-actions.md).
+
+## 4. Read and Mutate CRM Data in Workflows
+
+Inside deployed workflows, use worker adapters instead of browser hooks or direct database access:
+
+```ts
+// operations/src/sales/follow-up-stale-deals.ts
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { crm } from '@elevasis/sdk/worker'
+import { z } from 'zod'
+
+const inputSchema = z.object({
+  stage: z.string().default('proposal')
+})
+
+const outputSchema = z.object({
+  touched: z.number()
+})
+
+export const followUpStaleDealsWorkflow: WorkflowDefinition = {
+  config: {
+    resourceId: 'follow-up-stale-deals',
+    name: 'Follow Up Stale Deals',
+    type: 'workflow',
+    version: '1.0.0',
+    status: 'dev',
+    links: [{ nodeId: 'feature:sales.crm', kind: 'operates-on' }]
+  },
+  contract: { inputSchema, outputSchema },
+  steps: {
+    followUp: {
+      id: 'followUp',
+      name: 'Follow Up',
+      inputSchema,
+      outputSchema,
+      next: null,
+      handler: async (input) => {
+        const deals = await crm.listDeals({ stage: input.stage })
+
+        for (const deal of deals) {
+          await crm.createDealTask({
+            dealId: deal.id,
+            title: 'Follow up',
+            kind: 'email'
+          })
+          await crm.recordActivity({
+            dealId: deal.id,
+            type: 'workflow.follow_up_task_created',
+            title: 'Follow-up task created',
+            payload: { workflow: 'follow-up-stale-deals' }
+          })
+        }
+
+        return { touched: deals.length }
+      }
+    }
+  },
+  entryPoint: 'followUp'
+}
+```
+
+Use `crm` for focused CRM deal reads, notes, tasks, activity, and cleanup. Use `acqDb` when the workflow needs the broader acquisition substrate: companies, contacts, lists, list-stage transitions, enrichment data, social posts, or lower-level deal sync methods.
+
+## 5. Customize Pipeline Semantics
+
+CRM feature identity remains `sales.crm`, but the organization-model domain is `sales`.
+
+For stage labels or stage sets, start from the project reference file:
+
+`core/config/organization-model.examples.ts`
+
+Then update the project model:
+
+`core/config/organization-model.ts`
+
+Keep these boundaries straight:
+
+- Org-model sales pipelines describe business semantics.
+- `DealStage` and platform action defaults describe the current shared platform deal state vocabulary.
+- UI wrappers can relabel and route around shared surfaces, but changing persisted platform stages requires coordinated core/API/UI updates.
+- Do not add `sales.actions` to the org model in v1. Deal action customization is covered by [customize-crm-actions.md](customize-crm-actions.md).
+
+## Verify
+
+Run the checks for the surfaces you touched:
+
+```bash
+pnpm -C ui run check
+pnpm -C operations run check
+pnpm -C operations exec elevasis-sdk check
+```
+
+If you changed platform-level CRM contracts in the monorepo, the platform maintainer must also regenerate and verify scaffold output:
+
+```bash
+pnpm scaffold:sync
+pnpm scaffold:verify
+```

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

@@ -0,0 +1,297 @@
+---
+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, touchpoints, workflow adapters, contracts, and org-model extension boundaries.
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Build and Extend Lead Gen
+
+Use this recipe when a downstream project wants to build on the shared lead-gen system instead of forking it.
+
+Good trigger phrases:
+
+- "Add a lead-gen reports page."
+- "Build a campaign creator surface."
+- "Customize the lead-gen sidebar."
+- "Show artifacts or touchpoints for a campaign."
+- "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, feature gates, 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, touchpoints, list members, transitions, and derived actions live under `@elevasis/ui/hooks`.
+- **Acquisition substrate:** `acq_lists`, `acq_companies`, `acq_contacts`, `acq_artifacts`, `acq_touchpoints`, 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`.
+
+## Decision Table
+
+| User wants | Start here | Notes |
+| --- | --- | --- |
+| Change lead-gen feature availability, labels, quick access, or pipeline semantics | `core/config/organization-model.ts` plus `core/config/organization-model.examples.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`, `LeadGenCompaniesPage`, `LeadGenContactsPage` | Keep route files thin and put project-specific behavior in local feature modules. |
+| Build a custom campaign/list workspace | `useLists`, `useList`, `useListMembers`, `useArtifacts`, `useTouchpoints`, `useTransitionListMember` from `@elevasis/ui/hooks` | Use hooks for platform data and compose your own UI. |
+| Render artifacts, touchpoints, or list-member detail | `LeadGenListDetailPage`, `useArtifacts`, `useCreateArtifact`, `useTouchpoints`, `useListMember` | Artifacts and touchpoints are substrate primitives. 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`, `LeadGenCompaniesPage`, `LeadGenContactsPage` | `@elevasis/ui/features/lead-gen` | Shared lead-gen pages you can route to or wrap |
+| `LeadGenRouteShell`, `CompanyDetailModal`, `ContactDetailModal`, `LIST_TEMPLATE_OPTIONS`, `buildListConfig` | `@elevasis/ui/features/lead-gen` | Route shell helpers, detail modals, and list creation config helpers |
+| `useLists`, `useList`, `useListsTelemetry`, `useListProgress`, `useListExecutions`, `useCreateList`, `useUpdateList`, `useUpdateListConfig`, `useDeleteList` | `@elevasis/ui/hooks` | Headless list and telemetry data access |
+| `useCompanies`, `useCompany`, `useContacts`, `useContact` | `@elevasis/ui/hooks` | Acquisition company/contact data access |
+| `useArtifacts`, `useCreateArtifact`, `useTouchpoints`, `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, and organization context |
+| `acqDb`, `list` | `@elevasis/sdk/worker` | Workflow-side acquisition and list-scoped platform adapters |
+
+Read the generated contracts before changing typed boundaries:
+
+`node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+
+Look for the **Lead Gen Platform Primitives** section. It includes list shapes, company/contact shapes, list config, telemetry, artifacts, touchpoints, list members, stateful pipeline definitions, and workflow adapter method maps.
+
+## 1. Extend Lead-Gen Navigation or Sidebar
+
+For a simple nav addition, extend `LEAD_GEN_ITEMS` and override the lead-gen feature manifest:
+
+```tsx
+// ui/src/routes/__root.tsx
+import { leadGenManifest, LEAD_GEN_ITEMS, LeadGenSidebar, LeadGenSidebarMiddle } from '@elevasis/ui/features/lead-gen'
+import type { FeatureModule } from '@elevasis/ui/provider'
+import type { NavItem } from '@elevasis/ui/layout'
+import { IconChartBar } from '@tabler/icons-react'
+
+const customLeadGenItems: NavItem[] = [
+  ...LEAD_GEN_ITEMS,
+  { label: 'Reports', to: '/lead-gen/reports', icon: IconChartBar, exact: false }
+]
+
+const CustomLeadGenSidebar = () => (
+  <LeadGenSidebar>
+    <LeadGenSidebarMiddle items={customLeadGenItems} />
+  </LeadGenSidebar>
+)
+
+export const customLeadGenManifest: FeatureModule = {
+  ...leadGenManifest,
+  sidebar: CustomLeadGenSidebar
+}
+```
+
+Then replace `leadGenManifest` with `customLeadGenManifest` in the local `FEATURE_MANIFESTS` array and add the matching route under `ui/src/routes/lead-gen/`.
+
+For structural changes, compose `LeadGenSidebarTop`, `SubshellNavList`, and `SubshellSidebarSection`. The full sidebar decision tree lives in `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`.
+
+## 2. Wrap Shared Lead-Gen Pages
+
+If the shared page is close, keep it and wrap it:
+
+```tsx
+// ui/src/routes/lead-gen/lists.index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { LeadGenListsPage } from '@elevasis/ui/features/lead-gen'
+import { Stack } from '@mantine/core'
+import { ProjectAnnouncementBanner } from '@/lib/components/ProjectAnnouncementBanner'
+
+export const Route = createFileRoute('/lead-gen/lists/')({
+  component: ListsRoute
+})
+
+function ListsRoute() {
+  return (
+    <Stack gap={0}>
+      <ProjectAnnouncementBanner context="lead-gen-lists" />
+      <LeadGenListsPage />
+    </Stack>
+  )
+}
+```
+
+For list detail routes, pass the route param into `LeadGenListDetailPage`:
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { LeadGenListDetailPage } from '@elevasis/ui/features/lead-gen'
+
+export const Route = createFileRoute('/lead-gen/lists/$listId')({
+  component: ListDetailRoute
+})
+
+function ListDetailRoute() {
+  const { listId } = Route.useParams()
+  return <LeadGenListDetailPage listId={listId} />
+}
+```
+
+Use the same wrapping pattern for `LeadGenOverviewPage`, `LeadGenCompaniesPage`, and `LeadGenContactsPage`.
+
+## 3. Build a Custom Campaign Workspace
+
+When the project needs custom layout or vertical-specific rendering, use the hooks directly:
+
+```tsx
+import { Badge, Button, Card, Group, Stack, Text } from '@mantine/core'
+import { useArtifacts, useList, useListMembers, useTouchpoints, useTransitionListMember } from '@elevasis/ui/hooks'
+
+export function CampaignWorkspace({ listId }: { listId: string }) {
+  const listQuery = useList(listId)
+  const membersQuery = useListMembers({ listId })
+  const artifactsQuery = useArtifacts({ ownerKind: 'list', ownerId: listId })
+  const touchpointsQuery = useTouchpoints({ listId })
+  const transitionMember = useTransitionListMember()
+
+  const list = listQuery.data
+  if (!list) return null
+
+  const firstMember = membersQuery.data?.members[0]
+
+  return (
+    <Stack>
+      <Group justify="space-between">
+        <div>
+          <Text fw={700}>{list.name}</Text>
+          <Text size="sm" c="dimmed">{list.description}</Text>
+        </div>
+        <Badge>{list.stateKey}</Badge>
+      </Group>
+
+      <Card withBorder>
+        <Text size="sm">Artifacts: {artifactsQuery.data?.artifacts.length ?? 0}</Text>
+        <Text size="sm">Touchpoints: {touchpointsQuery.data?.touchpoints.length ?? 0}</Text>
+      </Card>
+
+      {firstMember ? (
+        <Button
+          onClick={() =>
+            transitionMember.mutate({
+              memberId: firstMember.id,
+              listId,
+              pipelineKey: 'lead-gen',
+              stageKey: 'prospecting',
+              stateKey: 'verified'
+            })
+          }
+        >
+          Mark First Member Verified
+        </Button>
+      ) : null}
+    </Stack>
+  )
+}
+```
+
+Use `useArtifacts({ ownerKind, ownerId })` for durable JSON artifacts like audits, research summaries, snapshots, exports, or model outputs. Use `useTouchpoints({ listId })`, `useTouchpoints({ listMemberId })`, or `useTouchpoints({ contactId })` for timeline-style campaign interactions.
+
+## 4. Read and Mutate Lead-Gen Data in Workflows
+
+Inside deployed workflows, use worker adapters instead of browser hooks or direct database access:
+
+External projects should define workflow input/output schemas in `@shared/types`; the example below assumes those shared schemas already exist.
+
+```ts
+// operations/src/sales/qualify-list.ts
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { acqDb, list } from '@elevasis/sdk/worker'
+import { qualifyListInputSchema, qualifyListOutputSchema } from '@shared/types'
+
+export const qualifyListWorkflow: WorkflowDefinition = {
+  config: {
+    resourceId: 'qualify-list',
+    name: 'Qualify List',
+    type: 'workflow',
+    version: '1.0.0',
+    status: 'dev',
+    links: [{ nodeId: 'feature:sales.lead-gen', kind: 'operates-on' }]
+  },
+  contract: { inputSchema: qualifyListInputSchema, outputSchema: qualifyListOutputSchema },
+  steps: {
+    qualify: {
+      id: 'qualify',
+      name: 'Qualify',
+      inputSchema: qualifyListInputSchema,
+      outputSchema: qualifyListOutputSchema,
+      next: null,
+      handler: async (input, context) => {
+        const config = await list.getConfig({ listId: input.listId })
+        const contacts = await acqDb.listContacts({ listId: input.listId, limit: 100, offset: 0 })
+
+        for (const contact of contacts.data) {
+          await list.updateContactStage({
+            listId: input.listId,
+            contactId: contact.id,
+            stage: 'verified',
+            executionId: context.executionId
+          })
+        }
+
+        await list.recordExecution({
+          listId: input.listId,
+          executionId: context.executionId,
+          configSnapshot: config
+        })
+
+        return { touched: contacts.data.length }
+      }
+    }
+  },
+  entryPoint: 'qualify'
+}
+```
+
+Use `list` for focused list-scoped workflow operations: fetch list config, record a list execution, and update company/contact list stages. Use `acqDb` when the workflow needs broader acquisition operations: create/update lists, companies, contacts, add contacts to lists, bulk import, enrichment, social posts, or CRM deal sync methods.
+
+Keep these boundaries straight:
+
+- Browser/UI code uses `@elevasis/ui/hooks`.
+- Workflow code uses `@elevasis/sdk/worker` adapters.
+- `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 feature key is `lead-gen`, the Organization OS feature id is `sales.lead-gen`, and the capability currently used by the shared manifest is `leadgen.lists.manage`.
+
+For feature toggles, labels, or lifecycle semantics, start from the project reference file:
+
+`core/config/organization-model.examples.ts`
+
+Then update the project model:
+
+`core/config/organization-model.ts`
+
+The platform-side lead-gen stateful vocabulary is defined for:
+
+- `acq.list`
+- `acq.list-member`
+- `acq.list-company`
+
+The generated contracts expose `StatefulPipelineDefinition` and `LEAD_GEN_PIPELINE_DEFINITIONS` so downstream agents can inspect the current pipeline/stage/state vocabulary before adding UI labels or workflow transitions.
+
+Changing persisted platform stages, adding new owner kinds, or extending artifact/touchpoint schema requires coordinated core/API/UI updates. Relabeling, route wrapping, sidebar changes, and project-owned rendering usually stay in the downstream project.
+
+## Verify
+
+Run the checks for the surfaces you touched:
+
+```bash
+pnpm -C ui run check
+pnpm -C operations run check
+pnpm -C operations exec elevasis-sdk check
+```
+
+If you changed platform-level lead-gen contracts in the monorepo, the platform maintainer must also regenerate and verify scaffold output:
+
+```bash
+pnpm scaffold:sync
+pnpm scaffold:verify
+```

package/reference/scaffold/recipes/index.md

@@ -22,14 +22,23 @@ You want a new shell feature (e.g., `analytics`) with its own nav entry, sidebar
 **[Add a Resource](add-a-resource.md)**
 You want a new workflow or agent deployed to the platform. Covers `WorkflowDefinition` authoring, `DeploymentSpec` registration, relationship declarations, domain mapping, and CLI verification.
 
-**[Gate by Feature or Admin](gate-by-feature-or-admin.md)**
-You want to restrict a route, nav item, or UI element by feature flag or admin role. Covers the decision table, `FeatureGuard`, `AdminGuard`, nav-entry visibility fields, per-member `MembershipFeatureConfig` overrides, and the settings-asymmetry gotcha.
-
----
-
-## Reference docs these recipes link into
-
-- [glossary.md](../reference/glossary.md) -- term disambiguation for Feature, Resource, featureId, Topology, Settings asymmetry
-- [contracts.md](../reference/contracts.md) -- TypeScript shapes: `FeatureModule`, `FeatureNavEntry`, `OrganizationModel`, `MembershipFeatureConfig`
-- [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md) -- full three-concept gating model
-- [workflow-recipes.md](../operations/workflow-recipes.md) -- workflow anatomy, adapters, trigger patterns
+**[Gate by Feature or Admin](gate-by-feature-or-admin.md)**
+You want to restrict a route, nav item, or UI element by feature flag or admin role. Covers the decision table, `FeatureGuard`, `AdminGuard`, nav-entry visibility fields, per-member `MembershipFeatureConfig` overrides, and the settings-asymmetry gotcha.
+
+**[Build and Extend CRM](extend-crm.md)**
+You want to build on the shared CRM without forking it: add CRM routes, compose sidebars/pages, use deal/company/contact hooks, mutate CRM data from workflows, or understand which contracts and adapters form the extension surface.
+
+**[Build and Extend Lead Gen](extend-lead-gen.md)**
+You want to build on the shared lead-gen system without forking it: add lead-gen routes, compose sidebars/pages, use list/company/contact/artifact/touchpoint hooks, mutate list data from workflows, or understand which contracts and adapters form the extension surface.
+
+**[Customize CRM Actions](customize-crm-actions.md)**
+You want to add, hide, or replace CRM deal action buttons, configure the shared `crmActions` provider path, or call a project-owned workflow from custom UI when server-side action dispatch constraints require it. Covers `ActionDef`, `DEFAULT_CRM_ACTIONS`, provider wiring, and the current v1 boundary for custom action dispatch.
+
+---
+
+## Reference docs these recipes link into
+
+- [glossary.md](../reference/glossary.md) -- term disambiguation for Feature, Resource, featureId, Topology, Settings asymmetry
+- [contracts.md](../reference/contracts.md) -- TypeScript shapes: `FeatureModule`, `FeatureNavEntry`, `OrganizationModel`, `MembershipFeatureConfig`, CRM deal types, lead-gen list/member/artifact/touchpoint types, `CrmToolMap`, `LeadToolMap`, `ListToolMap`, `ActionDef`
+- [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md) -- full three-concept gating model
+- [workflow-recipes.md](../operations/workflow-recipes.md) -- workflow anatomy, adapters, trigger patterns