@elevasis/sdk 1.19.0 → 1.20.0

package/reference/framework/project-structure.mdx

@@ -6,7 +6,7 @@ loadWhen: "Understanding scaffolded files or project layout"
 
 `elevasis-sdk init` creates a complete workspace structure. This page explains what each file does and when you will interact with it.
 
-The current full-stack scaffold uses a workspace layout with `ui/`, `operations/`, `foundations/`, and a root `docs/` directory. When older examples refer to `src/shared/`, read that as the current `foundations/` package for cross-runtime types, schemas, and organization-model configuration.
+The current full-stack scaffold uses a workspace layout with `ui/`, `operations/`, `core/`, and a root `docs/` directory. When older examples refer to `src/shared/`, read that as the current `core/` package for cross-runtime types, schemas, and organization-model configuration.
 
 ---
 
@@ -14,15 +14,17 @@ The current full-stack scaffold uses a workspace layout with `ui/`, `operations/
 
 ### `operations/src/index.ts`
 
-The registry entry point for your workspace. This file aggregates resources from domain barrel files and re-exports them as a `DeploymentSpec` default export. It does not contain workflow logic itself -- its sole job is aggregation:
+The registry entry point for your workspace. This file imports OM resource governance from `core/config/organization-model.ts`, aggregates executable resources from domain barrel files, and re-exports them as a `DeploymentSpec` default export. It does not contain workflow logic itself -- its sole job is assembly:
 
 ```ts
 import type { DeploymentSpec } from '@elevasis/sdk'
+import { resourceGovernanceModel } from '@core/config/organization-model'
 import * as example from './example/index.js'
 import * as emailNotification from './email-notification/exports.js'
 
 const org: DeploymentSpec = {
   version: '0.1.0',
+  organizationModel: resourceGovernanceModel,
   workflows: [...example.workflows, ...emailNotification.workflows],
   agents: [...example.agents, ...emailNotification.agents]
 }
@@ -39,9 +41,9 @@ A multi-step workflow demonstrating real platform API usage. Sends an email noti
 
 The starter workflow, scaffolded to demonstrate the per-file pattern: one workflow per file with its own Zod input/output schemas, config object, contract, and step handler. Replace this domain with your own when you're ready.
 
-### `foundations/`
+### `core/`
 
-Cross-runtime types, schemas, constants, and organization-model configuration shared between the UI and operations packages. Put contracts here when both runtimes need the same validation or labels without depending on app-specific code.
+Cross-runtime types, schemas, constants, and organization-model configuration shared between the UI and operations packages. Put contracts here when both runtimes need the same validation or labels without depending on app-specific code. Resource descriptors live in `core/config/organization-model.ts`.
 
 ### `operations/elevasis.config.ts`
 
@@ -104,7 +106,7 @@ The following directories are included in the scaffold:
 | ------------------------------------ | --------------- | ------------------------------------------------------------------ |
 | `operations/src/example/`            | Scaffold        | Always -- echo starter workflow lives here (replace with your own) |
 | `operations/src/email-notification/` | Scaffold        | Always -- multi-step notification workflow example                 |
-| `foundations/`                       | Scaffold        | Always -- cross-runtime contracts, schemas, and organization model |
+| `core/`                              | Scaffold        | Always -- cross-runtime contracts, schemas, and organization model |
 | `ui/`                                | Scaffold        | Always -- React frontend application                               |
 | `docs/`                              | Scaffold        | Always                                                             |
 | `docs/in-progress/`                  | Agent           | When you create a task doc for in-progress work                    |
@@ -117,7 +119,7 @@ This structure keeps the initial workspace minimal and adds directories only whe
 
 ### `operations/src/lib/`
 
-Shared code directory for utilities used by multiple workflows within the operations package. In the current workspace scaffold, prefer the top-level `foundations/` package for cross-runtime contracts. Included in the esbuild bundle alongside workflow code.
+Shared code directory for utilities used by multiple workflows within the operations package. In the current workspace scaffold, prefer the top-level `core/` package for cross-runtime contracts. Included in the esbuild bundle alongside workflow code.
 
 ### `data/`
 
@@ -182,7 +184,7 @@ The most important file for AI-assisted development. It provides Claude Code wit
 
 - **Project orientation** -- what an Elevasis SDK project is and how it works
 - **Project structure** -- which files contain resources, documentation, and configuration
-- **SDK patterns** -- working code examples for resource definitions, Zod schemas, and the `DeploymentSpec` export
+- **SDK patterns** -- working code examples for descriptor-backed resource definitions, Zod schemas, and the `DeploymentSpec` export
 - **CLI reference** -- all commands with flags (`check`, `deploy`, `exec`, `resources`, `executions`, `execution`, `deployments`, `env list/set/remove`)
 - **Development rules** -- conventions the agent should enforce (source in `src/`, docs in `docs/`, use `@elevasis/sdk` types only)
 
@@ -249,7 +251,7 @@ Not all scaffolded files participate in template updates. Files fall into two ca
 
 - `package.json`, `pnpm-workspace.yaml`, `tsconfig.json`
 - `.env`, `.npmrc`
-- `operations/src/index.ts`, `operations/src/email-notification/index.ts`, `operations/src/email-notification/exports.ts`, `operations/src/example/echo.ts`, `operations/src/example/index.ts`, `foundations/`
+- `operations/src/index.ts`, `operations/src/email-notification/index.ts`, `operations/src/email-notification/exports.ts`, `operations/src/example/echo.ts`, `operations/src/example/index.ts`, `core/`
 - `docs/index.md`, `docs/in-progress/.gitkeep`
 
 **MANAGED** -- Written during initial scaffold and updated when the template evolves:

package/reference/packages/core/src/business/README.md

@@ -2,7 +2,7 @@
 
 Published base entity contracts for the Elevasis platform. Each entity ships as a TypeScript interface, a matching Zod schema, and an inferred `Input` type, generic over a `<TMeta>` extension slot.
 
-External projects extend these in `foundations/types/entities.ts` to attach project-specific metadata while keeping the canonical shape stable.
+External projects extend these in `core/types/entities.ts` to attach project-specific metadata while keeping the canonical shape stable.
 
 ## Published Exports
 
@@ -49,4 +49,4 @@ export type Deal = BaseDeal
 
 The full pattern is documented in the SDK scaffold bundle: `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-a-base-entity.md`.
 
-The canonical template demo lives at `external/_template/foundations/types/entities.ts`.
+The canonical template demo lives at `external/_template/core/types/entities.ts`.

package/reference/packages/core/src/organization-model/README.md

@@ -47,10 +47,13 @@ Top-level fields:
 - `offerings`
 - `roles`
 - `goals`
+- `systems`
+- `resources`
 - `statuses`
 - `operations`
+- `knowledge`
 
-Resources bind to the graph from deployment metadata through `links` and `category`.
+Resource identity is authored in `resources.entries`. Runtime workflows, agents, and integrations import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
 
 ## Feature Set
 
@@ -77,6 +80,10 @@ Cross-collection links use kind-prefixed IDs:
 - `resource:lead-import`
 - `capability:operations.queue.review`
 
+## Resource Descriptors
+
+The OM Resources domain is governance-only. Descriptors declare canonical `id`, required `systemId`, governance `status`, and optional role ownership. `DeploymentSpec` remains the runtime/deploy assembly around those descriptors, not a second resource identity catalog.
+
 ## Resolution Semantics
 
 - `defineOrganizationModel()` is a typed helper.
@@ -92,11 +99,11 @@ Cross-collection links use kind-prefixed IDs:
 - Child feature IDs require ancestor feature nodes.
 - Container features omit `path`.
 - Leaf features provide `path`.
-- Resource links are validated against graph node IDs during registry registration.
+- Systems, resources, roles, knowledge nodes, and goals must resolve their declared cross-references.
 
 ## Practical Guidance
 
 - Use `resolveOrganizationModel()` when you need a runtime-safe model.
 - Use `defineOrganizationModel()` when authoring static overrides.
 - Keep feature IDs stable because shell routing, gating, breadcrumbs, and docs depend on them.
-- Put semantic resource relationships on resource metadata, not on feature nodes.
+- Put resource identity and governance in `resources.entries`; attach executable behavior in operations.

package/reference/resources/index.mdx

@@ -1,12 +1,12 @@
 ---
 title: Writing Resources
-description: Guide to creating workflows and agents using WorkflowDefinition, AgentDefinition, and DeploymentSpec with the Elevasis SDK
+description: Guide to creating descriptor-backed workflows and agents with the Elevasis SDK
 loadWhen: "Building or modifying a workflow"
 ---
 
-Resources are the building blocks of your Elevasis project. A resource is a workflow or agent definition that the platform can execute on your behalf. You define them in TypeScript, export them from a single entry point, and the platform handles scheduling, retries, logging, and execution.
+Resources are the building blocks of your Elevasis project. Resource identity and governance metadata live in the Organization Model under `organizationModel.resources.entries`; operations code imports those descriptors, attaches executable workflow or agent behavior, and exports a `DeploymentSpec` for deployment.
 
-This page covers how to structure your resources, write step handlers, and export everything through `DeploymentSpec`.
+This page covers how to structure executable resources, derive runtime IDs from OM descriptors, write step handlers, and assemble the deployment spec without creating a second identity catalog.
 
 ## WorkflowDefinition
 
@@ -24,6 +24,7 @@ A complete workflow definition has four required properties:
 ```typescript
 import { z } from 'zod';
 import type { WorkflowDefinition } from '@elevasis/sdk';
+import { resourceDescriptors } from '@core/config/organization-model';
 
 const echoInput = z.object({
   message: z.string(),
@@ -37,9 +38,10 @@ type EchoInput = z.infer<typeof echoInput>;
 
 const echoWorkflow: WorkflowDefinition = {
   config: {
-    resourceId: 'echo',
+    resource: resourceDescriptors.echo,
+    resourceId: resourceDescriptors.echo.id,
     name: 'Echo',
-    type: 'workflow',
+    type: resourceDescriptors.echo.kind,
     description: 'Returns the input message unchanged',
     version: '1.0.0',
     status: 'dev',
@@ -68,16 +70,17 @@ const echoWorkflow: WorkflowDefinition = {
 
 ### config
 
-The `config` block identifies the workflow on the platform:
-
-| Field         | Type              | Description                                                                                                         |
-| ------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `resourceId`  | `string`          | Unique lowercase ID within your organization (e.g., `send-welcome-email`). Used by the CLI to target this resource. |
-| `name`        | `string`          | Human-readable display name shown in the dashboard.                                                                 |
-| `type`        | `'workflow'`      | Always the literal string `'workflow'` for workflow resources.                                                      |
-| `description` | `string`          | Summary shown in the dashboard and command center.                                                                  |
-| `version`     | `string`          | Semver string (e.g., `'1.0.0'`). Increment when making breaking changes to the contract.                            |
-| `status`      | `'dev' | 'prod'` | Controls availability. Use `'dev'` while building. See [Resource Status](#resource-status).                         |
+The `config` block binds executable behavior to the OM resource descriptor:
+
+| Field         | Type              | Description                                                                                                                        |
+| ------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `resource`    | `ResourceEntry`   | OM descriptor from `core/config/organization-model.ts`; owns stable identity, kind, system membership, ownership, and status.      |
+| `resourceId`  | `string`          | Derived from `resource.id`. Used by runtime invocation, CLI targeting, execution logs, and dashboard links. Do not invent it here. |
+| `name`        | `string`          | Human-readable display name shown in the dashboard.                                                                                |
+| `type`        | `'workflow'`      | Derived from `resource.kind` for workflow resources.                                                                               |
+| `description` | `string`          | Summary shown in the dashboard and command center.                                                                                 |
+| `version`     | `string`          | Semver string (e.g., `'1.0.0'`). Increment when making breaking changes to the contract.                                           |
+| `status`      | `'dev' | 'prod'` | Controls runtime availability. Use `'dev'` while building. See [Resource Status](#resource-status).                                |
 | `domains`     | `string[]`        | Optional. Groups resources in the command center view.                                                              |
 
 ### contract
@@ -271,10 +274,14 @@ Agents are autonomous resources that use an LLM and tools to complete a goal. Yo
 
 ```typescript
 import type { AgentDefinition } from '@elevasis/sdk';
+import { resourceDescriptors } from '@core/config/organization-model';
 
 const myAgent: AgentDefinition = {
   config: {
+    resource: resourceDescriptors.myAgent,
+    resourceId: resourceDescriptors.myAgent.id,
     name: 'my-agent',
+    type: resourceDescriptors.myAgent.kind,
     description: 'Answers questions using platform tools',
     status: 'dev',
   },
@@ -291,12 +298,15 @@ const myAgent: AgentDefinition = {
 
 ## DeploymentSpec
 
-All resources must be exported through a `DeploymentSpec` default export from `src/index.ts`. This is the entry point the platform reads when you deploy.
+All executable resources must be assembled through a `DeploymentSpec` default export from `operations/src/index.ts`. This is the entry point the platform reads when you deploy. Include the Organization Model payload so the validator can compare code-backed resources against OM descriptors.
 
 ```typescript
 import type { DeploymentSpec } from '@elevasis/sdk';
+import { resourceGovernanceModel } from '@core/config/organization-model';
 
 const org: DeploymentSpec = {
+  version: '0.1.0',
+  organizationModel: resourceGovernanceModel,
   workflows: [echoWorkflow, pipeline],
   agents: [
     // myAgent,
@@ -306,7 +316,7 @@ const org: DeploymentSpec = {
 export default org;
 ```
 
-Each resource's `config.resourceId` is used as its identifier on the platform. These IDs appear in CLI output (`elevasis-sdk resources`), execution commands (`elevasis-sdk exec`), and the dashboard.
+Each resource's `config.resourceId` is still the deployed runtime identifier. The important authoring rule is that `config.resourceId` derives from the OM descriptor (`resource.id`) instead of being duplicated by hand.
 
 ### Resource Status
 

package/reference/scaffold/core/organization-model.mdx

@@ -1,6 +1,6 @@
 ---
 title: Organization Model
-description: Organization OS Model layer documentation for the flat feature hierarchy, semantic domains, resource graph links, and curated @elevasis/core public API.
+description: Organization OS Model layer documentation for the flat feature hierarchy, semantic domains, resource descriptors, and curated @elevasis/core public API.
 ---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
@@ -38,10 +38,13 @@ Top-level fields on `OrganizationModel`:
 - `offerings`
 - `roles`
 - `goals`
+- `systems`
+- `resources`
 - `statuses`
 - `operations`
+- `knowledge`
 
-Resources are not authored inside `OrganizationModel`. Deployable workflows, agents, triggers, integrations, external resources, and human checkpoints declare graph links on their resource metadata.
+Resource identity is authored inside `OrganizationModel.resources.entries`. Runtime workflows, agents, and integrations import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
 
 ## Feature Shape
 
@@ -74,7 +77,7 @@ Development-only features remain defined and enabled with `devOnly: true`; shell
 
 Navigation surfaces may also carry `devOnly` for compatibility with the legacy/domain navigation model. `knowledge.command-view` is intentionally development-only while its graph visualization modes continue to mature.
 
-## Graph IDs and Resource Links
+## Graph IDs and Resource Descriptors
 
 Cross-collection links use kind-prefixed graph IDs:
 
@@ -83,18 +86,30 @@ Cross-collection links use kind-prefixed graph IDs:
 - `resource:lead-import`
 - `capability:operations.queue.review`
 
-Example resource metadata:
+Resource identity is authored in the OM Resources domain. Operations imports descriptors from `organizationModel.resources.entries` and derives runtime `resourceId` / `type` while attaching executable behavior.
 
 ```ts
-config: {
-  resourceId: 'lead-import',
-  name: 'Lead Import',
-  type: 'workflow',
-  version: '1.0.0',
-  status: 'prod',
-  links: [{ nodeId: 'feature:sales.lead-gen', kind: 'operates-on' }],
-  category: 'production'
-}
+import { defineResources } from '@elevasis/core/organization-model'
+
+export const resourceDescriptors = defineResources({
+  leadImport: {
+    id: 'lead-import',
+    kind: 'workflow',
+    systemId: 'sys.prospecting',
+    ownerRoleId: 'role-ops-lead',
+    status: 'active',
+    capabilityKey: 'prospecting.lead-import'
+  }
+})
+
+export const resourceGovernanceModel = {
+  systems: {
+    systems
+  },
+  resources: {
+    entries: Object.values(resourceDescriptors)
+  }
+} as const
 ```
 
 ## Domain Semantics
@@ -105,7 +120,10 @@ The model keeps business semantics in named domains:
 - `prospecting` -- company/contact lifecycle stages
 - `projects` -- project, milestone, and task statuses
 - `identity`, `customers`, `offerings`, `roles`, `goals` -- organizational reality
+- `systems` -- bounded contexts that group governed operational resources
+- `resources` -- governance-only workflow, agent, and integration descriptors
 - `statuses` and `operations` -- runtime/vibe-layer semantic registries
+- `knowledge` -- playbooks, strategies, references, and graph-governing links
 
 ## Authoring and Resolution
 
@@ -124,8 +142,9 @@ The model keeps business semantics in named domains:
 - container/leaf path rules
 - valid sidebar positions
 - reality-domain cross references such as offering target segments and role reporting lines
+- system, resource, role, knowledge, and goal cross references used by resource governance
 
-Resource graph links are validated during resource registry registration because resources live in deployment specs.
+`DeploymentSpec` remains the runtime/deploy assembly around these descriptors. It is not the source of resource identity.
 
 ## Provider Integration
 

package/reference/scaffold/operations/workflow-recipes.md

@@ -16,21 +16,24 @@ description: Anatomy of a workflow, adapter usage, and trigger patterns -- runna
 
 Every workflow is a `WorkflowDefinition` object with four top-level keys: `config`, `contract`, `steps`, and `entryPoint`. The `email-notification` workflow at `operations/src/email-notification/index.ts` is used as the running example throughout this section.
 
-### Config
-
-```typescript
-config: {
-  resourceId: 'email-notification', // Unique ID -- used in API calls and CLI
-  name: 'Email Notification',       // Human-readable display name
-  type: 'workflow',                  // Always 'workflow' (vs 'agent')
-  description: 'Sends a notification email to a user...',
-  version: '1.0.0',                  // Bump on contract changes
-  status: 'dev'                      // 'dev' or 'prod'
-}
-```
-
-- `resourceId` is the stable identifier used by `pnpm exec elevasis exec` and `/execute` API calls.
-- Bump `version` whenever you change `contract.inputSchema` or `contract.outputSchema`.
+### Config
+
+```typescript
+import { resourceDescriptors } from '@core/config/organization-model'
+
+config: {
+  resource: resourceDescriptors.emailNotification,
+  resourceId: resourceDescriptors.emailNotification.id,
+  name: 'Email Notification',
+  type: resourceDescriptors.emailNotification.kind,
+  description: 'Sends a notification email to a user...',
+  version: '1.0.0',
+  status: 'dev'
+}
+```
+
+- The OM Resources descriptor owns the stable ID and kind. Runtime execution still uses that deployed `resourceId`, but workflow authoring should derive it from the descriptor.
+- Bump `version` whenever you change `contract.inputSchema` or `contract.outputSchema`.
 
 ### Contract
 
@@ -389,7 +392,7 @@ pnpm exec elevasis --prod exec Elevasis/email-notification --input '{...}'
 
 ## 4. Registry Pattern
 
-Workflows are discovered through `operations/src/index.ts`, which exports a `DeploymentSpec` as its default export.
+Workflows are discovered through `operations/src/index.ts`, which exports a `DeploymentSpec` as its default export. The spec assembles deployable runtime resources; it is not a second resource identity catalog.
 
 **Pattern:** each feature group in `operations/src/` has its own exports barrel. The top-level spec spreads all groups:
 
@@ -407,15 +410,17 @@ operations/src/
 Top-level registry (`operations/src/index.ts`):
 
 ```typescript
-import type { DeploymentSpec } from '@elevasis/sdk'
-import * as example from './example/index.js'
-import * as emailNotification from './email-notification/exports.js'
-
-const org: DeploymentSpec = {
-  version: '0.1.0',
-  workflows: [...example.workflows, ...emailNotification.workflows],
-  agents: [...example.agents, ...emailNotification.agents]
-}
+import type { DeploymentSpec } from '@elevasis/sdk'
+import { resourceGovernanceModel } from '@core/config/organization-model'
+import * as example from './example/index.js'
+import * as emailNotification from './email-notification/exports.js'
+
+const org: DeploymentSpec = {
+  version: '0.1.0',
+  organizationModel: resourceGovernanceModel,
+  workflows: [...example.workflows, ...emailNotification.workflows],
+  agents: [...example.agents, ...emailNotification.agents]
+}
 export default org
 ```
 
@@ -431,10 +436,11 @@ export const agents: never[] = []
 
 **Adding a new workflow:**
 
-1. Create `operations/src/<feature>/index.ts` with the `WorkflowDefinition`.
-2. Create `operations/src/<feature>/exports.ts` with `workflows` and `agents` arrays.
-3. Import the group barrel in `operations/src/index.ts` and spread into `workflows`/`agents`.
-4. Run `pnpm -C operations check` to validate, then `pnpm -C operations deploy` to publish.
+1. Add the resource descriptor to `core/config/organization-model.ts`.
+2. Create `operations/src/<feature>/index.ts` with the `WorkflowDefinition`, deriving `config.resourceId` and `config.type` from the descriptor.
+3. Create `operations/src/<feature>/exports.ts` with `workflows` and `agents` arrays.
+4. Import the group barrel in `operations/src/index.ts` and spread into `workflows`/`agents`.
+5. Run `pnpm -C operations check` to validate descriptor/code alignment, then `pnpm -C operations deploy` to publish.
 
 **Note:** Use `.js` extensions in imports even though the source is TypeScript. The TypeScript compiler and esbuild bundler both require this for ESM interoperability.
 

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

@@ -82,13 +82,28 @@ function AnalyticsLayout() {
 
 ## 4. Add backing resources
 
-For workflows or agents that power the feature, declare graph links on the resource metadata:
+For workflows or agents that power the feature, author an OM Resource descriptor first, then derive runtime metadata from it:
 
 ```ts
+// core/config/organization-model.ts
+import { defineResources } from '@elevasis/core/organization-model'
+
+export const resourceDescriptors = defineResources({
+  analyticsRefresh: {
+    id: 'analytics-refresh',
+    kind: 'workflow',
+    systemId: 'sys.analytics',
+    ownerRoleId: 'role-ops-lead',
+    status: 'active'
+  }
+})
+
+// operations/src/analytics-refresh/index.ts
 config: {
-  resourceId: 'analytics-refresh',
+  resource: resourceDescriptors.analyticsRefresh,
+  resourceId: resourceDescriptors.analyticsRefresh.id,
   name: 'Analytics Refresh',
-  type: 'workflow',
+  type: resourceDescriptors.analyticsRefresh.kind,
   version: '1.0.0',
   status: 'prod',
   links: [{ nodeId: 'feature:analytics', kind: 'operates-on' }],

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

@@ -1,6 +1,6 @@
 ---
 title: Add a Resource
-description: Add a workflow or agent with resource metadata, graph links, and deployment verification.
+description: Add an OM-owned workflow or agent descriptor, bind executable behavior in operations, and verify descriptor-backed deployment.
 ---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
@@ -8,18 +8,58 @@ description: Add a workflow or agent with resource metadata, graph links, and de
 
 # Add a Resource
 
-Resources are workflows, agents, triggers, integrations, external systems, or human checkpoints collected in a `DeploymentSpec`. They link into the Organization Model graph through resource metadata, not through `OrganizationModel` mapping tables.
+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.
 
-## 1. Author the resource
+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',
+    kind: 'workflow',
+    systemId: 'sys.operations',
+    ownerRoleId: 'role-ops-lead',
+    status: 'active',
+    capabilityKey: 'operations.my-workflow'
+  }
+})
+```
+
+Then expose the descriptor catalog through the Organization Model:
+
+```ts
+export const resourceGovernanceModel = {
+  systems: {
+    systems
+  },
+  resources: {
+    entries: Object.values(resourceDescriptors)
+  }
+} as const
+```
+
+Use `organizationModel.resources.entries` as the Resources descriptor catalog. `links[].nodeId` still uses the kind-prefixed graph grammar, such as `feature:sales.crm`, `integration:instantly`, or `capability:operations.queue.review`, when a runtime resource needs semantic graph binding.
+
+## 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: {
-    resourceId: 'my-workflow',
+    resource: resourceDescriptors.myWorkflow,
+    resourceId: resourceDescriptors.myWorkflow.id,
     name: 'My Workflow',
-    type: 'workflow',
+    type: resourceDescriptors.myWorkflow.kind,
     version: '1.0.0',
     status: 'dev',
     links: [{ nodeId: 'feature:operations', kind: 'operates-on' }],
@@ -46,17 +86,17 @@ export const myWorkflow: WorkflowDefinition = {
 }
 ```
 
-`links[].nodeId` uses the kind-prefixed graph grammar, such as `feature:sales.crm`, `integration:instantly`, or `capability:operations.queue.review`.
-
 `category` is one of `production`, `diagnostic`, `internal`, or `testing`.
 
-## 2. Register in the deployment spec
+## 3. Register in the deployment spec
 
 ```ts
+import { resourceGovernanceModel } from '@core/config/organization-model'
 import { myWorkflow } from './my-workflow/index.js'
 
 export const org = {
   version: '0.1.0',
+  organizationModel: resourceGovernanceModel,
   workflows: [myWorkflow],
   agents: []
 }
@@ -64,7 +104,7 @@ export const org = {
 
 Use `.js` extensions in TypeScript source imports for ESM compatibility.
 
-## 3. Declare runtime relationships
+## 4. Declare runtime relationships
 
 Use `DeploymentSpec.relationships` for execution topology:
 
@@ -79,7 +119,7 @@ relationships: {
 
 Use `config.links` for semantic graph binding and `relationships` for runtime execution relationships.
 
-## 4. Verify
+## 5. Verify
 
 ```bash
 pnpm -C operations check

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

@@ -84,13 +84,15 @@ The canonical transition workflow (see `packages/elevasis-operations/src/sales/c
 // 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: {
-    resourceId: 'move_to_proposal-workflow',
+    resource: resourceDescriptors.moveToProposal,
+    resourceId: resourceDescriptors.moveToProposal.id,
     name: 'Move to Proposal',
-    type: 'workflow',
+    type: resourceDescriptors.moveToProposal.kind,
     version: '1.0.0',
     status: 'prod',
     category: 'internal',
@@ -119,7 +121,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 `resourceId` 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's `workflowId` in `DEFAULT_CRM_ACTIONS` from `@elevasis/sdk` exactly.
 
 Register the workflow in the operations manifest:
 
@@ -232,6 +234,7 @@ export type SendQuoteOutput = z.infer<typeof sendQuoteOutputSchema>
 // 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
@@ -239,9 +242,10 @@ import {
 
 export const sendQuoteWorkflow: WorkflowDefinition = {
   config: {
-    resourceId: 'send-quote-workflow',
+    resource: resourceDescriptors.sendQuote,
+    resourceId: resourceDescriptors.sendQuote.id,
     name: 'Send Quote',
-    type: 'workflow',
+    type: resourceDescriptors.sendQuote.kind,
     version: '1.0.0',
     status: 'dev',
     category: 'internal',
@@ -315,9 +319,11 @@ A custom `ActionDef` entry with `workflowId: 'send-quote-workflow'` can be rende
 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 SendQuoteButton({ dealId }: { dealId: string }) {
   const { apiRequest, organizationId } = useElevasisServices()
+  const resourceId = resourceDescriptors.sendQuote.id
 
   const sendQuote = useMutation({
     mutationFn: async () => {
@@ -327,7 +333,7 @@ export function SendQuoteButton({ dealId }: { dealId: string }) {
         method: 'POST',
         body: JSON.stringify({
           resourceType: 'workflow',
-          resourceId: 'send-quote-workflow',
+          resourceId,
           input: { dealId, organizationId }
         })
       })