@elevasis/sdk 1.24.0 → 1.26.0

package/reference/runtime.mdx

@@ -1,173 +1,172 @@
----
-title: Execution Runtime
-description: How your code runs on the Elevasis platform -- execution lifecycle, concurrency, timeouts, cancellation, error handling, observability, resource limits, and v1 limitations
-loadWhen: "Debugging execution behavior or understanding the runtime model"
----
-
-This page covers everything that happens after you deploy -- how resources execute as managed processes, how failures surface to you, what observability data you can access, and the hard limits enforced on all executions.
-
----
-
-## Execution Lifecycle
-
-### The Four Stages
-
-Every execution traverses four stages: trigger, route, execute, and return.
-
-1. **Trigger** -- A user, CLI command, or API call initiates execution. The platform creates an execution record with `status: 'running'` and generates a unique `executionId`.
-2. **Route** -- The platform resolves the target resource from the registry. All resources (static and external) coexist in a single in-memory registry with no database queries at lookup time.
-3. **Execute** -- An ephemeral worker thread is created from your deployed bundle and sent the execution request. The worker matches the `resourceId` to your definition, validates the input against your Zod schema, and runs the handler. For workflows, steps execute sequentially following the `next` chain. The worker is terminated immediately after execution completes.
-4. **Return** -- The worker posts the result back to the platform. The platform stores the final result, updates the execution record, and fans events out to AI Studio and CLI subscribers.
-
-### Concurrency Model
-
-Workers are ephemeral -- each execution creates a new worker thread. There is no persistent pool:
-
-- **Per-execution isolation:** Each execution gets its own worker thread. Concurrent executions for the same organization run in separate workers with no shared state.
-- **Memory:** Each worker is capped at 256MB. Concurrent workers multiply memory usage proportionally.
-- **No cold start:** Workers are created fresh per execution. Your first execution and hundredth are identical in terms of startup behavior.
-
-### Timeout Enforcement
-
-Timeouts are enforced by the platform. You do not handle them explicitly in your code:
-
-- **Default timeout:** A platform default applies to all resource types unless overridden.
-- **Per-resource override:** Agents can configure `constraints.timeout` in the agent definition. Workflows use the platform default.
-- **Enforcement:** When a timeout fires, the worker is terminated immediately -- even if it is stuck in a synchronous loop. No special handler signature is required on your part.
-
-### Cancellation
-
-Cancellation is initiated by the platform and requires no special code in your handler. The worker is terminated immediately and the execution is recorded as cancelled.
-
-**What triggers cancellation:**
-
-- You call `POST /api/external/executions/:resourceId/:executionId/cancel` via CLI or API
-- The platform timeout expires
-- The resource is deleted while an execution is in-flight
-
----
-
-## Error Handling
-
-### How Errors Reach You
-
-Errors are displayed depending on the surface you use to inspect them:
-
-- **AI Studio:** Shows the error message and execution status. Example: `Remote resource 'onboard-client' failed: Email delivery failed: invalid address`
-- **CLI (`elevasis-sdk execution <resourceId> <id>`):** Shows full execution detail including the error message. The `--json` flag includes an `error` field in structured output.
-- **Error message source:** The error string comes directly from your handler's catch block (`String(err)`). The platform stores this verbatim and displays it as-is. Write descriptive error messages in your handlers -- they surface directly to users.
-
-### What Causes a Failed Execution
-
-- **Unhandled exception in your handler:** The worker reports `status: 'failed'` with the error message.
-- **Memory limit exceeded (256MB):** The worker crashes with an out-of-memory error. The platform catches this; other tenants are unaffected.
-- **Timeout exceeded:** The platform terminates the worker and marks the execution failed with a timeout reason.
-- **Cancellation:** Execution is marked cancelled.
-
----
-
-## Observability
-
-### Logging
-
-You produce logs using standard `console` methods -- no special logger object is needed:
-
-- **Console interception:** The SDK worker runtime intercepts `console.log`, `console.warn`, and `console.error` during handler execution and captures them as structured `{ level, message }` entries.
-- **Level mapping:** `console.log` maps to `info`, `console.warn` maps to `warn`, `console.error` maps to `error`.
-- **No changes required:** Any code that already uses `console.log` automatically has its output captured. Existing code works without modification.
-
-### Log Transport
-
-Logs are delivered to the platform atomically with the execution result:
-
-- **Bundled delivery:** All logs for an execution are included in the result message when the handler completes. There is no real-time streaming -- logs arrive with the final result.
-- **Crash behavior:** If the worker crashes before completing, logs captured up to the crash point are lost. The platform records only the crash error.
-
-### Log Retention and Display
-
-- **Retention:** 30 days by default (configurable per plan).
-- **Real-time fanout:** After execution completes, logs are stored and fanned out to AI Studio and CLI subscribers. AI Studio shows them in the execution detail view.
-- **CLI access:** Use `elevasis-sdk execution <resourceId> <id>` to view execution details including logs.
-
----
-
-## Resource Lifecycle
-
-### Status
-
-Every resource on the platform has a status that you control in your definition:
-
-- **`dev`** -- Default for new resources. Visible in AI Studio and executable, but marked with a "Development" badge. Use this during testing and iteration.
-- **`prod`** -- Set `status: 'prod'` in your resource definition before deploying. No badge. This is the live, production-ready state.
-
-### Versioning
-
-v1 versioning is intentionally simple:
-
-- **One active version per resource per org.** Deploying replaces the running version. There is no version history at the resource level; previous deploys are marked stopped.
-- **Immutable per deploy.** A resource definition is frozen at deploy time. Changing code requires a new deploy.
-
-### Deletion
-
-- **Via CLI:** Remove the resource from your `DeploymentSpec` export and run `elevasis-sdk deploy`. Resources absent from the new bundle are automatically deregistered from the platform.
-- **Via AI Studio:** The delete button unregisters the resource immediately and marks the deployment stopped.
-- **In-flight executions:** Workers already running complete normally. Deletion affects only new execution attempts.
-- **Data retention:** Execution logs and history for a deleted resource are retained for 30 days, then purged.
-
----
-
-## Resource Limits & Quotas
-
-### Per-Worker Limits
-
-Limits enforced per worker thread at runtime:
-
-| Resource         | Value                                                       |
-| ---------------- | ----------------------------------------------------------- |
-| Memory (V8 heap) | 256MB per worker                                            |
-| Disk             | Bundle file only (ephemeral, not persistent across deploys) |
-
-- **Memory:** Enforced by the platform. Exceeding 256MB crashes the worker. The platform catches the error; other tenants are unaffected. If your workflow processes large datasets, consider streaming or batching to stay within the limit.
-- **Disk:** Your bundle is written to disk during deploy and available to the worker at execution time. It is not a persistent write surface -- do not write files to disk from within your handler expecting them to persist.
-
-### Scale Limits
-
-Hard limits to prevent abuse and ensure platform stability:
-
-| Limit                              | Value         |
-| ---------------------------------- | ------------- |
-| Max execution duration (workflows) | 300s (5 min)  |
-| Max execution duration (agents)    | 600s (10 min) |
-| Max log volume                     | 100MB/day     |
-| Max deploy frequency               | 60/day        |
-
-- **Execution duration:** Executions exceeding the timeout are terminated by the platform. The execution is marked failed with a timeout reason.
-- **Log volume:** Total log output across all executions is capped at 100MB per day. Logs beyond this threshold may be truncated.
-- **Deploy frequency:** 60 deploys per day is generous for normal development. This limit prevents accidental deploy loops (for example, a CI pipeline misconfigured to deploy on every commit).
-
-### Networking
-
-- **Outbound:** Unrestricted. Your handlers can call any external API (OpenAI, Twilio, Stripe, etc.) from within the worker.
-- **Inbound:** Workers receive input from the platform coordinator via internal message passing -- they are not exposed to the network directly.
-- **No ports:** Workers communicate with the platform via zero-network-overhead message passing. No port allocation occurs.
-- **Isolation:** Workers have no access to other organizations' data or platform credentials by default. Supabase credentials are not present in the worker environment.
-
----
-
-## v1 Limitations
-
-| Limitation                                      | Reason                                                                                                                                                                                           | Future path                                                                                                             |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| **No nested execution from external resources** | External resources cannot call back to the platform's execution coordinator to trigger other resources as sub-executions.                                                                        | A callback API endpoint that external processes can call to trigger nested executions (requires auth token forwarding). |
-| **No streaming logs**                           | Execution logs are returned in the response body after completion. There is no real-time SSE streaming from within the worker.                                                                   | SSE/WebSocket push from external processes to the platform log system.                                                  |
-| **Static resource priority conflicts**          | If your organization has a static (monorepo) resource with the same ID as a resource in your SDK bundle, the deploy will fail. Static definitions always take priority and cannot be overridden. | Conflict detection is surfaced in the CLI with a clear error message.                                                   |
-
----
-
-## Organization Provisioning
-
-Organization creation is currently admin-only. If you need a new organization provisioned for SDK access, contact the Elevasis team. Self-serve organization creation and API key generation is on the roadmap.
-
----
-
-**Last Updated:** 2026-03-06
+---
+title: Execution Runtime
+description: How your code runs on the Elevasis platform -- execution lifecycle, concurrency, timeouts, cancellation, error handling, observability, resource limits, and v1 limitations
+---
+
+This page covers everything that happens after you deploy -- how resources execute as managed processes, how failures surface to you, what observability data you can access, and the hard limits enforced on all executions.
+
+---
+
+## Execution Lifecycle
+
+### The Four Stages
+
+Every execution traverses four stages: trigger, route, execute, and return.
+
+1. **Trigger** -- A user, CLI command, or API call initiates execution. The platform creates an execution record with `status: 'running'` and generates a unique `executionId`.
+2. **Route** -- The platform resolves the target resource from the registry. All resources (static and external) coexist in a single in-memory registry with no database queries at lookup time.
+3. **Execute** -- An ephemeral worker thread is created from your deployed bundle and sent the execution request. The worker matches the `resourceId` to your definition, validates the input against your Zod schema, and runs the handler. For workflows, steps execute sequentially following the `next` chain. The worker is terminated immediately after execution completes.
+4. **Return** -- The worker posts the result back to the platform. The platform stores the final result, updates the execution record, and fans events out to AI Studio and CLI subscribers.
+
+### Concurrency Model
+
+Workers are ephemeral -- each execution creates a new worker thread. There is no persistent pool:
+
+- **Per-execution isolation:** Each execution gets its own worker thread. Concurrent executions for the same organization run in separate workers with no shared state.
+- **Memory:** Each worker is capped at 256MB. Concurrent workers multiply memory usage proportionally.
+- **No cold start:** Workers are created fresh per execution. Your first execution and hundredth are identical in terms of startup behavior.
+
+### Timeout Enforcement
+
+Timeouts are enforced by the platform. You do not handle them explicitly in your code:
+
+- **Default timeout:** A platform default applies to all resource types unless overridden.
+- **Per-resource override:** Agents can configure `constraints.timeout` in the agent definition. Workflows use the platform default.
+- **Enforcement:** When a timeout fires, the worker is terminated immediately -- even if it is stuck in a synchronous loop. No special handler signature is required on your part.
+
+### Cancellation
+
+Cancellation is initiated by the platform and requires no special code in your handler. The worker is terminated immediately and the execution is recorded as cancelled.
+
+**What triggers cancellation:**
+
+- You call `POST /api/external/executions/:resourceId/:executionId/cancel` via CLI or API
+- The platform timeout expires
+- The resource is deleted while an execution is in-flight
+
+---
+
+## Error Handling
+
+### How Errors Reach You
+
+Errors are displayed depending on the surface you use to inspect them:
+
+- **AI Studio:** Shows the error message and execution status. Example: `Remote resource 'onboard-client' failed: Email delivery failed: invalid address`
+- **CLI (`elevasis-sdk execution <resourceId> <id>`):** Shows full execution detail including the error message. The `--json` flag includes an `error` field in structured output.
+- **Error message source:** The error string comes directly from your handler's catch block (`String(err)`). The platform stores this verbatim and displays it as-is. Write descriptive error messages in your handlers -- they surface directly to users.
+
+### What Causes a Failed Execution
+
+- **Unhandled exception in your handler:** The worker reports `status: 'failed'` with the error message.
+- **Memory limit exceeded (256MB):** The worker crashes with an out-of-memory error. The platform catches this; other tenants are unaffected.
+- **Timeout exceeded:** The platform terminates the worker and marks the execution failed with a timeout reason.
+- **Cancellation:** Execution is marked cancelled.
+
+---
+
+## Observability
+
+### Logging
+
+You produce logs using standard `console` methods -- no special logger object is needed:
+
+- **Console interception:** The SDK worker runtime intercepts `console.log`, `console.warn`, and `console.error` during handler execution and captures them as structured `{ level, message }` entries.
+- **Level mapping:** `console.log` maps to `info`, `console.warn` maps to `warn`, `console.error` maps to `error`.
+- **No changes required:** Any code that already uses `console.log` automatically has its output captured. Existing code works without modification.
+
+### Log Transport
+
+Logs are delivered to the platform atomically with the execution result:
+
+- **Bundled delivery:** All logs for an execution are included in the result message when the handler completes. There is no real-time streaming -- logs arrive with the final result.
+- **Crash behavior:** If the worker crashes before completing, logs captured up to the crash point are lost. The platform records only the crash error.
+
+### Log Retention and Display
+
+- **Retention:** 30 days by default (configurable per plan).
+- **Real-time fanout:** After execution completes, logs are stored and fanned out to AI Studio and CLI subscribers. AI Studio shows them in the execution detail view.
+- **CLI access:** Use `elevasis-sdk execution <resourceId> <id>` to view execution details including logs.
+
+---
+
+## Resource Lifecycle
+
+### Status
+
+Every resource on the platform has a status that you control in your definition:
+
+- **`dev`** -- Default for new resources. Visible in AI Studio and executable, but marked with a "Development" badge. Use this during testing and iteration.
+- **`prod`** -- Set `status: 'prod'` in your resource definition before deploying. No badge. This is the live, production-ready state.
+
+### Versioning
+
+v1 versioning is intentionally simple:
+
+- **One active version per resource per org.** Deploying replaces the running version. There is no version history at the resource level; previous deploys are marked stopped.
+- **Immutable per deploy.** A resource definition is frozen at deploy time. Changing code requires a new deploy.
+
+### Deletion
+
+- **Via CLI:** Remove the resource from your `DeploymentSpec` export and run `elevasis-sdk deploy`. Resources absent from the new bundle are automatically deregistered from the platform.
+- **Via AI Studio:** The delete button unregisters the resource immediately and marks the deployment stopped.
+- **In-flight executions:** Workers already running complete normally. Deletion affects only new execution attempts.
+- **Data retention:** Execution logs and history for a deleted resource are retained for 30 days, then purged.
+
+---
+
+## Resource Limits & Quotas
+
+### Per-Worker Limits
+
+Limits enforced per worker thread at runtime:
+
+| Resource         | Value                                                       |
+| ---------------- | ----------------------------------------------------------- |
+| Memory (V8 heap) | 256MB per worker                                            |
+| Disk             | Bundle file only (ephemeral, not persistent across deploys) |
+
+- **Memory:** Enforced by the platform. Exceeding 256MB crashes the worker. The platform catches the error; other tenants are unaffected. If your workflow processes large datasets, consider streaming or batching to stay within the limit.
+- **Disk:** Your bundle is written to disk during deploy and available to the worker at execution time. It is not a persistent write surface -- do not write files to disk from within your handler expecting them to persist.
+
+### Scale Limits
+
+Hard limits to prevent abuse and ensure platform stability:
+
+| Limit                              | Value         |
+| ---------------------------------- | ------------- |
+| Max execution duration (workflows) | 300s (5 min)  |
+| Max execution duration (agents)    | 600s (10 min) |
+| Max log volume                     | 100MB/day     |
+| Max deploy frequency               | 60/day        |
+
+- **Execution duration:** Executions exceeding the timeout are terminated by the platform. The execution is marked failed with a timeout reason.
+- **Log volume:** Total log output across all executions is capped at 100MB per day. Logs beyond this threshold may be truncated.
+- **Deploy frequency:** 60 deploys per day is generous for normal development. This limit prevents accidental deploy loops (for example, a CI pipeline misconfigured to deploy on every commit).
+
+### Networking
+
+- **Outbound:** Unrestricted. Your handlers can call any external API (OpenAI, Twilio, Stripe, etc.) from within the worker.
+- **Inbound:** Workers receive input from the platform coordinator via internal message passing -- they are not exposed to the network directly.
+- **No ports:** Workers communicate with the platform via zero-network-overhead message passing. No port allocation occurs.
+- **Isolation:** Workers have no access to other organizations' data or platform credentials by default. Supabase credentials are not present in the worker environment.
+
+---
+
+## v1 Limitations
+
+| Limitation                                      | Reason                                                                                                                                                                                           | Future path                                                                                                             |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| **No nested execution from external resources** | External resources cannot call back to the platform's execution coordinator to trigger other resources as sub-executions.                                                                        | A callback API endpoint that external processes can call to trigger nested executions (requires auth token forwarding). |
+| **No streaming logs**                           | Execution logs are returned in the response body after completion. There is no real-time SSE streaming from within the worker.                                                                   | SSE/WebSocket push from external processes to the platform log system.                                                  |
+| **Static resource priority conflicts**          | If your organization has a static (monorepo) resource with the same ID as a resource in your SDK bundle, the deploy will fail. Static definitions always take priority and cannot be overridden. | Conflict detection is surfaced in the CLI with a clear error message.                                                   |
+
+---
+
+## Organization Provisioning
+
+Organization creation is currently admin-only. If you need a new organization provisioned for SDK access, contact the Elevasis team. Self-serve organization creation and API key generation is on the roadmap.
+
+---
+
+**Last Updated:** 2026-03-06

package/reference/scaffold/operations/propagation-pipeline.md

@@ -102,7 +102,7 @@ The external skill doc (`.claude/skills/external/SKILL.md`) remains the workflow
 | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `deps`         | `@elevasis/ui`, `@elevasis/sdk`, `@elevasis/core` versions match template                                                                                                                                                                                                                                                                                   |
 | `tier1`        | registry-backed replace surfaces match template where verification still models them as exact baselines                                                                                                                                                                                                                                                     |
-| `org-os`       | Organization model exists, exports canonical symbols, imports from `@elevasis/core/organization-model`, calls `createFoundationOrganizationModel`, app-config references org model, `__root.tsx` uses `ElevasisSystemsProvider` + `canonicalOrganizationModel`, `main.tsx` uses `createElevasisApp`, all 3 CSS subpath imports present |
+| `org-os`       | Organization model exists, exports canonical symbols, imports from `@elevasis/core/organization-model`, either calls `createFoundationOrganizationModel` or uses explicit `resolveOrganizationModel(..., { mergeDefaults: false })` canonical assembly, app-config references org model, `__root.tsx` uses `ElevasisAuthenticatedShell` / `ElevasisSystemsProvider` + `canonicalOrganizationModel`, `main.tsx` uses `createElevasisApp`, all 3 CSS subpath imports present |
 | `placeholders` | No unresolved `__PROJECT_SLUG__`, `__PROJECT_NAME__`, `__PROJECT_DESCRIPTION__` in key config files                                                                                                                                                                                                                                                         |
 | `scripts`      | `ui` and `operations` `package.json` have required npm scripts                                                                                                                                                                                                                                                                                              |
 | `lib`          | `ui/src/lib/`, `lib/`, `test-utils/` exist with minimum file counts                                                                                                                                                                                                                                                                                         |

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

@@ -23,14 +23,14 @@ Use this recipe when a user asks for work like:
 
 ## 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:
+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 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.
+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.
 
 ## ActionDef Shape
 
@@ -120,7 +120,7 @@ export const moveToProposalWorkflow: WorkflowDefinition = {
 }
 ```
 
-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's `workflowId` in `DEFAULT_CRM_ACTIONS` from `@elevasis/sdk` exactly.
+To add side effects (create a task, send a Slack message, log a deal activity), extend the handler before the `return`. The OM descriptor ID must match the action entry's `workflowId` exactly.
 
 Register the workflow in the operations manifest:
 
@@ -144,23 +144,23 @@ pnpm exec elevasis-sdk deploy
 
 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')
-]
-```
+```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')
+```
 
 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,
+```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',
@@ -357,20 +357,21 @@ When you own the full page, use the primitives directly:
 - `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'
+```tsx
+import { deriveActions } 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, DEFAULT_CRM_ACTIONS) : []
-  }, [deal])
+  const executeAction = useExecuteAction({ dealId })
+
+  const platformActions = useMemo(() => {
+    return deal ? deriveActions(deal, crmActions) : []
+  }, [deal])
 
   if (!deal) return null
 
@@ -395,24 +396,22 @@ export function CustomDealPage({ dealId }: { dealId: string }) {
 
 ## CRM State-Key Source of Truth
 
-`CRM_PIPELINE_DEFINITION` in `packages/core/src/organization-model/domains/sales.ts` is the single canonical source for CRM `state_key` values. It exports a `StatefulPipelineDefinition` that enumerates every valid state per stage (e.g. `interested` → `discovery_replied`, `discovery_link_sent`, `discovery_nudging`, etc.). Named per-state constants (`CRM_DISCOVERY_REPLIED_STATE`, `CRM_DISCOVERY_LINK_SENT_STATE`, and siblings) are also exported for use in conditional logic.
-
-Import via `@repo/core/organization-model`:
-
-```ts
-import {
-  CRM_PIPELINE_DEFINITION,
-  CRM_DISCOVERY_REPLIED_STATE,
-  getValidStatesForStage
-} from '@repo/core/organization-model'
-
-const validStates = getValidStatesForStage(CRM_PIPELINE_DEFINITION, 'interested')
-// [{ stateKey: 'discovery_replied', label: '...' }, ...]
-```
-
-Workflows that write `state_key` should import from this definition rather than hardcoding string literals. This keeps the vocabulary in one place and lets the API validate against the allowed set for a deal's current stage.
-
-**Current gap:** `@elevasis/core` v0.13.0 does not yet expose the `organization-model` subpath. Until a new release ships that export, hardcoded strings in `packages/elevasis-operations/...` are tracked as follow-up. Document usages with a `// TODO: replace with CRM_PIPELINE_DEFINITION import once @elevasis/core exposes organization-model` comment so they are easy to find.
+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/organization-model` 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.
+
+Within the Elevasis monorepo, import runtime CRM definitions from `@repo/elevasis-core/organization-model`:
+
+```ts
+import {
+  CRM_PIPELINE_DEFINITION,
+  CRM_DISCOVERY_REPLIED_STATE,
+  getValidStatesForStage
+} from '@repo/elevasis-core/organization-model'
+
+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.
 
 ## Activity Log Conventions