@elevasis/sdk 1.14.0 → 1.15.0

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

@@ -1,6 +1,6 @@
 ---
 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.
+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.
 ---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
@@ -15,7 +15,7 @@ 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."
+- "Show artifacts for a campaign."
 - "Read or update lead-gen lists from a workflow."
 - "Change the lead-gen lifecycle for this business."
 
@@ -23,42 +23,42 @@ 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.
+- **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`.
 
 ## 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. |
+| 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`, `useTransitionListMember` from `@elevasis/ui/hooks`      | Use hooks for platform data and compose your own UI.                                                            |
+| 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`, `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 |
+| 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`, `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.
+Look for the **Lead Gen Platform Primitives** section. It includes list shapes, company/contact shapes, list config, telemetry, artifacts, list members, stateful pipeline definitions, and workflow adapter method maps.
 
 ## 1. Extend Lead-Gen Navigation or Sidebar
 
@@ -141,13 +141,12 @@ When the project needs custom layout or vertical-specific rendering, use the hoo
 
 ```tsx
 import { Badge, Button, Card, Group, Stack, Text } from '@mantine/core'
-import { useArtifacts, useList, useListMembers, useTouchpoints, useTransitionListMember } from '@elevasis/ui/hooks'
+import { useArtifacts, useList, useListMembers, 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
@@ -167,7 +166,6 @@ export function CampaignWorkspace({ listId }: { listId: string }) {
 
       <Card withBorder>
         <Text size="sm">Artifacts: {artifactsQuery.data?.artifacts.length ?? 0}</Text>
-        <Text size="sm">Touchpoints: {touchpointsQuery.data?.touchpoints.length ?? 0}</Text>
       </Card>
 
       {firstMember ? (
@@ -190,7 +188,7 @@ export function CampaignWorkspace({ listId }: { listId: string }) {
 }
 ```
 
-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.
+Use `useArtifacts({ ownerKind, ownerId })` for durable JSON artifacts like audits, research summaries, snapshots, exports, or model outputs.
 
 ## 4. Read and Mutate Lead-Gen Data in Workflows
 
@@ -277,7 +275,7 @@ The platform-side lead-gen stateful vocabulary is defined for:
 
 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.
+Changing persisted platform stages, adding new owner kinds, or extending artifact schema requires coordinated core/API/UI updates. Relabeling, route wrapping, sidebar changes, and project-owned rendering usually stay in the downstream project.
 
 ## Verify
 

package/reference/scaffold/recipes/index.md

@@ -1,44 +1,44 @@
----
-title: Pathway Recipes
-description: Terse end-to-end walkthroughs for the three most common authoring tasks -- adding a feature, adding a resource, and gating access.
----
+---
+title: Pathway Recipes
+description: Terse end-to-end walkthroughs for the three most common authoring tasks -- adding a feature, adding a resource, and gating access.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-# Pathway Recipes
-
-Three sequential walkthroughs for common authoring tasks. Each recipe links into the reference docs rather than duplicating them.
-
-Before starting, read [glossary.md](../reference/glossary.md) to disambiguate overloaded terms (Feature, Resource, featureId, Settings asymmetry, Topology).
-
----
-
-## Recipes
-
-**[Add a Feature](add-a-feature.md)**
-You want a new shell feature (e.g., `analytics`) with its own nav entry, sidebar, routes, and org-model gate. Covers adding a feature object to the org model, `FeatureModule` manifest authoring, route creation, and gating.
-
-**[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.
-
-**[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
+
+# Pathway Recipes
+
+Three sequential walkthroughs for common authoring tasks. Each recipe links into the reference docs rather than duplicating them.
+
+Before starting, read [glossary.md](../reference/glossary.md) to disambiguate overloaded terms (Feature, Resource, featureId, Settings asymmetry, Topology).
+
+---
+
+## Recipes
+
+**[Add a Feature](add-a-feature.md)**
+You want a new shell feature (e.g., `analytics`) with its own nav entry, sidebar, routes, and org-model gate. Covers adding a feature object to the org model, `FeatureModule` manifest authoring, route creation, and gating.
+
+**[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.
+
+**[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 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 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