@elevasis/sdk 1.18.0 → 1.20.0

package/reference/claude-config/sync-notes/2026-05-09-clients-domain.md

@@ -0,0 +1,32 @@
+# Clients Domain Release Train
+
+## Why this note exists
+
+The clients domain release train adds client-management surfaces across the shared platform packages and updates template-facing project guidance. Template-derived projects need the new package baselines and guidance before they rely on the clients CLI, published clients UI feature exports, or project skill client-linkage instructions.
+
+## Applies to
+
+Template-derived projects that consume `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk`, especially projects that expose client management in UI shells or use the SDK CLI for project/client linkage.
+
+## Required actions
+
+- Pull the updated template dependency baselines for `core/package.json`, `ui/package.json`, and `operations/package.json` after the release stages publish new package versions.
+- Review project-local usage of project/client CLI flags and prefer `--client` / `--clear-client` for client linkage; keep `--client-company-id` only for the legacy company field.
+- If the project maintains local Claude skill guidance, reconcile the project skill client-linkage wording with the updated template baseline.
+- Smoke the clients UI route only after the project has the updated `@elevasis/ui` baseline.
+
+## Verification
+
+Run the package-specific checks after sync:
+
+```bash
+pnpm -C core check-types
+pnpm -C operations check-types
+pnpm -C ui check-types
+```
+
+For projects adopting the clients UI immediately, also open the clients list and detail routes and verify the route renders with the current organization selected.
+
+## Not handled by /git-sync
+
+`/git-sync` can propagate template baselines and guidance, but it does not publish packages, deploy the SDK resources bundle, decide project-specific client data migration policy, or validate tenant-specific WorkOS/Supabase data availability.

package/reference/claude-config/sync-notes/2026-05-09-command-system.md

@@ -0,0 +1,33 @@
+# 2026-05-09 -- Command System SDK Release Train
+
+## Why this note exists
+
+This train adds SDK CLI catalog, acquisition CLI read, API-key external route, and deterministic knowledge-routing changes to the existing SDK release queue. It publishes updated `@elevasis/core` and `@elevasis/sdk` baselines, then syncs the template dependency pins to derived projects.
+
+## Applies to
+
+- Template-derived projects consuming `@elevasis/core` or `@elevasis/sdk`.
+- Operators using `elevasis-sdk cli`, `acquisition:list:*`, `acquisition:deal:*`, `client:*`, or generated `/knowledge` routing guidance.
+- Projects that rely on API-key-gated SDK CLI access to platform external routes.
+
+## Required actions
+
+1. Pull the synced template changes through `/git-sync`.
+2. Accept the package baseline bumps published by this train:
+   - `core/package.json`: `@elevasis/core`
+   - `operations/package.json`: `@elevasis/core` and `@elevasis/sdk`
+3. Verify local `operations` commands still have the expected platform key environment variables before using SDK CLI API calls.
+4. Review local operator guidance if the project documents SDK CLI command discovery or acquisition/client/deal command usage.
+
+## Verification
+
+- `pnpm -C operations check`
+- `pnpm -C operations check-types`
+- `pnpm -C operations test`
+- `pnpm -C core test`
+
+## Not handled by /git-sync
+
+- Platform API route deployment remains an Elevasis monorepo/API deployment concern.
+- Tenant-specific platform keys and API base URLs remain project-owned secrets and environment configuration.
+- Project-authored knowledge nodes and routing guidance remain project-owned content.

package/reference/claude-config/sync-notes/2026-05-09-resource-governance-and-misc.md

@@ -0,0 +1,69 @@
+# Resource Governance Runtime + CRM Detail Pages + Service-Context Rename
+
+## Why this note exists
+
+The 2026-05-09 release train extends the clients-domain ship with three additional bodies of work that affect template-derived projects:
+
+1. **Resource Governance runtime cutover.** The shared resource-governance validator now defaults to **strict** mode. The OM Resources/Systems descriptor catalog is the source of truth for resource identity. Operations bundles must bind workflows, agents, and integrations to descriptors via `defineResource(s)` + descriptor binding helpers; raw `resourceId` literals in `DeploymentSpec` no longer pass strict validation.
+2. **CRM detail-page surface expansion.** `@elevasis/ui` now publishes `ContactDetailPage` (new) and `CompanyDetailPage` (now exported from `sdk-barrel`) under `@elevasis/ui/features/crm`. The lead-gen flow no longer renders detail modals on row click — both pages are reached via TanStack Router routes (`/crm/contacts/$contactId`, `/crm/companies/$companyId`). The legacy `CompanyDetailModal` and `ContactDetailModal` exports were removed from `@elevasis/ui/features/lead-gen/shared`.
+3. **`ElevasisServiceContext` field rename.** `useElevasisServices().organizationId` is renamed to `useElevasisServices().workOSOrganizationId` to make the WorkOS-vs-Supabase distinction loud at call sites. The old `organizationId` field is preserved as a back-compat alias on both `ElevasisServiceContextValue` and `ElevasisServiceProviderProps` for one release cycle, so existing template consumers continue to work without immediate migration.
+
+Companion items already covered elsewhere:
+
+- Scaffold/agent guidance for descriptor-first authoring → see `2026-05-08-resource-governance-scaffold-guidance.md`.
+- Clients domain (new sidebar pillar, write operations, project/client linkage) → see `2026-05-09-clients-domain.md`.
+
+## Applies to
+
+Any template-derived project (e.g. `nirvana-marketing`, `ZentaraHQ`) that:
+
+- Deploys workflows, agents, or integrations through `operations/src/index.ts` (resource-governance validator).
+- Renders contacts/companies in any feature surface, including custom CRM views (CRM detail pages + modal removal).
+- Uses `useElevasisServices()` from `@elevasis/ui` in custom hooks, components, or test fixtures (service-context rename).
+
+## Required actions
+
+### 1. Resource Governance — descriptor-backed deployment
+
+- Confirm `core/config/organization-model.ts` declares your tenant's resources at `organizationModel.resources.entries` (single-author resource IDs).
+- In `operations/src/index.ts`, bind your workflow/agent/integration definitions to those descriptors via the helpers exported from `@elevasis/sdk` instead of authoring raw `resourceId` strings inline in `DeploymentSpec`.
+- Run `pnpm -C operations check`. The default validator mode is now strict; missing descriptors, raw-ID authoring, runtime/OM type mismatches, and missing Systems will fail the build. Set `ELEVASIS_RESOURCE_VALIDATOR=warn-only` only as a temporary emergency escape hatch — do not let normal CI silently depend on it.
+- New SDK CLI commands are available: `elevasis-sdk agent:list`, `elevasis-sdk agent:get \<id>`, `elevasis-sdk session:list`, `elevasis-sdk session:get \<id>`, `elevasis-sdk session:end \<id>`. Existing `resources` / `describe` / `exec` / `executions` / `execution` are unchanged.
+
+### 2. CRM detail pages
+
+- If your project imports `CompanyDetailModal` or `ContactDetailModal` from `@elevasis/ui/features/lead-gen/shared`, those exports were removed. Replace modal-on-row-click patterns with `useNavigate` to `/crm/contacts/$contactId` or `/crm/companies/$companyId`.
+- If you need detail-page UI in custom routes, import `ContactDetailPage` and `CompanyDetailPage` from `@elevasis/ui/features/crm`. Both are part of the published `sdk-barrel` and accept `contactId` / `companyId` props.
+- The `extend-lead-gen.md` recipe in `node_modules/@elevasis/sdk/reference/scaffold/recipes/` was updated — it no longer documents the modal helpers.
+
+### 3. `workOSOrganizationId` field rename
+
+- New idiomatic destructure: `const { apiRequest, workOSOrganizationId, isReady } = useElevasisServices()`.
+- The old `organizationId` field still resolves correctly through the back-compat alias, so existing template code compiles and runs without changes. New code in this project should use `workOSOrganizationId`.
+- If your project uses `<ElevasisServiceProvider organizationId={...}>`, that prop also accepts both names. Provider's resolver is `workOSOrganizationId ?? organizationId ?? null` — passing both names is supported but unnecessary.
+- For test fixtures that mock `useElevasisServices` via `vi.mock`, return `workOSOrganizationId` rather than `organizationId` when authoring NEW mocks; existing mocks will continue to work via the alias but should be migrated opportunistically. The runtime trap is: `vi.mock(...)` is untyped — TypeScript will not catch a mock that returns the deprecated key, but the resolver bypass means downstream `services.workOSOrganizationId` reads `undefined`.
+
+## Verification
+
+After reconciling local project guidance and writing any descriptor / service-context updates:
+
+```bash
+pnpm -C operations check
+pnpm -C operations check-types
+pnpm -C ui check-types
+pnpm -C ui test
+```
+
+If your project deploys to production and you author runtime resources directly:
+
+```bash
+pnpm -C operations exec elevasis-sdk deploy
+```
+
+Expect strict-mode validator output. Investigate any "OM resource missing for code resource" or "raw resourceId authoring detected" errors as descriptor-binding work, not as test bypass.
+
+## Not handled by /git-sync
+
+- `/git-sync` pulls the new `@elevasis/sdk`, `@elevasis/ui`, and `@elevasis/core` versions and template-owned files, but it does **not** rewrite existing project-owned `operations/src/**` workflow/agent/integration files to use descriptor-backed binding. Maintainers must migrate raw `resourceId` literals to descriptor lookups intentionally.
+- `/git-sync` does **not** rewrite custom UI routes that import `CompanyDetailModal` / `ContactDetailModal` from `@elevasis/ui/features/lead-gen/shared`. Replace those imports with `useNavigate` to detail-page routes manually.
+- `/git-sync` does **not** rename `useElevasisServices().organizationId` reads in project-owned code. The back-compat alias keeps existing code working; proactive renaming is a manual cleanup.

package/reference/examples/organization-model.ts

@@ -4,7 +4,7 @@
 // Pure reference file -- NOT imported anywhere.
 // Copy individual examples into core/config/organization-model.ts or resource definitions as needed.
 
-import { defineOrganizationModel } from '@elevasis/core/organization-model'
+import { defineOrganizationModel, defineResources } from '@elevasis/core/organization-model'
 
 // ---------------------------------------------------------------------------
 // Branding override
@@ -166,12 +166,24 @@ export const customersAndOfferingsExample = defineOrganizationModel({
 })
 
 // ---------------------------------------------------------------------------
-// Resource metadata example
+// Resource descriptor example
 // ---------------------------------------------------------------------------
-export const workflowResourceMetadataExample = {
-  resourceId: 'lead-enrichment-workflow',
+export const workflowResourceDescriptorsExample = defineResources({
+  leadEnrichment: {
+    id: 'lead-enrichment-workflow',
+    kind: 'workflow',
+    systemId: 'sys.prospecting',
+    ownerRoleId: 'role-ops-lead',
+    capabilityKey: 'prospecting.lead-enrichment',
+    status: 'active' as const
+  }
+})
+
+export const workflowResourceRuntimeMetadataExample = {
+  resource: workflowResourceDescriptorsExample.leadEnrichment,
+  resourceId: workflowResourceDescriptorsExample.leadEnrichment.id,
   name: 'Lead Enrichment',
-  type: 'workflow' as const,
+  type: workflowResourceDescriptorsExample.leadEnrichment.kind,
   version: '1.0.0',
   status: 'prod' as const,
   links: [

package/reference/framework/index.mdx

@@ -70,7 +70,7 @@ See [Memory System](memory.mdx) for architecture, error tracking format, scaling
 
 ### Project Structure
 
-The scaffolded project separates concerns clearly: `src/` for resources, `docs/` for platform documentation, `.claude/` for agent infrastructure, and config files at the root. In the current full-stack template that becomes a small workspace with `ui/`, `operations/`, and `foundations/` packages plus a root `docs/index.md`. Understanding which files are gitignored, which are committed, and why matters for collaborating on projects.
+The scaffolded project separates concerns clearly: `operations/` for executable resources, `core/` for shared contracts and Organization Model configuration, `ui/` for the shell, `docs/` for platform documentation, and `.claude/` for agent infrastructure. Understanding which files are gitignored, which are committed, and why matters for collaborating on projects.
 
 See [Project Structure](project-structure.mdx) for a file-by-file walkthrough of the scaffolded project.
 

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.