@elevasis/sdk 1.13.1 → 1.14.0

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

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

package/reference/scaffold/recipes/index.md

@@ -22,23 +22,23 @@ You want a new shell feature (e.g., `analytics`) with its own nav entry, sidebar
 **[Add a Resource](add-a-resource.md)**
 You want a new workflow or agent deployed to the platform. Covers `WorkflowDefinition` authoring, `DeploymentSpec` registration, relationship declarations, domain mapping, and CLI verification.
 
-**[Gate by Feature or Admin](gate-by-feature-or-admin.md)**
-You want to restrict a route, nav item, or UI element by feature flag or admin role. Covers the decision table, `FeatureGuard`, `AdminGuard`, nav-entry visibility fields, per-member `MembershipFeatureConfig` overrides, and the settings-asymmetry gotcha.
-
-**[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
+**[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