@elevasis/sdk 1.44.3 → 1.46.0

package/reference/scaffold/recipes/add-a-resource.md

@@ -1,25 +1,25 @@
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
----
-title: Add a Resource
-description: Add an OM-owned workflow or agent descriptor, bind executable behavior in operations, and verify descriptor-backed deployment.
----
-
-# Add a Resource
-
-Resources are governed descriptors in the Organization Model. The OM owns resource identity, System membership, owner role, and lifecycle status. Operations code imports those descriptors, attaches executable workflow or agent behavior, and exports a `DeploymentSpec` for deployment.
-
-Do not keep a second identity catalog in operations. `DeploymentSpec` is the runtime/deploy assembly artifact; it should not be the place where a workflow ID is invented.
-
-## 1. Author the OM descriptor
-
-Add the descriptor in `core/config/organization-model.ts`:
-
-```ts
-import { defineResources } from '@elevasis/core/organization-model'
-
-export const resourceDescriptors = defineResources({
+---
+title: Add a Resource
+description: Add an OM-owned workflow or agent descriptor, bind executable behavior in operations, and verify descriptor-backed deployment.
+---
+
+# Add a Resource
+
+Resources are governed descriptors in the Organization Model. The OM owns resource identity, System membership, owner role, and lifecycle status. Operations code imports those descriptors, attaches executable workflow or agent behavior, and exports a `DeploymentSpec` for deployment.
+
+Do not keep a second identity catalog in operations. `DeploymentSpec` is the runtime/deploy assembly artifact; it should not be the place where a workflow ID is invented.
+
+## 1. Author the OM descriptor
+
+Add the descriptor in `core/config/organization-model.ts`:
+
+```ts
+import { defineResources } from '@elevasis/core/organization-model'
+
+export const resourceDescriptors = defineResources({
   myWorkflow: {
     id: 'my-workflow',
     title: 'My Workflow',
@@ -38,79 +38,87 @@ export const resourceDescriptors = defineResources({
       emits: ['operations:event/my-workflow.completed']
     },
     codeRefs: [
-      {
-        path: 'operations/src/my-workflow/index.ts',
-        role: 'entrypoint',
-        symbol: 'myWorkflow'
-      },
-      {
-        path: 'operations/src/my-workflow/my-workflow.test.ts',
-        role: 'test'
-      }
-    ]
-  }
-})
-```
-
-Then expose the descriptor catalog through the Organization Model:
-
-```ts
-export const resourceGovernanceModel = {
-  systems,
-  resources: resourceDescriptors
-} as const
-```
-
+      {
+        path: 'operations/src/my-workflow/index.ts',
+        role: 'entrypoint',
+        symbol: 'myWorkflow'
+      },
+      {
+        path: 'operations/src/my-workflow/my-workflow.test.ts',
+        role: 'test'
+      }
+    ]
+  }
+})
+```
+
+Then expose the descriptor catalog through the Organization Model:
+
+<!-- doc-snippet:skip: illustrative excerpt -- `systems` refers to the System map authored elsewhere in the same organization-model.ts file, not a local declaration -->
+
+```ts
+export const resourceGovernanceModel = {
+  systems,
+  resources: resourceDescriptors
+} as const
+```
+
 Use `organizationModel.resources` as the Resources descriptor catalog. Graph references still use kind-prefixed IDs, such as `system:sales.crm`, `resource:lead-import`, or `action:operations.queue.review`, when runtime behavior needs semantic graph binding.
 
 Use `codeRefs` as repo-relative implementation breadcrumbs for agents and operators. They do not define resource identity, System membership, runtime topology, or graph links; they point from the governed Resource descriptor to the files that implement, validate, or document it.
 
 Use descriptor `title` and `description` for executable display metadata. Use nested `resource.ontology` bindings to declare which ontology actions, objects, catalogs, and events the resource performs, reads, writes, uses, or emits. `resource.ontology.primaryAction` is the default/selectable ontology action and must be included in `resource.ontology.actions`. Optional top-level resource `emits` remains readable for bridge-era event descriptors, but new descriptors should keep event bindings in `resource.ontology.emits`.
-
-## 2. Author executable behavior
-
-Operations code owns schemas, steps, handlers, triggers, and UI execution metadata. Import the descriptor and derive runtime identity from it at the binding boundary:
-
-```ts
-import type { WorkflowDefinition } from '@elevasis/sdk'
-import { resourceDescriptors } from '@core/config/organization-model'
-
-export const myWorkflow: WorkflowDefinition = {
-  config: {
-    resource: resourceDescriptors.myWorkflow,
-    resourceId: resourceDescriptors.myWorkflow.id,
-    name: 'My Workflow',
-    type: resourceDescriptors.myWorkflow.kind,
-    version: '1.0.0',
-    status: 'dev',
-    category: 'production'
-  },
-  contract: {
-    inputSchema,
-    outputSchema
-  },
-  steps: {
-    run: {
-      id: 'run',
-      name: 'Run',
-      handler: async (_input, context) => {
-        context.logger.info('[my-workflow] starting')
-        return { ok: true }
-      },
-      inputSchema,
-      outputSchema,
-      next: null
-    }
-  },
-  entryPoint: 'run'
-}
-```
-
-`category` is one of `production`, `diagnostic`, `internal`, or `testing`.
-
-## 3. Register in the deployment spec
-
-```ts
+
+## 2. Author executable behavior
+
+Operations code owns schemas, steps, handlers, triggers, and UI execution metadata. Import the descriptor and derive runtime identity from it at the binding boundary:
+
+<!-- doc-snippet:skip: illustrative excerpt -- `resourceDescriptors` names the project's own resource-descriptors export from step 1, and `inputSchema`/`outputSchema` are shown unimported for readability -->
+
+```ts
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { resourceDescriptors } from '@core/config/organization-model'
+
+export const myWorkflow: WorkflowDefinition = {
+  config: {
+    resource: resourceDescriptors.myWorkflow,
+    resourceId: resourceDescriptors.myWorkflow.id,
+    name: 'My Workflow',
+    description: resourceDescriptors.myWorkflow.description,
+    type: resourceDescriptors.myWorkflow.kind,
+    version: '1.0.0',
+    status: 'dev',
+    category: 'production'
+  },
+  contract: {
+    inputSchema,
+    outputSchema
+  },
+  steps: {
+    run: {
+      id: 'run',
+      name: 'Run',
+      description: 'Runs the governed work item workflow.',
+      handler: async (_input, context) => {
+        context.logger.info('[my-workflow] starting')
+        return { ok: true }
+      },
+      inputSchema,
+      outputSchema,
+      next: null
+    }
+  },
+  entryPoint: 'run'
+}
+```
+
+`category` is one of `production`, `diagnostic`, `internal`, or `testing`.
+
+## 3. Register in the deployment spec
+
+<!-- doc-snippet:skip: illustrative excerpt with a relative import to the project's own workflow file, not a standalone compilable file -->
+
+```ts
 import { organizationModel } from '@core/config/organization-model'
 import { myWorkflow } from './my-workflow/index.js'
 
@@ -119,40 +127,38 @@ export const org = {
   organizationModel,
   workflows: [myWorkflow],
   agents: []
-}
-```
-
-Use `.js` extensions in TypeScript source imports for ESM compatibility.
-
-## 4. Declare runtime relationships
-
-Use `organizationModel.topology.relationships` for durable execution topology:
+}
+```
+
+Use `.js` extensions in TypeScript source imports for ESM compatibility.
+
+## 4. Declare runtime relationships
+
+Use `organizationModel.topology` for durable execution topology. Author it with the typed helpers rather than by hand — `relationships` is an id-keyed record, not an array, and each relationship uses `from`/`to`:
 
 ```ts
-topology: {
-  relationships: [
-    {
-      source: { kind: 'trigger', id: 'daily-work-item-import' },
-      target: { kind: 'resource', id: 'my-workflow' },
-      kind: 'triggers'
-    },
-    {
-      source: { kind: 'resource', id: 'my-workflow' },
-      target: { kind: 'externalResource', id: 'hubspot' },
-      kind: 'uses'
-    }
-  ]
-}
+import { defineTopology, topologyRef, topologyRelationship } from '@elevasis/core/organization-model'
+
+export const topology = defineTopology({
+  dailyImportTriggersMyWorkflow: topologyRelationship.triggers(
+    topologyRef.trigger('daily-work-item-import'),
+    topologyRef.resource('my-workflow')
+  ),
+  myWorkflowUsesHubspot: topologyRelationship.uses(
+    topologyRef.resource('my-workflow'),
+    topologyRef.externalResource('hubspot')
+  )
+})
 ```
 
+`defineTopology` also accepts an array, in which case it assigns the keys `relationship-1`, `relationship-2`, and so on. Prefer explicit keys — they are what diagnostics name when a reference dangles.
+
 Use relationship kinds `triggers`, `uses`, and `approval` for the initial topology vocabulary. For semantic graph binding, prefer OM ontology IDs in `resource.ontology`; keep `config.links` only when maintaining older descriptors that still need the legacy graph bridge.
-
-## 5. Verify
-
-```bash
+
+## 5. Verify
+
+```bash
 pnpm -C operations check
-pnpm -C operations deploy
-pnpm exec elevasis describe Elevasis/my-workflow
-pnpm scaffold:sync
-pnpm scaffold:verify
+pnpm -C operations run deploy
+pnpm elevasis-sdk describe my-workflow
 ```

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

@@ -12,7 +12,7 @@ CRM deal pages derive their action buttons from an `ActionDef[]` array. The shar
 
 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.
 
-**Shape reference:** The `ActionDef` flat shape and the consolidation that replaced the old `handler`/`kind` union are documented in `apps/docs/content/docs/in-progress/active-development/sdk-changes/crm/crm-current-state-assessment.mdx`.
+**Shape reference:** The `ActionDef` flat shape and the consolidation that replaced the old `handler`/`kind` union are documented in `apps/docs/content/docs/in-progress/active-development/_pipeline/crm/crm-current-state-assessment.mdx`.
 
 Use this recipe when a user asks for work like:
 
@@ -42,6 +42,8 @@ Read the generated contract reference before editing:
 
 The current flat shape (no `handler` nesting, no `kind` discriminator):
 
+<!-- doc-snippet:skip: shape excerpt from derive-actions.ts -- AcqDealRow and z are shown unimported here for readability -->
+
 ```ts
 export interface ActionDef {
   key: string
@@ -56,6 +58,8 @@ export interface ActionDef {
 
 A minimal entry looks like:
 
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
 ```ts
 {
   key: 'move_to_proposal',
@@ -80,7 +84,9 @@ These wrap existing `LeadService` logic -- they are extraction, not new business
 
 Deploy a workflow with the same `workflowId` as the default action you want to replace. The resource registry resolves your project-owned workflow first.
 
-The canonical transition workflow (see `packages/elevasis-operations/src/sales/crm/actions/move-to-proposal.ts` for the deployed reference):
+The canonical transition workflow (see `packages/elevasis/operations/src/sales/crm/actions/move-to-proposal.ts` for the deployed reference):
+
+<!-- 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
@@ -94,6 +100,7 @@ export const moveToProposalWorkflow: WorkflowDefinition = {
     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',
@@ -107,6 +114,7 @@ export const moveToProposalWorkflow: WorkflowDefinition = {
     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) => {
@@ -126,6 +134,8 @@ To add side effects (create a task, send a Slack message, log a deal activity),
 
 Register the workflow in the operations manifest:
 
+<!-- doc-snippet:skip: illustrative excerpt with a relative import to the project's own workflow file, not a standalone compilable file -->
+
 ```ts
 // operations/src/index.ts
 import { moveToProposalWorkflow } from './sales/crm/actions/move-to-proposal.js'
@@ -146,6 +156,8 @@ pnpm exec elevasis-sdk deploy
 
 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 -->
+
 ```ts
 // ui/src/config/crm-actions.ts
 import type { ActionDef } from '@elevasis/sdk'
@@ -156,6 +168,8 @@ export const crmActions: ActionDef[] = platformCrmActions.filter((action) => act
 
 To add a new action entry alongside the defaults (note: brand-new keys are not server-dispatched until the platform knows their `workflowId`):
 
+<!-- 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'
@@ -206,7 +220,7 @@ This controls the shared `DealDetailPage` and `DealDrawer` action row.
 
 For a brand-new action key that calls a project-owned workflow, define the workflow first.
 
-If the action sends email, writes to another channel, or otherwise touches a customer, use `acqDb.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/`.
+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/`.
 
 ### Define the Workflow Contract
 
@@ -231,6 +245,8 @@ export type SendQuoteOutput = z.infer<typeof sendQuoteOutputSchema>
 
 ### Define 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 -->
+
 ```ts
 // operations/src/sales/send-quote.ts
 import type { WorkflowDefinition } from '@elevasis/sdk'
@@ -246,6 +262,7 @@ export const sendQuoteWorkflow: WorkflowDefinition = {
     resource: resourceDescriptors.sendQuote,
     resourceId: resourceDescriptors.sendQuote.id,
     name: 'Send Quote',
+    description: 'Sends a quote email to the deal contact.',
     type: resourceDescriptors.sendQuote.kind,
     version: '1.0.0',
     status: 'dev',
@@ -259,6 +276,7 @@ export const sendQuoteWorkflow: WorkflowDefinition = {
     send: {
       id: 'send',
       name: 'Send Quote Email',
+      description: 'Loads the deal, sends the quote email, and records a deal activity entry.',
       inputSchema: sendQuoteInputSchema,
       outputSchema: sendQuoteOutputSchema,
       handler: async (rawInput, context) => {
@@ -296,6 +314,8 @@ export const sendQuoteWorkflow: WorkflowDefinition = {
 
 Register the workflow in the operations manifest and deploy:
 
+<!-- doc-snippet:skip: illustrative excerpt with a relative import to the project's own workflow file, not a standalone compilable file -->
+
 ```ts
 // operations/src/index.ts
 import { sendQuoteWorkflow } from './sales/send-quote.js'
@@ -400,16 +420,13 @@ export function CustomDealPage({ dealId }: { dealId: string }) {
 
 ## 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/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.
+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.
 
-Within the Elevasis monorepo, import runtime CRM definitions from `@repo/elevasis-core/organization-model`:
+Within the Elevasis monorepo, import the tenant pipeline data from `@repo/elevasis-core/sales` and the generic `getValidStatesForStage` helper from `@repo/core/organization-model`:
 
 ```ts
-import {
-  CRM_PIPELINE_DEFINITION,
-  CRM_DISCOVERY_REPLIED_STATE,
-  getValidStatesForStage
-} from '@repo/elevasis-core/organization-model'
+import { CRM_PIPELINE_DEFINITION, CRM_DISCOVERY_REPLIED_STATE } from '@repo/elevasis-core/sales'
+import { getValidStatesForStage } from '@repo/core/organization-model'
 
 const validStates = getValidStatesForStage(CRM_PIPELINE_DEFINITION, 'interested')
 // [{ stateKey: 'discovery_replied', label: '...' }, ...]
@@ -432,7 +449,7 @@ Run the relevant checks from the project root:
 
 ```bash
 pnpm -C operations run check
-pnpm -C ui run check
+pnpm -C ui run check-types
 ```
 
 For a workflow-backed action, deploy or run the workflow smoke before wiring it into the UI:
@@ -441,5 +458,3 @@ 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
 ```
-
-