@elevasis/sdk 1.55.0 → 1.57.0

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

@@ -1,192 +1,121 @@
+---
+title: Customize CRM Actions
+description: Add, hide, reorder, or re-implement CRM deal action buttons by authoring them in your project's Organization Model and deploying the workflows they dispatch to.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
----
-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.
----
 
 # 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`.
+CRM deal action buttons are authored in the Organization Model, not in code. Each button is one `actionTypes` record under the `sales.crm` System's ontology scope. The record carries the button's label, its order in the action bar, the conditions under which it appears, and the id of the deployed resource it dispatches to.
 
-For the broader CRM extension map -- pages, sidebars, hooks, workflow adapters, System Interfaces, and org-model boundaries -- start with [Build and Extend CRM](extend-crm.md). This recipe is only the deal-action path.
+`compileCrmActionCatalog` turns those records into a `CompiledCrmAction[]`. The shared UI reads that array from the provider and filters it per deal with `deriveCompiledCrmActions`; the API re-checks the same conditions server-side before dispatching.
 
-**Shape reference:** The `ActionDef` flat shape and the consolidation that replaced the old `handler`/`kind` union are documented in `apps/docs/content/docs/technical/features/operations/crm/index.mdx`.
+For the broader CRM extension map -- pages, sidebars, hooks, workflow adapters, System Interfaces, and org-model boundaries -- start with [Build and Extend CRM](extend-crm.md). This recipe is only the deal-action path.
 
 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."
+- "Change what Move to Proposal does."
+- "Reorder the deal action buttons."
 - "Build a custom deal page that runs one of our workflows."
 
-## How Platform Action Dispatch Works
-
-Every action in the CRM action catalog 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 action entry. The resource registry picks the project-owned workflow over the platform default. The `isAvailableFor` predicate comes from the caller-supplied action catalog; override what the action does and keep button availability aligned with the server-side gate.
-
-CRM action dispatch is an API-backed surface. The tenant Organization Model must expose an active and ready `sales.crm.apiInterface` marker before shared CRM action buttons are considered ready. If a lead-gen workflow hands off into CRM, model that crossing through lead-gen resources that bind the CRM pipeline plus a scoped topology grant to `sales.crm.apiInterface` instead of making base lead-gen readiness depend on CRM catalogs.
-
-## ActionDef Shape
-
-Read the generated contract reference before editing:
+## One Action, One Record
 
-`operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+An action exists exactly once, in the OM. There is no second array to keep in sync and no override-by-shadowing mechanism -- the record's `resourceId` is the single binding between the button and the code that runs.
 
-The current flat shape (no `handler` nesting, no `kind` discriminator):
+The ontology id's local id **is** the action key used in `POST /deals/:dealId/actions/:actionKey`. `sales.crm:action/move_to_proposal` is the `move_to_proposal` button.
 
-<!-- doc-snippet:skip: shape excerpt from derive-actions.ts -- AcqDealRow and z are shown unimported here for readability -->
+<!-- doc-snippet:skip: illustrative OM excerpt -- one entry from the sales.crm System's ontology.actionTypes map -->
 
 ```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:
-
-<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
-
-```ts
-{
-  key: 'move_to_proposal',
+// core/config/organization-model.ts, under the sales.crm System
+'sales.crm:action/move_to_proposal': {
+  id: 'sales.crm:action/move_to_proposal',
   label: 'Move to Proposal',
-  isAvailableFor: (deal) => deal.stage_key === 'interested',
-  workflowId: 'move_to_proposal-workflow',
-  payloadSchema: undefined
+  description: 'Advance a qualified CRM deal into the proposal stage.',
+  ownerSystemId: 'sales.crm',
+  order: 10,
+  actsOn: ['sales.crm:object/deal'],
+  resourceId: 'move_to_proposal-workflow',
+  availableFrom: { stageKeys: ['interested'] },
+  effects: [
+    { kind: 'setProperty', objectType: 'sales.crm:object/deal', property: 'stage', to: 'proposal' },
+    { kind: 'emitEvent', eventType: 'sales.crm:event/deal.stage-changed' }
+  ]
 }
 ```
 
-## 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 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.
+| Field           | Meaning                                                                                                                                 |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`         | Button text. Falls back to the action key when omitted.                                                                                 |
+| `order`         | Position in the deal action bar. Records without one sort after every ordered record, in id order.                                      |
+| `resourceId`    | The deployed workflow this action dispatches to. Required for any record with `availableFrom`.                                          |
+| `availableFrom` | When the button appears. Omit the whole field to keep a record in the ontology without making it a deal action.                         |
+| `actsOn`        | The ontology object the action operates on.                                                                                             |
+| `effects`       | Declarative record of what the action changes. Read by the graph and by knowledge nodes; it does not execute -- the workflow does that. |
 
-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.
+### `availableFrom`
 
-## Override a Default Action
+Three optional dimensions, all evaluated against the deal row:
 
-Deploy a workflow with the same `workflowId` as the default action you want to replace. The resource registry resolves your project-owned workflow first.
+```
+stageKeys       deal.stage_key   (required, at least one)
+stateKeys       deal.state_key   (optional)
+nextActionKeys  deal.nextAction  (optional)
+```
 
-The canonical transition workflow (see `packages/elevasis/operations/src/sales/crm/actions/move-to-proposal.ts` for the deployed reference):
+Dimensions **AND** together; membership within one dimension is **OR**; an omitted dimension is unconstrained. So this button shows only for a deal that is in the `interested` stage, sitting in one of three states, and whose derived next action is `send_reply`:
 
-<!-- doc-snippet:skip: illustrative excerpt -- `resourceDescriptors` names the project's own resource-descriptors export, and `../shared/action-workflow-schemas.js` is a project-local sibling file -->
+<!-- doc-snippet:skip: illustrative excerpt -- the availableFrom fragment of an actionTypes record -->
 
 ```ts
-// operations/src/sales/crm/actions/move-to-proposal.ts
-import type { WorkflowDefinition } from '@elevasis/sdk'
-import { acqDb } from '@elevasis/sdk/worker'
-import { resourceDescriptors } from '@core/config/organization-model'
-import { ActionWorkflowInputSchema, ActionWorkflowOutputSchema } from '../shared/action-workflow-schemas.js'
-
-export const moveToProposalWorkflow: WorkflowDefinition = {
-  config: {
-    resource: resourceDescriptors.moveToProposal,
-    resourceId: resourceDescriptors.moveToProposal.id,
-    name: 'Move to Proposal',
-    description: 'Transition a deal to the proposal stage.',
-    type: resourceDescriptors.moveToProposal.kind,
-    version: '1.0.0',
-    status: 'prod',
-    category: 'internal',
-  },
-  contract: {
-    inputSchema: ActionWorkflowInputSchema,
-    outputSchema: ActionWorkflowOutputSchema
-  },
-  steps: {
-    transition: {
-      id: 'transition',
-      name: 'Transition to Proposal',
-      description: 'Call transitionDeal to move the deal to the proposal stage',
-      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'
+availableFrom: {
+  stageKeys: ['interested'],
+  stateKeys: ['discovery_replied', 'discovery_link_sent', 'discovery_nudging'],
+  nextActionKeys: ['send_reply']
 }
 ```
 
-To add side effects (create a task, send a Slack message, log a deal activity), extend the handler before the `return`. The OM descriptor ID must match the action entry's `workflowId` exactly.
+Every `stageKeys` entry must be a stage in the CRM pipeline catalog, and every `stateKeys` entry must be a valid state for one of the declared stages. `compileCrmActionCatalog` checks both and reports every violation at once as a `SystemInterfaceReadinessError` carrying `SYSTEM_INTERFACE_INVALID` issues -- which reaches an API caller as a 503 with `readinessCode`, not a silent missing button.
 
-Register the workflow in the operations manifest:
+## Compile the Catalog
 
-<!-- doc-snippet:skip: illustrative excerpt with a relative import to the project's own workflow file, not a standalone compilable file -->
+<!-- doc-snippet:skip: illustrative excerpt -- `@core/config/organization-model` is the project's own OM alias -->
 
 ```ts
-// operations/src/index.ts
-import { moveToProposalWorkflow } from './sales/crm/actions/move-to-proposal.js'
+// ui/src/config/crm-actions.ts
+import { compileCrmActionCatalog, compileCrmApiOntologyValidationIndex, type CompiledCrmAction } from '@elevasis/sdk'
+import { organizationModel } from '@core/config/organization-model'
 
-export const deploymentSpec = {
-  workflows: [moveToProposalWorkflow],
-  agents: []
-}
+export const crmActions: CompiledCrmAction[] = compileCrmActionCatalog(
+  compileCrmApiOntologyValidationIndex(organizationModel)
+)
 ```
 
-Then deploy:
+`compileCrmApiOntologyValidationIndex` proves the `sales.crm` System Interface is ready -- active `apiInterface` marker, resolvable scoped resources, a non-empty pipeline catalog -- before the action catalog compiles against it. CRM action dispatch is an API-backed surface: if that marker is missing or disabled, compilation throws rather than producing a catalog of buttons that would 503 on click.
 
-```bash
-pnpm exec elevasis-sdk deploy
-```
+If a lead-gen workflow hands off into CRM, model that crossing through lead-gen resources that bind the CRM pipeline plus a scoped topology grant to `sales.crm.apiInterface` -- not by making base lead-gen readiness depend on CRM catalogs.
 
-## 1. Override the Shared CRM Action Set (UI-Side)
+The compiled shape:
 
-To hide, reorder, or relabel buttons in the shared deal UI, create a local action config module:
-
-<!-- doc-snippet:skip: illustrative excerpt with a relative import to the project's own platform-crm-actions module, not a standalone compilable file -->
+<!-- doc-snippet:skip: shape excerpt from compile-action-catalog.ts -->
 
 ```ts
-// ui/src/config/crm-actions.ts
-import type { ActionDef } from '@elevasis/sdk'
-import { platformCrmActions } from './platform-crm-actions'
-
-export const crmActions: ActionDef[] = platformCrmActions.filter((action) => action.key !== 'move_to_closed_lost')
+export interface CompiledCrmAction {
+  key: string
+  label: string
+  availableFrom: CompiledCrmActionAvailability
+  resourceId: string
+  payloadSchema?: z.ZodTypeAny
+}
 ```
 
-To add a new action entry alongside the defaults (note: brand-new keys are not server-dispatched until the platform knows their `workflowId`):
+### Wire It Into the Provider
 
-<!-- doc-snippet:skip: illustrative excerpt with a relative import to the project's own platform-crm-actions module, not a standalone compilable file -->
-
-```ts
-// ui/src/config/crm-actions.ts
-import type { ActionDef } from '@elevasis/sdk'
-import { platformCrmActions } from './platform-crm-actions'
-
-export const crmActions: ActionDef[] = [
-  ...platformCrmActions,
-  {
-    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:
+If the template uses `createElevasisApp`, pass it in the app config:
 
 ```tsx
 // ui/src/main.tsx
@@ -214,48 +143,47 @@ If the project hand-wires providers, pass the same array to `ElevasisUIProvider`
 </ElevasisUIProvider>
 ```
 
-This controls the shared `DealDetailPage` and `DealDrawer` action row.
+This drives the shared `DealDetailPage` and `DealDrawer` action rows.
 
-## 2. Add a Custom Workflow-Backed Action
+## How Dispatch Works
 
-For a brand-new action key that calls a project-owned workflow, define the workflow first.
+When the shared UI calls `POST /deals/:dealId/actions/:actionKey`, the platform:
 
-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 `packages/elevasis/operations/src/sales/crm/actions/`.
+1. Loads the deal and finds the compiled action by key.
+2. Re-evaluates `availableFrom` against the deal server-side. This is the security gate and cannot be skipped -- a client that fabricates an action key or calls one out of stage gets a 400.
+3. Validates the payload against the action's `payloadSchema`, and rejects any payload sent to an action that declares none.
+4. Appends an `action_taken` entry to the deal's activity log, before the handler runs -- operator intent is recorded separately from effect.
+5. Resolves `resourceId` to the deployed resource and dispatches through `SingleExecutionCoordinator`, the same execution engine as every other workflow.
+6. Returns the refetched deal.
 
-### Define the Workflow Contract
+### Payload Schemas Are Platform-Registered
 
-```ts
-// core/types/index.ts
-import { z } from 'zod'
+A Zod schema is not serializable model data, so `payloadSchema` cannot be authored in the OM. `compileCrmActionCatalog` resolves it from a small registry in published core, keyed by action key. Today only `send_reply` has one (`replyBody`). An action with no registered schema is a one-click button and rejects any payload.
 
-export const sendQuoteInputSchema = z.object({
-  dealId: z.string().uuid(),
-  organizationId: z.string().uuid()
-})
+Adding a payload schema for a new action key is platform work, not scaffold work. Until then, take input through a custom UI path that calls the workflow directly (see [Custom Deal Page](#build-a-fully-custom-deal-page) below).
 
-export const sendQuoteOutputSchema = z.object({
-  dealId: z.string().uuid(),
-  sent: z.boolean(),
-  messageId: z.string().optional()
-})
+## Add an Action
 
-export type SendQuoteInput = z.infer<typeof sendQuoteInputSchema>
-export type SendQuoteOutput = z.infer<typeof sendQuoteOutputSchema>
-```
+Three steps, in order.
 
-### Define the Workflow
+### 1. Define and Deploy the Workflow
 
-<!-- doc-snippet:skip: illustrative excerpt -- `resourceDescriptors` names the project's own resource-descriptors export, and `sendQuoteInputSchema`/`sendQuoteOutputSchema` are the schemas defined in the previous step, not yet added to this project's real core/types/index.ts -->
+Workflows backing CRM actions use worker adapters instead of raw Supabase calls. The acquisition adapter is imported as `acqDb` from `@elevasis/sdk/worker`:
+
+- `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 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.
+
+The separate `crm` adapter exposes focused CRM methods such as `crm.recordActivity(...)`; use `acqDb` for action workflows that need deal transitions and the broader acquisition substrate.
+
+<!-- doc-snippet:skip: illustrative excerpt -- `resourceDescriptors` names the project's own resource-descriptors export, and the schemas are project-local -->
 
 ```ts
 // operations/src/sales/send-quote.ts
 import type { WorkflowDefinition } from '@elevasis/sdk'
 import { acqDb, createResendAdapter } from '@elevasis/sdk/worker'
 import { resourceDescriptors } from '@core/config/organization-model'
-import {
-  sendQuoteInputSchema,
-  sendQuoteOutputSchema
-} from '@core/types'
+import { sendQuoteInputSchema, sendQuoteOutputSchema } from '@core/types'
 
 export const sendQuoteWorkflow: WorkflowDefinition = {
   config: {
@@ -265,8 +193,8 @@ export const sendQuoteWorkflow: WorkflowDefinition = {
     description: 'Sends a quote email to the deal contact.',
     type: resourceDescriptors.sendQuote.kind,
     version: '1.0.0',
-    status: 'dev',
-    category: 'internal',
+    status: 'prod',
+    category: 'internal'
   },
   contract: {
     inputSchema: sendQuoteInputSchema,
@@ -299,11 +227,7 @@ export const sendQuoteWorkflow: WorkflowDefinition = {
           payload: { triggered_by_action: 'send_quote', channel: 'email' }
         })
 
-        return {
-          dealId,
-          sent: true,
-          messageId: String(sent.id ?? '')
-        }
+        return { dealId, sent: true, messageId: String(sent.id ?? '') }
       },
       next: null
     }
@@ -312,9 +236,11 @@ export const sendQuoteWorkflow: WorkflowDefinition = {
 }
 ```
 
-Register the workflow in the operations manifest and deploy:
+If the action sends email, writes to another channel, or otherwise touches a customer, use `acqDb.recordDealActivity` inside the handler so the audit trail reflects it. For an Instantly-thread-aware variant that prefers in-thread replies and falls back to fresh outbound, see the canonical CRM action examples in `packages/elevasis/operations/src/sales/crm/actions/`.
+
+Register and deploy:
 
-<!-- doc-snippet:skip: illustrative excerpt with a relative import to the project's own workflow file, not a standalone compilable file -->
+<!-- doc-snippet:skip: illustrative excerpt with a relative import to the project's own workflow file -->
 
 ```ts
 // operations/src/index.ts
@@ -330,71 +256,118 @@ export const deploymentSpec = {
 pnpm exec elevasis-sdk deploy
 ```
 
-### Choose the UI Path
+### 2. Author the Action Record
 
-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.
+Add one entry to the `sales.crm` System's `ontology.actionTypes`, with `resourceId` matching the deployed resource id exactly:
 
-```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'
-import { resourceDescriptors } from '@core/config/organization-model'
+<!-- doc-snippet:skip: illustrative OM excerpt -->
 
-export function SendQuoteButton({ dealId }: { dealId: string }) {
-  const { apiRequest, organizationId } = useElevasisServices()
-  const resourceId = resourceDescriptors.sendQuote.id
+```ts
+'sales.crm:action/send_quote': {
+  id: 'sales.crm:action/send_quote',
+  label: 'Send Quote',
+  description: 'Email the current quote to the deal contact.',
+  ownerSystemId: 'sales.crm',
+  order: 25,
+  actsOn: ['sales.crm:object/deal'],
+  resourceId: 'send-quote-workflow',
+  availableFrom: { stageKeys: ['proposal'] }
+}
+```
 
-  const sendQuote = useMutation({
-    mutationFn: async () => {
-      if (!organizationId) throw new Error('Organization context is not ready')
+The local id (`send_quote`) becomes the action key. Underscores are legal in a local id; the format is `system.path:kind/local-id`, parsed and formatted through the core ontology helpers rather than by splitting strings.
 
-      return apiRequest('/execute-async', {
-        method: 'POST',
-        body: JSON.stringify({
-          resourceType: 'workflow',
-          resourceId,
-          input: { dealId, organizationId }
-        })
-      })
-    }
-  })
+### 3. Deploy the Organization Model
 
-  return (
-    <Button loading={sendQuote.isPending} onClick={() => sendQuote.mutate()}>
-      Send Quote
-    </Button>
-  )
+The compiled catalog is derived from the OM, so the button appears once the model carrying it is deployed. Run the model deployment the same way you deploy any OM change in your project; `om:doctor` validates the ontology before it lands.
+
+## Hide, Relabel, or Reorder an Action
+
+All three are OM edits on the existing record -- no code change, no filtering array.
+
+| Want                     | Do                                                                                                            |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| Hide the button entirely | Remove the record, or remove its `availableFrom` to keep it in the ontology without surfacing it as a button. |
+| Change when it appears   | Edit `availableFrom.stageKeys` / `stateKeys` / `nextActionKeys`.                                              |
+| Change the button text   | Edit `label`.                                                                                                 |
+| Change its position      | Edit `order`.                                                                                                 |
+
+Removing a record removes it from both the UI and the server-side dispatch set at once, because both read the same catalog. Note that removing an ontology id from a model whose snapshot is already deployed leaves that snapshot stale until the model is deployed again.
+
+## Change What an Action Does
+
+Edit the workflow the record's `resourceId` points at, or point `resourceId` at a different deployed resource. There is no same-name shadowing mechanism and no platform default to fall back to -- whatever id the record names is what runs.
+
+The canonical transition workflow, for reference (see `packages/elevasis/operations/src/sales/crm/actions/move-to-proposal.ts`):
+
+<!-- doc-snippet:skip: illustrative excerpt -- `resourceDescriptors` names the project's own resource-descriptors export, and `../shared/action-workflow-schemas.js` is a project-local sibling file -->
+
+```ts
+// operations/src/sales/crm/actions/move-to-proposal.ts
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { acqDb } from '@elevasis/sdk/worker'
+import { resourceDescriptors } from '@core/config/organization-model'
+import { ActionWorkflowInputSchema, ActionWorkflowOutputSchema } from '../shared/action-workflow-schemas.js'
+
+export const moveToProposalWorkflow: WorkflowDefinition = {
+  config: {
+    resource: resourceDescriptors.moveToProposal,
+    resourceId: resourceDescriptors.moveToProposal.id,
+    name: 'Move to Proposal',
+    description: 'Transition a deal to the proposal stage.',
+    type: resourceDescriptors.moveToProposal.kind,
+    version: '1.0.0',
+    status: 'prod',
+    category: 'internal'
+  },
+  contract: {
+    inputSchema: ActionWorkflowInputSchema,
+    outputSchema: ActionWorkflowOutputSchema
+  },
+  steps: {
+    transition: {
+      id: 'transition',
+      name: 'Transition to Proposal',
+      description: 'Call transitionDeal to move the deal to the proposal stage',
+      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'
 }
 ```
 
-Use this button through a custom deal route or a `renderActions` slot where available.
+To add side effects (create a task, send a Slack message, log a deal activity), extend the handler before the `return`. Keep the record's `effects` in step with what the handler actually changes -- `effects` is what the graph and knowledge nodes read.
 
-Keep the same interface boundary for direct workflow buttons: custom UI may render read-only deal context without API readiness, but buttons that call `/execute`, `/execute-async`, or CRM action routes should be hidden or disabled until the relevant System Interface and any scoped topology grant are ready.
-
-## 3. Build a Fully Custom Deal Page
+## 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.
+- `deriveCompiledCrmActions(deal, crmActions)` returns the subset the deal can currently invoke, in authored order.
+- `useExecuteAction({ dealId })` dispatches by action key.
+- A button for something that is not a CRM deal action calls `/execute` or `/execute-async` directly.
 
 ```tsx
-import { deriveActions } from '@elevasis/sdk'
+import { deriveCompiledCrmActions } from '@elevasis/sdk'
 import { Group, Stack } from '@mantine/core'
 import { useMemo } from 'react'
 import { useDealDetail, useExecuteAction } from '@elevasis/ui/hooks'
 import { crmActions } from '../config/crm-actions'
-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, crmActions) : []
+  const actions = useMemo(() => {
+    return deal ? deriveCompiledCrmActions(deal, crmActions) : []
   }, [deal])
 
   if (!deal) return null
@@ -402,22 +375,55 @@ export function CustomDealPage({ dealId }: { dealId: string }) {
   return (
     <Stack>
       <Group>
-        {platformActions.map((action) => (
-          <button
-            key={action.key}
-            type="button"
-            onClick={() => executeAction.mutate({ key: action.key })}
-          >
+        {actions.map((action) => (
+          <button key={action.key} type="button" onClick={() => executeAction.mutate({ key: action.key })}>
             {action.label}
           </button>
         ))}
-        <SendQuoteButton dealId={deal.id} />
       </Group>
     </Stack>
   )
 }
 ```
 
+For a direct-workflow button, call `/execute-async` with the resource id:
+
+```tsx
+// ui/src/features/crm/components/RunAuditButton.tsx
+import { Button } from '@mantine/core'
+import { useMutation } from '@tanstack/react-query'
+import { useElevasisServices } from '@elevasis/ui/provider'
+import { resourceDescriptors } from '@core/config/organization-model'
+
+export function RunAuditButton({ dealId }: { dealId: string }) {
+  const { apiRequest, organizationId } = useElevasisServices()
+  const resourceId = resourceDescriptors.runAudit.id
+
+  const runAudit = 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,
+          input: { dealId, organizationId }
+        })
+      })
+    }
+  })
+
+  return (
+    <Button loading={runAudit.isPending} onClick={() => runAudit.mutate()}>
+      Run Audit
+    </Button>
+  )
+}
+```
+
+Keep the same interface boundary for direct workflow buttons: custom UI may render read-only deal context without API readiness, but buttons that call `/execute`, `/execute-async`, or CRM action routes should be hidden or disabled until the relevant System Interface and any scoped topology grant are ready.
+
 ## CRM State-Key Source of Truth
 
 CRM `stage_key` and `state_key` values are tenant/runtime data. In the Elevasis workspace, the canonical CRM pipeline definition lives in `@repo/elevasis-core/sales` and is authored into the `sales.crm:catalog/crm.pipeline` ontology catalog on the canonical organization model. Published `@elevasis/core` keeps only generic `StatefulPipelineDefinition` types/helpers and transport schemas.
@@ -432,7 +438,7 @@ const validStates = getValidStatesForStage(CRM_PIPELINE_DEFINITION, 'interested'
 // [{ stateKey: 'discovery_replied', label: '...' }, ...]
 ```
 
-Template-derived projects should define their own CRM catalog/action config in project code rather than importing Elevasis runtime constants from published core.
+Template-derived projects author their own CRM pipeline catalog in their own OM rather than importing Elevasis runtime constants from published core. The stage and state keys an action's `availableFrom` may name are exactly the ones that catalog defines.
 
 ## Activity Log Conventions
 
@@ -458,3 +464,5 @@ For a workflow-backed action, deploy or run the workflow smoke before wiring it
 pnpm -C operations exec elevasis-sdk check
 pnpm -C operations exec elevasis-sdk deploy
 ```
+
+A compiled catalog that silently comes back shorter than expected means a record was skipped for want of `availableFrom`; a `SYSTEM_INTERFACE_INVALID` throw means a `stageKeys`/`stateKeys` entry names something the pipeline catalog does not define, or a record declares `availableFrom` with no `resourceId`. Both are reported with the offending ontology id.

package/reference/scaffold/recipes/customize-organization-model.md

@@ -103,7 +103,9 @@ System field reference:
 - `actions` -- references to the cross-cutting actions domain.
 - `ontology` -- System-owned object, link, action, catalog, event, surface, interface, value-type, property, or group records.
 - `config` -- JSON-serializable settings local to this System.
-- `systems` -- nested child Systems. Use this for new recursive authoring; `subsystems` is a compatibility alias only.
+- `systems` -- nested child Systems. Use this for new recursive authoring; `subsystems` is a retired spelling, accepted on input only.
+
+**A parsed model no longer carries children under both keys.** Parsing used to mirror `systems` into `subsystems`, so either spelling could be read off any parsed System. That mirror is gone: children now live under whichever key the author wrote. Anything walking the tree must read `system.systems ?? system.subsystems` -- reading `subsystems` alone looked correct only because the mirror was filling it in.
 
 ## Ontology