@elevasis/sdk 1.12.0 → 1.13.1

package/reference/claude-config/rules/ui.md

@@ -119,7 +119,7 @@ The API URL is centralized in `ui/src/lib/constants/api.ts`. In the current temp
 Current top-level app sections:
 
 - `/` -- host-local dashboard entrypoint with quick links derived from `organizationModel.navigation.quickAccessSurfaceIds`
-- `/lead-gen/*` -- lead generation pages (`lists`, `companies`, `contacts`, `deliverability`)
+- `/lead-gen/*` -- lead generation pages (`lists`, `companies`, `contacts`)
 - `/crm/*` -- CRM overview, pipeline, and deals
 - `/projects/*` -- delivery feature pages (projects, milestones, tasks, notes)
 - `/operations/*` -- operations overview, resources, command queue, command view, sessions, task scheduler
@@ -193,10 +193,12 @@ Two customization layers are available for every shared feature sidebar:
 
 `manifest.sidebar` accepts any component, so arbitrary customization is always available. The `items` prop is an abstraction barrier for the common case, not a limit.
 
-See `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` for the decision tree, page-wrapping pattern, and delivery's three-section variant. See `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for `NavItem`, `FeatureModule`, and related TypeScript shapes.
-
-## Notes
-
-- `ui/src/routeTree.gen.ts` is generated by TanStack Router tooling. Do not hand-edit it.
+See `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` for the decision tree, page-wrapping pattern, and delivery's three-section variant. For broader CRM extension work across pages, hooks, actions, workflows, and org-model boundaries, start with `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md`. For broader lead-gen extension work across pages, hooks, list/member state, artifacts, touchpoints, workflows, and org-model boundaries, start with `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md`. See `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for `NavItem`, `FeatureModule`, CRM platform primitives, Lead Gen platform primitives, and related TypeScript shapes.
+
+For CRM deal action buttons, read `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` before changing `crmActions`, `DealDetailPage`, `DealDrawer`, or custom workflow buttons. Start with the shared `crmActions` provider path for action visibility, labels, ordering, and render-time configuration. In v1, platform-known/default action endpoint behavior is server-constrained; use project-owned UI that calls the workflow directly when a custom key sits outside that server-dispatched set.
+
+## Notes
+
+- `ui/src/routeTree.gen.ts` is generated by TanStack Router tooling. Do not hand-edit it.
 - The template ships a broad route surface so downstream projects can trim or reshape features without having to re-derive the shared shell contract from scratch.
 - For package-export discovery, glob `node_modules/@elevasis/sdk/reference/` or `node_modules/@repo/ui/dist/` for the current SDK/UI package surface.

package/reference/claude-config/rules/vibe.md

@@ -119,11 +119,17 @@ This routing applies to both codify levels (decision #21 -- Codify ceremony dele
 - **Level A** (config-only edits to `organization-model.ts`, feature toggles, label renames): delegate to `/configure <domain>` immediately.
 - **Level B** (new Zod extension files in `foundations/config/extensions/`): also delegate to `/configure <domain>`; `/configure` gates Level B to explicit user asks before scaffolding a new TS file.
 
-Vibe detects the intent and delegates in both cases. It does not run either pipeline itself.
-
-Heuristics for when to propose codification (passed to `/configure` as context):
-
-- First mention of a new attribute: note to `resume_context`, do not propose yet
+Vibe detects the intent and delegates in both cases. It does not run either pipeline itself.
+
+For "build/extend the CRM" asks, classify the structural org-model portion as Codify, then read `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md` before editing. CRM work often spans org-model sales semantics, shared UI routes, hooks, workflow adapters, and deal actions; do not reduce it to only `sales` config or only UI.
+
+For "build/extend lead gen" / "campaign creator" / "outbound list state" asks, classify the structural org-model portion as Codify, then read `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` before editing. Lead-gen work often spans org-model prospecting semantics, shared UI routes, hooks, list/member state, artifacts, touchpoints, and workflow adapters; do not reduce it to only `prospecting` config or only UI.
+
+For "add a custom CRM action" / "Send Quote button" asks, classify as Codify, then read `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` before editing. Start with the shared `crmActions` provider path for action visibility, labels, ordering, and render-time configuration. In v1, platform-known/default action endpoint behavior is server-constrained; use project-owned UI that calls the workflow directly when a custom key sits outside that server-dispatched set.
+
+Heuristics for when to propose codification (passed to `/configure` as context):
+
+- First mention of a new attribute: note to `resume_context`, do not propose yet
 - Second mention OR explicit declaration ("we're ecom"): propose extension
 - Explicit ask ("track ecom deals separately"): propose immediately with fuller scope
 - Attribute appearing across 3+ tasks: propose adding field to existing extension

package/reference/claude-config/sync-notes/2026-04-27-crm-hitl-action-layer-cutover.md

@@ -36,11 +36,7 @@ Operations-only projects with no CRM surface and no `acq_deals` table can ignore
 pnpm up @elevasis/core @elevasis/ui @elevasis/sdk --latest
 ```
 
-3. If your project has a project-local `acq_deals` table, run the matching atomic cutover migration. The reference SQL lives in the monorepo at `apps/docs/content/docs/in-progress/active-development/sdk-changes/org-model/_sql/`:
-   - `00_preflight_org_model_cutover.sql`
-   - `01_cleanup_known_cutover_outliers.sql`
-   - `02_acq_deals_atomic_cutover.sql`
-   - `03_postflight_org_model_cutover.sql`
+3. If your project has a project-local `acq_deals` table, run a matching atomic cutover migration. The reference SQL that drove the monorepo cutover (preflight, outlier cleanup, atomic cutover, postflight) is no longer checked into the repo -- recover it from git history under `apps/docs/content/docs/in-progress/active-development/sdk-changes/org-model/_sql/` (deleted 2026-04-27 alongside the completed task doc) if you need a starting point.
 
    The cutover is single-shot, not dual-write. Backfill `pipeline_key` / `stage_key` from `cached_stage` and drop the legacy columns in the same transaction. There is no mid-flight rollback path; fix-forward only. Confirm prod deal volume is small enough to accept that tradeoff before applying.
 

package/reference/claude-config/sync-notes/2026-04-27-lead-gen-substrate-train.md

@@ -0,0 +1,110 @@
+# Lead-Gen Substrate Train (Tracks A + B + C)
+
+## Why this note exists
+
+This release train ships the Lead-Gen Substrate Generalization across three coordinated tracks:
+
+- **Track A — Additive Primitives.** New `acq_artifacts` (versioned content: audit PDFs, email drafts, etc.) and `acq_touchpoints` (append-only outreach event log) tables, plus ICP rubric columns (`qualification_score numeric`, `qualification_signals jsonb`, `qualification_rubric_key text`) on `acq_companies` and `acq_contacts`. Purely additive schema — no column drops on these entities.
+- **Track B — Stateful Trait Generalization.** The `(pipeline_key, stage_key, state_key, activity_log)` quartet from the CRM HITL deal cutover is now applied to `acq_lists`, `acq_list_members`, and `acq_list_companies`. Legacy `acq_lists.status`, `acq_list_*.stage`, and `acq_list_*.stage_updated_at` columns are dropped. `acq_companies` and `acq_contacts` are explicitly **excluded** (batch-ETL pattern, not state-machine).
+- **Track C — Campaign Creator UI.** `@elevasis/ui` ships a hooks layer (`useArtifacts`, `useCreateArtifact`, `useTouchpoints`, `useListMembers`, `useListMember`, `useTransitionList`, `useTransitionListMember`, `useTransitionListCompany`, `useDeriveActions`) plus upgraded `LeadGenListsPage` and `LeadGenListDetailPage` (5-tab layout: Overview / Members / Activity / Artifacts / Touchpoints) and a `ListMemberDrawer` deep-linkable via `?member=<id>&memberKind=<contact|company>`.
+
+Concretely, this train introduces:
+
+- a `Stateful` interface + `StatefulSchema` Zod object + generic `TransitionItem<T,TEvent>` / `DeriveActions<T,TAction>` type aliases at `@elevasis/core/business/acquisition/stateful`
+- three `StatefulPipelineDefinition` constants on `@elevasis/core/organization-model` — `ACQ_LISTS_LEAD_GEN_PIPELINE` (single stage `lifecycle` with five states: draft / enriching / launched / closing / archived), `ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE`, `ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE` — plus `findPipeline()` helper and `LEAD_GEN_PIPELINE_DEFINITIONS` map
+- API routes `GET/POST /acquisition/artifacts`, `GET /acquisition/touchpoints`, `GET /acquisition/lists/:listId/members`, `GET /acquisition/list-members/:memberId`, `PATCH /acquisition/lists/:listId/transition`, `PATCH /acquisition/list-members/:memberId/transition`, `PATCH /acquisition/list-companies/:listCompanyId/transition`
+- new flat columns on `acq_artifacts` / `acq_touchpoints` / `acq_lists` / `acq_list_members` / `acq_list_companies` and ICP rubric columns on `acq_companies` / `acq_contacts`
+
+## Applies to
+
+All template-derived projects that:
+
+- consume `@elevasis/core/business/acquisition` types or import the `Stateful` trait / `LEAD_GEN_PIPELINE_DEFINITIONS`
+- render the lead-gen lists / list-detail / Campaign Creator surfaces from `@elevasis/ui/features/lead-gen`
+- have a project-local `acq_*` schema that mirrors the platform tables (artifacts, touchpoints, lists, list-members, list-companies)
+- author workflows under `operations/src/sales/{outreach,prospecting,qualification}/**` that read or write the `acq_lists` / `acq_list_members` / `acq_list_companies` lifecycle columns, or that produce email drafts / audit content / outreach events
+- read `acq_companies.qualification_score` / `qualification_signals` / `qualification_rubric_key`, or the parallel columns on `acq_contacts`
+
+Operations-only projects with no lead-gen surface and no `acq_*` tables can ignore this train.
+
+## Required actions
+
+1. Pull template changes with `/git-sync` so the refreshed lead-gen hook surface, `LeadGenListsPage` upgrades, and `ListMemberDrawer` deep-link wiring are available.
+
+2. After the release train is published, update package versions in the project:
+
+```bash
+pnpm up @elevasis/core @elevasis/ui @elevasis/sdk --latest
+```
+
+3. If your project has project-local `acq_*` tables, run additive + cutover migrations:
+   - **Additive (Track A — safe to apply standalone):** `acq_artifacts` and `acq_touchpoints` table creation (canonical 3-policy RLS — `Platform admins have full access to <table>` / `Org members with acquisition.manage can manage <table>` / `Org members can view <table>`). ICP columns added to `acq_companies` and `acq_contacts` (`qualification_score numeric`, `qualification_signals jsonb`, `qualification_rubric_key text`, all nullable).
+   - **Stateful trait (Track B — atomic cutover, not dual-write):** add `pipeline_key text NOT NULL`, `stage_key text NOT NULL`, `state_key text NOT NULL`, `activity_log jsonb NOT NULL DEFAULT '[]'` to `acq_lists` / `acq_list_members` / `acq_list_companies`; drop `acq_lists.status`, `acq_list_members.{stage,stage_updated_at}`, `acq_list_companies.{stage,stage_updated_at}` in the same transaction.
+   - **Backfill values used in the platform cutover:** `acq_lists` -> `pipeline_key='lead-gen'`, `stage_key='lifecycle'`, `state_key=coalesce(status,'draft')`. `acq_list_members` and `acq_list_companies` -> `pipeline_key='lead-gen'`, `stage_key='outreach'`, `state_key=coalesce(stage,'pending')` (preserves `personalized` / `verified` / `discovered` / `qualified` / `populated` / `extracted` vocabularies losslessly).
+   - The cutover is single-shot. Confirm prod row counts on these tables are small enough to accept fix-forward semantics before applying.
+
+4. Replace any direct lifecycle writes on lists / list-members / list-companies with the new transition surface:
+   - workflow code that previously wrote `acq_lists.status`, `acq_list_members.stage`, or `acq_list_companies.stage` directly must now route through `acqDb.transitionList(...)` / `transitionListMember(...)` / `transitionListCompany(...)`
+   - the API server injects `organizationId` from execution context — never pass `organizationId` from worker payload
+   - the platform-side methods append `ActivityEventSchema`-shaped events to `activity_log`; do NOT also write activity rows from the workflow side
+
+5. Replace `enrichmentData.pipeline.{auditDoc, touchpointCount, lastReply}` writers with `acq_artifacts` / `acq_touchpoints` writes:
+   - audit PDFs / email drafts / proposals -> `acq_artifacts(kind='audit'|'email_draft'|'proposal', owner_kind='company'|'contact'|'list'|'list_member', version=N, content=<jsonb>, source_execution_id=<execution>)`
+   - outreach events -> `acq_touchpoints(direction='outbound'|'inbound', channel='email'|'linkedin'|'sms', kind='initial'|'followup'|'reply'|'nudge', occurred_at=<ts>, payload=<jsonb>, artifact_id=<linked draft>, source_execution_id=<execution>)`
+   - `pipeline_status.pipelineStatus` text enum on `acq_companies` is **untouched** (out of trait scope per Decision B1) — that JSONB key remains canonical for company-level state
+
+6. Adopt the qualification rubric columns:
+   - LLM qualifiers should write `acq_companies.qualification_score` / `qualification_signals` (jsonb shape: `{ status: 'complete' | 'pending' | ..., result?: ..., reason?: ..., completedAt?: ... }`) and stop writing `pipeline_status.qualification`
+   - readers (e.g. `fetch-companies` filters in email-discovery / company-qualification workflows) should use `qualificationSignals?.status === 'complete'` instead of `pipeline_status.qualification?.status`
+   - `qualification_rubric_key` is a free-form text key today; an Org OS rubric registry may land in a later train without a schema change
+
+7. If you read `activity_log` rows on lists / list-members / list-companies and pattern-match by `type`, mirror the flat schema already used for `acq_deals`:
+
+```ts
+{ type: 'state_change', timestamp, stateBefore, stateAfter, reason? }
+{ type: 'stage_change', timestamp, stageBefore, stageAfter, reason? }
+{ type: 'task_created', timestamp, taskId }
+```
+
+8. If you ship lead-gen UI from `@elevasis/ui/features/lead-gen`, the `lists.tsx` and `list-detail.tsx` pages now expect:
+   - `state_key` badge column resolved via `findPipeline('acq.list')` from `LEAD_GEN_PIPELINE_DEFINITIONS`
+   - ICP rubric column reading `list.config.qualification.qualificationRubricKey` (em-dash when absent)
+   - `stateKeyFilter` Select chip in the FilterBar (options sourced from `ACQ_LISTS_LEAD_GEN_PIPELINE.stages[0].states`)
+   - 5-tab detail layout (Overview / Members / Activity / Artifacts / Touchpoints) plus action toolbar fed by `useDeriveActions(list)`
+   - Row-click navigation on the Members tab via `window.history.pushState`, with `useSearch({ strict: false })` reading `?member=<id>&memberKind=<contact|company>` to drive `ListMemberDrawer`
+   - For the `?member=` deep-link to be typed, add `validateSearch` to the project's `routes/lead-gen/lists.$listId.tsx` route file (optional; the drawer reads search params untyped via `strict: false`)
+
+9. Redeploy `operations` after the package upgrades so workers pick up the new typed adapter surface, the artifact/touchpoint writers, and the qualification column writes:
+
+```bash
+pnpm -C operations exec elevasis-sdk deploy --prod
+```
+
+## Verification
+
+Run from the project root after package updates and any DB migration:
+
+```bash
+pnpm -C ui check-types
+pnpm -C ui build
+pnpm -C operations check-types
+pnpm -C operations exec elevasis-sdk check
+```
+
+Then exercise the lead-gen surface:
+
+- open the lists page — confirm the new state-key badge column renders, the ICP rubric column shows either the rubric key or an em-dash, and the FilterBar exposes a state-key Select chip
+- open a list detail — confirm the 5-tab layout (Overview / Members / Activity / Artifacts / Touchpoints), the state-machine progression badge in the Overview tab, and that the Action toolbar in `PageTitleCaption` renders the actions returned by `useDeriveActions(list)`
+- click a member row — confirm the drawer opens, the URL gains `?member=<id>&memberKind=<contact|company>`, the activity / touchpoints / artifacts tabs render, and `onClose` clears both params
+- after the operations redeploy, run a campaign through the qualification + email-discovery workflows; confirm new rows in `acq_artifacts`, new rows in `acq_touchpoints`, and non-null `qualification_score` / `qualification_signals` on the affected `acq_companies` rows
+
+If a workflow that historically wrote `acq_lists.status` / `acq_list_*.stage` throws Zod errors against `StatefulSchema` or fails on missing `state_key`, route it through `acqDb.transitionList(...)` / `transitionListMember(...)` / `transitionListCompany(...)`.
+
+## Not handled by /git-sync
+
+- `/git-sync` does not publish or upgrade `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk`.
+- `/git-sync` does not run the project-local `acq_artifacts` / `acq_touchpoints` table creation, ICP-column additions, or the Stateful-trait cutover on `acq_lists` / `acq_list_members` / `acq_list_companies`. Each of those is owner-authorized and atomic.
+- `/git-sync` does not redeploy the project's `operations` bundle to dev or prod.
+- `/git-sync` does not rewrite project-owned workflow code that bypasses `transitionList` / `transitionListMember` / `transitionListCompany` to write list / member / company stage directly.
+- `/git-sync` does not retire project-local `enrichmentData.pipeline.{auditDoc, touchpointCount, lastReply}` writers — those must be migrated to `acq_artifacts` + `acq_touchpoints` by the project owner.
+- `/git-sync` does not migrate workflow qualifiers off `pipeline_status.qualification` onto `qualification_score` / `qualification_signals` / `qualification_rubric_key`.

package/reference/packages/ui/src/test-utils/README.md

@@ -3,3 +3,5 @@
 Published test helpers for consumers that test Elevasis UI composition.
 
 Use `@elevasis/ui/test-utils` for provider-aware React rendering, WorkOS auth mocks, MSW handlers, and test query clients. Use `@elevasis/ui/test-utils/setup` or `@elevasis/ui/test-utils/setup-integration` from Vitest `setupFiles` when a consumer wants the shared browser and auth mocks.
+
+`renderWithProviders`, `renderHookWithProviders`, and `createTestWrapper` include `ApiClientProvider`, `ElevasisServiceProvider`, `QueryClientProvider`, and `MantineProvider` by default. Tests can override `queryClient`, `getAccessToken`, `organizationId`, `isOrganizationReady`, `apiRequest`, and `isServiceReady` per render.

package/reference/scaffold/index.mdx

@@ -21,11 +21,14 @@ This scaffold reference contains universal documentation that applies to all Ele
 ### 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
-
-### UI Patterns
+- [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

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

@@ -0,0 +1,411 @@
+---
+title: Customize CRM Actions
+description: Add, hide, or replace CRM deal action buttons in a template-derived project, and override default platform action workflows with project-owned implementations.
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Customize CRM Actions
+
+CRM deal pages derive their action buttons from an `ActionDef[]` array. The shared UI reads that array from the provider, filters it with `deriveActions(deal, actions)`, and renders one-click buttons for actions without a `payloadSchema`.
+
+For the broader CRM extension map -- pages, sidebars, hooks, workflow adapters, contracts, and org-model boundaries -- start with [Build and Extend CRM](extend-crm.md). This recipe is only the deal-action path.
+
+**Shape reference:** The `ActionDef` flat shape and the consolidation that replaced the old `handler`/`kind` union are documented in `apps/docs/content/docs/in-progress/active-development/sdk-changes/crm/crm-current-state-assessment.mdx`.
+
+Use this recipe when a user asks for work like:
+
+- "Hide Close Lost from the deal drawer."
+- "Add a Send Quote action to deals in Proposal."
+- "Override Move to Proposal to also create a task in our project tool."
+- "Build a custom deal page that runs one of our workflows."
+
+## How Platform Action Dispatch Works
+
+Every default action in `DEFAULT_CRM_ACTIONS` maps to a deployed workflow via its `workflowId` field. When the shared UI calls `POST /deals/:dealId/actions/:actionKey`, the platform:
+
+1. Validates `isAvailableFor(deal)` server-side (security gate -- cannot be skipped).
+2. Resolves `actionDef.workflowId` to a deployed resource.
+3. Dispatches through `SingleExecutionCoordinator` -- same execution engine as every other workflow.
+4. Returns the refetched deal.
+
+External projects override an action's behavior by deploying a workflow with the same `workflowId` as the default. The resource registry picks the project-owned workflow over the platform default. The `isAvailableFor` predicate is not overridable in V1 -- it stays in `@core` `DEFAULT_CRM_ACTIONS`. Override what the action does, not when the button shows.
+
+## ActionDef Shape
+
+Read the generated contract reference before editing:
+
+`node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+
+The current flat shape (no `handler` nesting, no `kind` discriminator):
+
+```ts
+export interface ActionDef {
+  key: string
+  label: string
+  isAvailableFor: (deal: AcqDealRow) => boolean
+  workflowId: string
+  payloadSchema?: z.ZodTypeAny
+}
+```
+
+`deriveActions(deal, actions)` returns only render-time actions: `{ key, label, payloadSchema? }`. It does not expose `workflowId` or `isAvailableFor` to the browser.
+
+A minimal entry looks like:
+
+```ts
+{
+  key: 'move_to_proposal',
+  label: 'Move to Proposal',
+  isAvailableFor: (deal) => deal.stage_key === 'interested',
+  workflowId: 'move_to_proposal-workflow',
+  payloadSchema: undefined
+}
+```
+
+## acqDb and crm Helpers
+
+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.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.
+
+## Override a Default Action
+
+Deploy a workflow with the same `workflowId` as the default action you want to replace. The resource registry resolves your project-owned workflow first.
+
+The canonical transition workflow (see `external/elevasis/operations/src/sales/crm/actions/move-to-proposal.ts` for the deployed reference):
+
+```ts
+// operations/src/sales/crm/actions/move-to-proposal.ts
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { acqDb } from '@elevasis/sdk/worker'
+import { ActionWorkflowInputSchema, ActionWorkflowOutputSchema } from '../shared/action-workflow-schemas.js'
+
+export const moveToProposalWorkflow: WorkflowDefinition = {
+  config: {
+    resourceId: 'move_to_proposal-workflow',
+    name: 'Move to Proposal',
+    type: 'workflow',
+    version: '1.0.0',
+    status: 'prod',
+    category: 'internal',
+    links: [{ nodeId: 'feature:sales.crm', kind: 'operates-on' }]
+  },
+  contract: {
+    inputSchema: ActionWorkflowInputSchema,
+    outputSchema: ActionWorkflowOutputSchema
+  },
+  steps: {
+    transition: {
+      id: 'transition',
+      name: 'Transition to Proposal',
+      inputSchema: ActionWorkflowInputSchema,
+      outputSchema: ActionWorkflowOutputSchema,
+      handler: async (rawInput, context) => {
+        const { dealId } = rawInput as { dealId: string; organizationId: string }
+        context.logger.info(`[transition] Moving deal ${dealId} to proposal`)
+        await acqDb.transitionDeal({ dealId, toStage: 'proposal' })
+        return { dealId, sent: false }
+      },
+      next: null
+    }
+  },
+  entryPoint: 'transition'
+}
+```
+
+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.
+
+Register the workflow in the operations manifest:
+
+```ts
+// operations/src/index.ts
+import { moveToProposalWorkflow } from './sales/crm/actions/move-to-proposal.js'
+
+export const deploymentSpec = {
+  workflows: [moveToProposalWorkflow],
+  agents: []
+}
+```
+
+Then deploy:
+
+```bash
+pnpm exec elevasis-sdk deploy
+```
+
+## 1. Override the Shared CRM Action Set (UI-Side)
+
+To hide, reorder, or relabel buttons in the shared deal UI, create a local action config module:
+
+```ts
+// ui/src/config/crm-actions.ts
+import { DEFAULT_CRM_ACTIONS, type ActionDef } from '@elevasis/sdk'
+
+export const crmActions: ActionDef[] = [
+  ...DEFAULT_CRM_ACTIONS.filter((action) => action.key !== 'move_to_closed_lost')
+]
+```
+
+To add a new action entry alongside the defaults (note: brand-new keys are not server-dispatched until the platform knows their `workflowId`):
+
+```ts
+// ui/src/config/crm-actions.ts
+import { DEFAULT_CRM_ACTIONS, type ActionDef } from '@elevasis/sdk'
+
+export const crmActions: ActionDef[] = [
+  ...DEFAULT_CRM_ACTIONS,
+  {
+    key: 'send_quote',
+    label: 'Send Quote',
+    isAvailableFor: (deal) => deal.stage_key === 'proposal',
+    workflowId: 'send-quote-workflow'
+  }
+]
+```
+
+Wire it into the app provider. If the template uses `createElevasisApp`, pass it in the app config:
+
+```tsx
+// ui/src/main.tsx
+import { crmActions } from './config/crm-actions'
+
+const App = createElevasisApp({
+  router,
+  apiUrl: API_URL,
+  auth: {
+    clientId: import.meta.env.VITE_WORKOS_CLIENT_ID,
+    redirectUri: import.meta.env.VITE_WORKOS_REDIRECT_URI,
+    devMode: true
+  },
+  theme: { presets: themePresets, background, loader },
+  queryClient,
+  crmActions
+})
+```
+
+If the project hand-wires providers, pass the same array to `ElevasisUIProvider` or `ElevasisCoreProvider`:
+
+```tsx
+<ElevasisUIProvider auth={auth} apiUrl={API_URL} crmActions={crmActions}>
+  <AppRoutes />
+</ElevasisUIProvider>
+```
+
+This controls the shared `DealDetailPage` and `DealDrawer` action row.
+
+## 2. Add a Custom Workflow-Backed Action
+
+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`.
+
+### Define the Workflow Contract
+
+```ts
+// core/types/index.ts
+import { z } from 'zod'
+
+export const sendQuoteInputSchema = z.object({
+  dealId: z.string().uuid(),
+  organizationId: z.string().uuid()
+})
+
+export const sendQuoteOutputSchema = z.object({
+  dealId: z.string().uuid(),
+  sent: z.boolean(),
+  messageId: z.string().optional()
+})
+
+export type SendQuoteInput = z.infer<typeof sendQuoteInputSchema>
+export type SendQuoteOutput = z.infer<typeof sendQuoteOutputSchema>
+```
+
+### Define the Workflow
+
+```ts
+// operations/src/sales/send-quote.ts
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { acqDb, createResendAdapter } from '@elevasis/sdk/worker'
+import {
+  sendQuoteInputSchema,
+  sendQuoteOutputSchema
+} from '@core/types'
+
+export const sendQuoteWorkflow: WorkflowDefinition = {
+  config: {
+    resourceId: 'send-quote-workflow',
+    name: 'Send Quote',
+    type: 'workflow',
+    version: '1.0.0',
+    status: 'dev',
+    category: 'internal',
+    links: [{ nodeId: 'feature:sales.crm', kind: 'operates-on' }]
+  },
+  contract: {
+    inputSchema: sendQuoteInputSchema,
+    outputSchema: sendQuoteOutputSchema
+  },
+  steps: {
+    send: {
+      id: 'send',
+      name: 'Send Quote Email',
+      inputSchema: sendQuoteInputSchema,
+      outputSchema: sendQuoteOutputSchema,
+      handler: async (rawInput, context) => {
+        const { dealId } = rawInput as { dealId: string; organizationId: string }
+        const deal = await acqDb.loadDeal({ dealId })
+
+        const resend = createResendAdapter('my-resend-credential')
+        context.logger.info(`[send-quote] Sending quote for deal ${dealId}`)
+
+        const sent = await resend.sendEmail({
+          to: deal.contact.email,
+          subject: 'Your quote is ready',
+          html: `<p>Your quote is ready. Reply to this email with questions.</p>`
+        })
+
+        await acqDb.recordTouchpoint({
+          dealId,
+          direction: 'outbound',
+          channel: 'email',
+          kind: 'quote_sent',
+          payload: { triggered_by_action: 'send_quote' },
+          contactId: deal.contact.id,
+          sourceExecutionId: context.executionId
+        })
+
+        return {
+          dealId,
+          sent: true,
+          messageId: String(sent.id ?? '')
+        }
+      },
+      next: null
+    }
+  },
+  entryPoint: 'send'
+}
+```
+
+Register the workflow in the operations manifest and deploy:
+
+```ts
+// operations/src/index.ts
+import { sendQuoteWorkflow } from './sales/send-quote.js'
+
+export const deploymentSpec = {
+  workflows: [sendQuoteWorkflow],
+  agents: []
+}
+```
+
+```bash
+pnpm exec elevasis-sdk deploy
+```
+
+### Choose the UI Path
+
+A custom `ActionDef` entry with `workflowId: 'send-quote-workflow'` can be rendered through the shared `crmActions` provider path. Server dispatch through `POST /deals/:dealId/actions/:actionKey` is constrained by the platform-known/default action set in v1, so use a custom deal page or render slot that calls the workflow directly through `/execute` or `/execute-async` when the action key is outside that server-side set.
+
+```tsx
+// ui/src/features/crm/components/SendQuoteButton.tsx
+import { Button } from '@mantine/core'
+import { useMutation } from '@tanstack/react-query'
+import { useElevasisServices } from '@elevasis/ui/provider'
+
+export function SendQuoteButton({ dealId }: { dealId: string }) {
+  const { apiRequest, organizationId } = useElevasisServices()
+
+  const sendQuote = useMutation({
+    mutationFn: async () => {
+      if (!organizationId) throw new Error('Organization context is not ready')
+
+      return apiRequest('/execute-async', {
+        method: 'POST',
+        body: JSON.stringify({
+          resourceType: 'workflow',
+          resourceId: 'send-quote-workflow',
+          input: { dealId, organizationId }
+        })
+      })
+    }
+  })
+
+  return (
+    <Button loading={sendQuote.isPending} onClick={() => sendQuote.mutate()}>
+      Send Quote
+    </Button>
+  )
+}
+```
+
+Use this button through a custom deal route or a `renderActions` slot where available.
+
+## 3. Build a Fully Custom Deal Page
+
+When you own the full page, use the primitives directly:
+
+- `useDealDetail(dealId)` loads the deal.
+- `deriveActions(deal, crmActions)` filters the action set.
+- `useExecuteAction({ dealId })` dispatches platform-known action keys.
+- Project-owned workflow buttons call `/execute` or `/execute-async` directly when they are outside the server-dispatched action set.
+
+```tsx
+import { DEFAULT_CRM_ACTIONS, deriveActions } from '@elevasis/sdk'
+import { Group, Stack } from '@mantine/core'
+import { useMemo } from 'react'
+import { useDealDetail, useExecuteAction } from '@elevasis/ui/hooks'
+import { SendQuoteButton } from './SendQuoteButton'
+
+export function CustomDealPage({ dealId }: { dealId: string }) {
+  const { data: deal } = useDealDetail(dealId)
+  const executeAction = useExecuteAction({ dealId })
+
+  const platformActions = useMemo(() => {
+    return deal ? deriveActions(deal, DEFAULT_CRM_ACTIONS) : []
+  }, [deal])
+
+  if (!deal) return null
+
+  return (
+    <Stack>
+      <Group>
+        {platformActions.map((action) => (
+          <button
+            key={action.key}
+            type="button"
+            onClick={() => executeAction.mutate({ key: action.key })}
+          >
+            {action.label}
+          </button>
+        ))}
+        <SendQuoteButton dealId={deal.id} />
+      </Group>
+    </Stack>
+  )
+}
+```
+
+## Verify
+
+Run the relevant checks from the project root:
+
+```bash
+pnpm -C operations run check
+pnpm -C ui run check
+```
+
+For a workflow-backed action, deploy or run the workflow smoke before wiring it into the UI:
+
+```bash
+pnpm -C operations exec elevasis-sdk check
+pnpm -C operations exec elevasis-sdk deploy
+```