@elevasis/sdk 1.14.1 → 1.15.1

package/reference/claude-config/sync-notes/2026-05-02-template-hardcode-workos-config.md

@@ -0,0 +1,56 @@
+# Template WorkOS Hardcode + Strict Dev Port
+
+## Why this note exists
+
+The template UI no longer reads WorkOS configuration from `VITE_WORKOS_*` env vars. WorkOS `clientId`, `redirectUri`, and `signoutUri` are hardcoded in a new file `ui/src/config/workos.ts` so a freshly bootstrapped template runs without any UI `.env` setup. The Vite dev server now uses `strictPort: true` on port `4300` so a second `pnpm -C ui dev` on the same machine fails fast instead of silently drifting to another port.
+
+This sync moves three pieces into derived projects:
+
+- `ui/src/config/workos.ts` -- new merge-baseline file holding `clientId`, `redirectUri`, `signoutUri`
+- `ui/src/main.tsx` and `ui/src/routes/__root.tsx` -- merge-regions updates that import `WORKOS_CONFIG` from `@/config/workos` instead of reading `import.meta.env.VITE_WORKOS_*`
+- `ui/vite.config.ts` -- `strictPort: true` added next to `port: 4300`
+- `ui/.env.example` -- WorkOS section removed (replaced with a single comment pointing at `ui/src/config/workos.ts`)
+- `.claude/rules/ui.md` and `CLAUDE.md` -- prose updated; project-owned `CLAUDE.md` is verify-only and the project keeps its own narrative
+
+`nirvana-marketing` and `ZentaraHQ` already received `ui/src/config/workos.ts`, the `strictPort` flag, and the `.claude/rules/ui.md` baseline as prep-gate repairs in the previous train. This note formally attributes those changes to an owning task doc and covers any remaining template-derived projects.
+
+## Applies to
+
+Template-derived projects that:
+
+- run a WorkOS-authenticated UI from `ui/src/main.tsx` and `ui/src/routes/__root.tsx`
+- run the Vite dev server on port `4300`
+- have a project-owned `ui/src/config/workos.ts` (created via prep-gate repair) or are seeing it land for the first time on this sync
+- maintain a `ui/.env` file that previously set `VITE_WORKOS_CLIENT_ID`, `VITE_WORKOS_REDIRECT_URI`, or `VITE_WORKOS_SIGNOUT_URI`
+
+Projects with no WorkOS surface or no Vite dev server are not affected.
+
+## Required actions
+
+1. Pull template changes with `/git-sync` after this train publishes so the WorkOS hardcode and strict-port baselines reach the project's UI shell.
+
+2. Confirm the project's `ui/src/config/workos.ts` reflects the WorkOS client ID the project should authenticate against. The template ships the platform team's dev-tier `clientId`; client-facing projects must overwrite that value with the project's own WorkOS client ID before going to production. Edit the literal in `ui/src/config/workos.ts` -- no env vars are involved.
+
+3. Stop providing `VITE_WORKOS_CLIENT_ID`, `VITE_WORKOS_REDIRECT_URI`, and `VITE_WORKOS_SIGNOUT_URI` in `ui/.env`. They are no longer read. Delete the entries to keep the file honest. The WorkOS values now live in `ui/src/config/workos.ts`.
+
+4. Confirm `ui/vite.config.ts` carries `strictPort: true` next to `server.port: 4300`. If a second dev server starts on the same port, expect a hard failure instead of a drift to `4301`.
+
+5. If the project hand-rolled an env-vars notice component or a `REQUIRED_ENV_VARS` array around WorkOS, remove it. `createElevasisApp` no longer needs the `MissingEnvNotice` prop now that `clientId` is always truthy.
+
+## Verification
+
+After upgrading:
+
+- `pnpm -C ui check-types` and `pnpm -C ui build` pass with `WORKOS_CONFIG` imported from `@/config/workos`.
+- `pnpm -C ui dev` boots on `4300`. Starting a second `pnpm -C ui dev` in another terminal fails with a port-in-use error instead of incrementing to `4301`.
+- WorkOS sign-in and sign-out still round-trip through the project's WorkOS tenant. Sign-out lands on the URL configured in `ui/src/config/workos.ts` (`signoutUri`).
+- `grep -r VITE_WORKOS_ ui/src` returns nothing.
+
+## Not handled by /git-sync
+
+`/git-sync` does not:
+
+- delete `VITE_WORKOS_*` entries from project-local `ui/.env` files
+- overwrite `ui/src/config/workos.ts` if the project has already customized the `clientId` for a non-default WorkOS tenant (the file is merge-baseline; customizations are preserved)
+- update WorkOS dashboard redirect URIs or CORS origins for projects that run the dev server on a non-`4300` port; if the project changed the dev port, it must also change the WorkOS dashboard accordingly
+- redeploy any project-owned operations bundle; this train is UI-shell only

package/reference/scaffold/index.mdx

@@ -1,70 +1,70 @@
----
-title: Scaffold Reference
-description: Universal scaffold documentation for Elevasis SDK projects -- recipes, patterns, architecture, and reference materials that apply to all workspaces.
----
+---
+title: Scaffold Reference
+description: Universal scaffold documentation for Elevasis SDK projects -- recipes, patterns, architecture, and reference materials that apply to all workspaces.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-## Overview
-
-This scaffold reference contains universal documentation that applies to all Elevasis SDK projects. Content is organized by package ownership:
-
-- **recipes/** -- Cross-package pathway recipes (add a feature, add a resource, gating patterns)
-- **ui/** -- UI patterns, feature shell architecture, composition, and customization
-- **core/** -- Organization model architecture, graph layer, and semantic contracts
-- **operations/** -- Workflow authoring patterns and adapter usage
-- **reference/** -- Glossary, auto-generated contracts, and feature registry
-
-## Quick Navigation
-
-### Pathway Recipes
-
-- [Add a Feature](./recipes/add-a-feature.md) -- end-to-end from org model key through manifest, routes, gating
-- [Add a Resource](./recipes/add-a-resource.md) -- author and deploy a workflow or agent
-- [Extend a Base Entity](./recipes/extend-a-base-entity.md) -- add project-specific metadata to canonical entity shapes via the TMeta slot
-- [Gate by Feature or Admin](./recipes/gate-by-feature-or-admin.md) -- decision table for access control patterns
-- [Build and Extend CRM](./recipes/extend-crm.md) -- map CRM UI pages, hooks, actions, workflow adapters, contracts, and org-model boundaries
-- [Build and Extend Lead Gen](./recipes/extend-lead-gen.md) -- map lead-gen UI pages, hooks, list/member state, artifacts, touchpoints, workflow adapters, contracts, and org-model boundaries
-- [Customize CRM Actions](./recipes/customize-crm-actions.md) -- add, hide, or replace CRM deal actions, use the shared `crmActions` provider path, and understand workflow dispatch constraints
-
-### UI Patterns
-
-- [UI Recipes](./ui/recipes.md) -- copy-paste recipes for pages, nav items, components, theme tokens
-- [Feature Flags & Gating](./ui/feature-flags-and-gating.md) -- three-concept model for feature access
-- [Customizing Features](./ui/customization.md) -- sidebar composition via manifest overrides
-- [Feature Shell & Provider](./ui/feature-shell.mdx) -- FeatureModule manifest contract, provider runtime
-- [Composition & Extensibility](./ui/composition-extensibility.mdx) -- layout primitives, router abstraction
-
-### Core Architecture
-
-- [Organization Model](./core/organization-model.mdx) -- semantic contract, schema, authoring helpers
-- [Organization Graph](./core/organization-graph.mdx) -- graph derivation, node/edge taxonomy, lenses
-
-### Operations
-
-- [Workflow Recipes](./operations/workflow-recipes.md) -- workflow anatomy, adapter patterns, trigger patterns
-- [Propagation Pipeline](./operations/propagation-pipeline.md) -- three-layer sync pipeline, verification checks, integration points
-- [Scaffold Maintenance](./operations/scaffold-maintenance.md) -- content placement, auto-generation, adding new scaffold docs
-
-### Reference
-
-- [Glossary](./reference/glossary.md) -- term definitions for Organization OS concepts
-- [Contracts](./reference/contracts.md) -- auto-generated TypeScript contract shapes
-- [Feature Registry](./reference/feature-registry.md) -- auto-generated feature manifest catalog
-
-## Source Locations
-
-Content is co-located with its owning package and copied here during SDK build:
-
-| Bundle Path                                   | Source Location                                           | Owner           |
-| --------------------------------------------- | --------------------------------------------------------- | --------------- |
-| `scaffold/recipes/`                           | `packages/sdk/docs/scaffold/recipes/`                     | SDK             |
-| `scaffold/operations/`                        | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
-| `scaffold/operations/propagation-pipeline.md` | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
-| `scaffold/operations/scaffold-maintenance.md` | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
-| `scaffold/ui/`                                | `packages/ui/src/scaffold/`                               | UI              |
-| `scaffold/core/`                              | `packages/core/src/organization-model/`                   | Core            |
-| `scaffold/reference/glossary.md`              | `packages/core/src/reference/glossary.md`                 | Core            |
-| `scaffold/reference/contracts.md`             | `packages/core/src/reference/_generated/contracts.md`     | Core (auto-gen) |
-| `scaffold/reference/feature-registry.md`      | `packages/ui/src/scaffold/_generated/feature-registry.md` | UI (auto-gen)   |
+
+## Overview
+
+This scaffold reference contains universal documentation that applies to all Elevasis SDK projects. Content is organized by package ownership:
+
+- **recipes/** -- Cross-package pathway recipes (add a feature, add a resource, gating patterns)
+- **ui/** -- UI patterns, feature shell architecture, composition, and customization
+- **core/** -- Organization model architecture, graph layer, and semantic contracts
+- **operations/** -- Workflow authoring patterns and adapter usage
+- **reference/** -- Glossary, auto-generated contracts, and feature registry
+
+## Quick Navigation
+
+### Pathway Recipes
+
+- [Add a Feature](./recipes/add-a-feature.md) -- end-to-end from org model key through manifest, routes, gating
+- [Add a Resource](./recipes/add-a-resource.md) -- author and deploy a workflow or agent
+- [Extend a Base Entity](./recipes/extend-a-base-entity.md) -- add project-specific metadata to canonical entity shapes via the TMeta slot
+- [Gate by Feature or Admin](./recipes/gate-by-feature-or-admin.md) -- decision table for access control patterns
+- [Build and Extend CRM](./recipes/extend-crm.md) -- map CRM UI pages, hooks, actions, workflow adapters, contracts, and org-model boundaries
+- [Build and Extend Lead Gen](./recipes/extend-lead-gen.md) -- map lead-gen UI pages, hooks, list/member state, artifacts, workflow adapters, contracts, and org-model boundaries
+- [Customize CRM Actions](./recipes/customize-crm-actions.md) -- add, hide, or replace CRM deal actions, use the shared `crmActions` provider path, and understand workflow dispatch constraints
+
+### UI Patterns
+
+- [UI Recipes](./ui/recipes.md) -- copy-paste recipes for pages, nav items, components, theme tokens
+- [Feature Flags & Gating](./ui/feature-flags-and-gating.md) -- three-concept model for feature access
+- [Customizing Features](./ui/customization.md) -- sidebar composition via manifest overrides
+- [Feature Shell & Provider](./ui/feature-shell.mdx) -- FeatureModule manifest contract, provider runtime
+- [Composition & Extensibility](./ui/composition-extensibility.mdx) -- layout primitives, router abstraction
+
+### Core Architecture
+
+- [Organization Model](./core/organization-model.mdx) -- semantic contract, schema, authoring helpers
+- [Organization Graph](./core/organization-graph.mdx) -- graph derivation, node/edge taxonomy, lenses
+
+### Operations
+
+- [Workflow Recipes](./operations/workflow-recipes.md) -- workflow anatomy, adapter patterns, trigger patterns
+- [Propagation Pipeline](./operations/propagation-pipeline.md) -- three-layer sync pipeline, verification checks, integration points
+- [Scaffold Maintenance](./operations/scaffold-maintenance.md) -- content placement, auto-generation, adding new scaffold docs
+
+### Reference
+
+- [Glossary](./reference/glossary.md) -- term definitions for Organization OS concepts
+- [Contracts](./reference/contracts.md) -- auto-generated TypeScript contract shapes
+- [Feature Registry](./reference/feature-registry.md) -- auto-generated feature manifest catalog
+
+## Source Locations
+
+Content is co-located with its owning package and copied here during SDK build:
+
+| Bundle Path                                   | Source Location                                           | Owner           |
+| --------------------------------------------- | --------------------------------------------------------- | --------------- |
+| `scaffold/recipes/`                           | `packages/sdk/docs/scaffold/recipes/`                     | SDK             |
+| `scaffold/operations/`                        | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
+| `scaffold/operations/propagation-pipeline.md` | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
+| `scaffold/operations/scaffold-maintenance.md` | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
+| `scaffold/ui/`                                | `packages/ui/src/scaffold/`                               | UI              |
+| `scaffold/core/`                              | `packages/core/src/organization-model/`                   | Core            |
+| `scaffold/reference/glossary.md`              | `packages/core/src/reference/glossary.md`                 | Core            |
+| `scaffold/reference/contracts.md`             | `packages/core/src/reference/_generated/contracts.md`     | Core (auto-gen) |
+| `scaffold/reference/feature-registry.md`      | `packages/ui/src/scaffold/_generated/feature-registry.md` | UI (auto-gen)   |

package/reference/scaffold/recipes/customize-crm-actions.md

@@ -69,12 +69,10 @@ A minimal entry looks like:
 Workflows backing CRM actions use worker adapters instead of raw Supabase calls. The acquisition adapter is imported as `acqDb` from `@elevasis/sdk/worker` and exposes the action-workflow helpers:
 
 - `acqDb.transitionDeal({ dealId, toStage, toState? })` -- moves a deal to a new stage, optionally updating state_key.
-- `acqDb.recordDealActivity({ dealId, type, title, description?, payload? })` -- appends an entry to `acq_deal_activity_log`.
-- `acqDb.recordTouchpoint({ dealId, direction, channel, kind, payload, contactId, sourceExecutionId })` -- writes an `acq_touchpoints` row for outbound/inbound audit.
+- `acqDb.recordDealActivity({ dealId, type, title, description?, payload? })` -- appends an entry to the deal's `activity_log` JSONB column. Use this for outbound/inbound audit and lifecycle events.
 - `acqDb.loadDeal({ dealId })` -- returns the deal row joined with contact and company.
-- `acqDb.listDealTouchpoints({ dealId, kind?, limit? })` -- returns touchpoint history for a deal.
 
-These wrap existing `LeadService` logic -- they are extraction, not new business logic. The separate `crm` adapter also exposes focused CRM methods such as `crm.recordActivity(...)`; use `acqDb` for action workflows that need deal transitions, touchpoints, and the broader acquisition substrate.
+These wrap existing `LeadService` logic -- they are extraction, not new business logic. The separate `crm` adapter also exposes focused CRM methods such as `crm.recordActivity(...)`; use `acqDb` for action workflows that need deal transitions and the broader acquisition substrate.
 
 ## Override a Default Action
 
@@ -121,7 +119,7 @@ export const moveToProposalWorkflow: WorkflowDefinition = {
 }
 ```
 
-To add side effects (create a task, send a Slack message, record a touchpoint), extend the handler before the `return`. The `resourceId` must match the action's `workflowId` in `DEFAULT_CRM_ACTIONS` from `@elevasis/sdk` exactly.
+To add side effects (create a task, send a Slack message, log a deal activity), extend the handler before the `return`. The `resourceId` must match the action's `workflowId` in `DEFAULT_CRM_ACTIONS` from `@elevasis/sdk` exactly.
 
 Register the workflow in the operations manifest:
 
@@ -205,7 +203,7 @@ This controls the shared `DealDetailPage` and `DealDrawer` action row.
 
 For a brand-new action key that calls a project-owned workflow, define the workflow first.
 
-If the action sends email, writes to another channel, or otherwise touches a customer, use `acqDb.recordTouchpoint` inside the workflow handler to write an audit row. For an advanced Instantly-thread-aware variant that prefers in-thread replies and falls back to fresh outbound, use the production CRM workflow summary as the canonical example: `apps/docs/content/docs/in-progress/active-development/sdk-changes/crm/crm-current-state-assessment.mdx`.
+If the action sends email, writes to another channel, or otherwise touches a customer, use `acqDb.recordDealActivity` inside the workflow handler to append an audit entry to the deal's `activity_log`. For an advanced Instantly-thread-aware variant that prefers in-thread replies and falls back to fresh outbound, see the canonical CRM action examples in `external/elevasis/operations/src/sales/crm/actions/`.
 
 ### Define the Workflow Contract
 
@@ -272,14 +270,11 @@ export const sendQuoteWorkflow: WorkflowDefinition = {
           html: `<p>Your quote is ready. Reply to this email with questions.</p>`
         })
 
-        await acqDb.recordTouchpoint({
+        await acqDb.recordDealActivity({
           dealId,
-          direction: 'outbound',
-          channel: 'email',
-          kind: 'quote_sent',
-          payload: { triggered_by_action: 'send_quote' },
-          contactId: deal.contact.id,
-          sourceExecutionId: context.executionId
+          type: 'quote_sent',
+          title: 'Sent quote',
+          payload: { triggered_by_action: 'send_quote', channel: 'email' }
         })
 
         return {
@@ -394,6 +389,36 @@ export function CustomDealPage({ dealId }: { dealId: string }) {
 }
 ```
 
+## CRM State-Key Source of Truth
+
+`CRM_PIPELINE_DEFINITION` in `packages/core/src/organization-model/domains/sales.ts` is the single canonical source for CRM `state_key` values. It exports a `StatefulPipelineDefinition` that enumerates every valid state per stage (e.g. `interested` → `discovery_replied`, `discovery_link_sent`, `discovery_nudging`, etc.). Named per-state constants (`CRM_DISCOVERY_REPLIED_STATE`, `CRM_DISCOVERY_LINK_SENT_STATE`, and siblings) are also exported for use in conditional logic.
+
+Import via `@repo/core/organization-model`:
+
+```ts
+import {
+  CRM_PIPELINE_DEFINITION,
+  CRM_DISCOVERY_REPLIED_STATE,
+  getValidStatesForStage
+} from '@repo/core/organization-model'
+
+const validStates = getValidStatesForStage(CRM_PIPELINE_DEFINITION, 'interested')
+// [{ stateKey: 'discovery_replied', label: '...' }, ...]
+```
+
+Workflows that write `state_key` should import from this definition rather than hardcoding string literals. This keeps the vocabulary in one place and lets the API validate against the allowed set for a deal's current stage.
+
+**Current gap:** `@elevasis/core` v0.13.0 does not yet expose the `organization-model` subpath. Until a new release ships that export, hardcoded strings in `external/elevasis/operations/...` are tracked as follow-up. Document usages with a `// TODO: replace with CRM_PIPELINE_DEFINITION import once @elevasis/core exposes organization-model` comment so they are easy to find.
+
+## Activity Log Conventions
+
+The `acq_deal_activity_log` table uses a `kind` field to distinguish how a state transition was initiated. Two values are relevant for CRM state changes:
+
+- `state_change` -- written by workflow steps (e.g. `crm-send-booking-link.ts` transitioning to `discovery_link_sent`). Carries an `action_taken` payload identifying the workflow.
+- `state_changed_manually` -- written by the `PATCH /api/deals/:dealId/state` route when an operator edits `state_key` directly from the UI. Carries the user id and the before/after state. This is a pure column update with no workflow side-effects.
+
+When reading the audit trail, use `kind` to distinguish automated pipeline progression from manual repair operations. Do not conflate the two when building reports or alerting rules.
+
 ## Verify
 
 Run the relevant checks from the project root:

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

@@ -58,7 +58,9 @@ 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**.
+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**.
+
+Deal list and detail responses include a server-derived `priority` object. Use `deal.priority.bucketKey`, `rank`, `label`, `reason`, `latestActivityAt`, and `nextActionAt` when composing custom deal workspaces or workflow-side follow-up logic instead of re-deriving priority from `updated_at`.
 
 ## 1. Extend CRM Navigation or Sidebar
 
@@ -192,13 +194,15 @@ export const followUpStaleDealsWorkflow: WorkflowDefinition = {
       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'
+        const deals = await crm.listDeals({ stage: input.stage })
+
+        for (const deal of deals) {
+          if (!['follow_up_due', 'stale'].includes(deal.priority.bucketKey)) continue
+
+          await crm.createDealTask({
+            dealId: deal.id,
+            title: 'Follow up',
+            kind: 'email'
           })
           await crm.recordActivity({
             dealId: deal.id,

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,44 @@ 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`, `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.              |
 
 ## 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`, `ListBuilderPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`                          | `@elevasis/ui/features/lead-gen` | Shared lead-gen pages you can route to or wrap                       |
+| `ListActionsProvider`, `useListActions`, `ListBuilderWorkflow`, `ListBuilderRegistry`, MVP workflow form components                                           | `@elevasis/ui/features/lead-gen` | List Builder workflow registry, run modal inputs, and project-owned action wiring |
+| `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                              |
+| `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          |
 
 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
 
@@ -135,19 +137,90 @@ 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`:
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { ListBuilderPage } from '@elevasis/ui/features/lead-gen'
+
+export const Route = createFileRoute('/lead-gen/list-builder/$listId')({
+  component: ListBuilderRoute
+})
+
+function ListBuilderRoute() {
+  const { listId } = Route.useParams()
+  return <ListBuilderPage listId={listId} />
+}
+```
+
+Register project workflow actions at the provider boundary. The shared UI owns the contract; each project owns workflow ids and form choices:
+
+```tsx
+import {
+  CompanyCleanupForm,
+  EmailDiscoveryForm,
+  EmailVerificationForm,
+  WebsiteExtractForm,
+  type ListBuilderRegistry
+} from '@elevasis/ui/features/lead-gen'
+import { ElevasisUIProvider } from '@elevasis/ui/provider'
+
+const listActions: ListBuilderRegistry = [
+  {
+    resourceId: 'lgn-04-email-discovery-workflow',
+    label: 'Email Discovery',
+    description: 'Discover contact email addresses for companies in the list.',
+    category: 'enrich',
+    stagesAffected: ['discovered'],
+    inputForm: EmailDiscoveryForm
+  },
+  {
+    resourceId: 'lgn-05-email-verification-workflow',
+    label: 'Email Verification',
+    description: 'Verify deliverability for contact emails in the list.',
+    category: 'enrich',
+    stagesAffected: ['verified'],
+    inputForm: EmailVerificationForm
+  },
+  {
+    resourceId: 'lgn-02-website-extract-workflow',
+    label: 'Website Extract',
+    description: 'Extract website intelligence for companies in the list.',
+    category: 'scrape',
+    stagesAffected: ['extracted'],
+    inputForm: WebsiteExtractForm
+  },
+  {
+    resourceId: 'lgn-company-cleanup-workflow',
+    label: 'Company Cleanup',
+    description: 'Normalize and clean company records for the list.',
+    category: 'utility',
+    stagesAffected: ['populated'],
+    inputForm: CompanyCleanupForm
+  }
+]
+
+export function App() {
+  return (
+    <ElevasisUIProvider listActions={listActions} {...providerProps}>
+      {children}
+    </ElevasisUIProvider>
+  )
+}
+```
+
 ## 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'
+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 +240,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 +262,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 +349,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