@elevasis/sdk 1.22.0 → 1.22.1

package/reference/claude-config/rules/operations.md

@@ -32,11 +32,11 @@ The workflow is registered in `operations/src/index.ts` as part of the `example`
 
 1. **Define the descriptor in `core/config/organization-model.ts`** -- Add the OM Resource descriptor under the id-keyed `resources` map so identity, System membership, owner role, and governance status are authored once.
 
-2. **Model the semantic surface** -- Add durable business nouns, verbs, catalogs, links, events, and surfaces to the owning System's `ontology`; add system-local defaults/settings to `System.config`; add explanatory or governing material to `knowledge`; and keep transient DTOs and handler internals out of the OM. Top-level `entities`, top-level `actions`, and `System.content` are compatibility mirrors only when current published consumers still need them.
+2. **Model the semantic surface** -- Add durable business nouns, verbs, catalogs, links, events, and surfaces to the owning System's `ontology`; bind executable Resources through `resource.ontology.actions` and optional `resource.ontology.primaryAction`; add system-local defaults/settings to `System.config`; add explanatory or governing material to `knowledge`; and keep transient DTOs and handler internals out of the OM. Top-level `entities`, top-level `actions`, and `System.content` are compatibility mirrors only when current published consumers still need them.
 
 3. **Define the contract in `core/types/`** -- Add Zod schemas and inferred types to `core/types/index.ts` (or a new file under `core/types/`). Use `core/types/entities.ts` when workflows operate on project-specific entity contracts.
 
-4. **Implement the workflow in `operations/src/`** -- Create a new directory under `operations/src/` for the feature. Import the descriptor, derive runtime `resourceId` / `type` from it, export the workflow from its `index.ts`, and register it in `operations/src/index.ts`.
+4. **Implement the workflow in `operations/src/`** -- Create a new directory under `operations/src/` for the feature. Import the descriptor, derive runtime `resourceId`, `type`, `name`, and `description` from it, export the workflow from its `index.ts`, and register it in `operations/src/index.ts`.
 
 5. **Add the UI in `ui/src/routes/`** -- Create a new route file. Use TanStack Query to call the workflow execution endpoint. Import schemas from `@core/types` for validation and type inference. Read OM resources, ontology, knowledge, and graph data where possible instead of creating page-local semantic registries.
 
@@ -51,7 +51,7 @@ pnpm -C operations deploy       # deploy to dev
 
 ## Resource Registry
 
-`operations/src/index.ts` default-exports a `DeploymentSpec` with `version`, `organizationModel`, `workflows`, `agents`, and optional topology-oriented metadata such as `triggers`, `integrations`, `relationships`, `humanCheckpoints`, and `externalResources`. Each feature group exports `workflows` and `agents` arrays from its own `index.ts`, spread into the top-level spec. `DeploymentSpec` assembles deployable behavior; it should not be treated as a second resource identity catalog.
+`operations/src/index.ts` default-exports a `DeploymentSpec` with `version`, `organizationModel`, `workflows`, `agents`, and optional deployment mechanics such as `triggers`, `integrations`, `relationships`, `humanCheckpoints`, and `externalResources`. Durable operational wiring belongs in `organizationModel.topology.relationships`; deployment mechanics, credentials, provider webhook details, and per-run state stay outside the OM. Each feature group exports `workflows` and `agents` arrays from its own `index.ts`, spread into the top-level spec. `DeploymentSpec` assembles deployable behavior; it should not be treated as a second resource identity catalog.
 
 When you need breadth first, read:
 

package/reference/claude-config/rules/organization-model.md

@@ -36,11 +36,13 @@ Author system-local semantics by boundary:
 - `System.ontology` owns durable object types, action types, catalog types, link types, event types, and surfaces.
 - `System.config` owns system-local JSON settings and defaults.
 - `resources` own executable workflow/agent descriptors, `systemPath`, owners, governance status, code references, and runtime implementation links.
-- `resource.ontology` describes implemented actions, reads, writes, catalog use, and emitted events.
+- `resource.ontology.actions` describes the ontology actions a Resource performs; `resource.ontology.primaryAction` names the default/selectable action when a Resource has one.
+- `resource.ontology` also describes reads, writes, catalog use, and emitted events.
+- `topology.relationships` owns durable operational wiring between Systems, Resources, ontology nodes, policies, roles, triggers, checkpoints, and external resources.
 - `knowledge` owns long-form playbooks, strategies, references, and governance context.
 - `System.content`, top-level `entities`, and top-level `actions` are compatibility mirrors only. Keep them aligned when current published consumers still need them, but do not treat them as the primary authoring surface.
 
-Keep `actionKey` as the current runtime compatibility bridge to workflow metadata.
+Do not author Resource `actionKey` in the target contract. Runtime/UI routing that needs a single selectable action should read `resource.ontology.primaryAction`.
 
 ## Runtime Validation
 
@@ -79,9 +81,9 @@ schema validation. Use `getResourcesForSystem(model, path)` (from `@elevasis/cor
 query resources for a system at runtime. Pass `{ includeDescendants: true }` to include
 all descendant systems (segment-aware -- `'sales'` does NOT match `'salesforce.foo'`).
 
-Some external templates may carry a `systemId` compatibility mirror while published
-`@elevasis/core` releases catch up to the current source contract. Treat that field as
-legacy adapter data only; author new resource relationships against `systemPath`.
+Some external templates may carry a `systemId` compatibility mirror while published
+`@elevasis/core` releases catch up to the current source contract. Treat that field as
+legacy adapter data only; author new resource relationships against `systemPath`.
 
 Do not fetch resources for every system-oriented read by default. For agent workflows, start
 with the user's requested OM/knowledge context and query resources only when the task involves
@@ -103,6 +105,10 @@ entrypoint, handler, schema, test, docs, or config files that implement it. They
 not define resource identity, System membership, runtime execution topology, or graph
 relationships.
 
+`topology.relationships` defines durable operational wiring in the OM. Keep credential
+values, provider webhook mechanics, deployment environment settings, execution logs,
+and per-run scheduler state outside the OM.
+
 `System.ontology` owns durable semantic contracts: object types, action types, catalog
 types, link types, event types, and surfaces. `System.config` owns local settings and
 defaults. If current UI or runtime code still needs legacy mirrors, keep `entities`,

package/reference/claude-config/sync-notes/2026-05-14-organization-model-ontology-refactor.md

@@ -2,7 +2,7 @@
 
 ## Why this note exists
 
-The template now demonstrates the Organization Model ontology bridge. New semantic contracts should be authored in `System.ontology`, while legacy `entities`, `actions`, and `System.content` remain compatibility mirrors for current consumers.
+The template now demonstrates the Organization Model ontology and topology bridge. New semantic contracts should be authored in `System.ontology`; executable Resources bind through `resource.ontology.actions` and optional `resource.ontology.primaryAction`; durable operational wiring belongs in `organizationModel.topology.relationships`. Legacy `entities`, `actions`, and `System.content` remain compatibility mirrors for current consumers.
 
 ## Applies to
 
@@ -14,13 +14,15 @@ The template now demonstrates the Organization Model ontology bridge. New semant
 - `operations/src/resource-registry.test.ts`
 - `operations/src/README.md`
 - `.claude/rules/organization-model.md`
+- `.claude/rules/operations.md`
 
 ## Required actions
 
 1. Preserve system-colocated ontology scopes when syncing template organization-model changes.
-2. Preserve Resource descriptor `ontologyBinding`, `actionKey`, and `codeRefs` together.
-3. Keep `entities`, `actions`, and `System.content` aligned as compatibility mirrors until downstream consumers move fully to compiled ontology indexes.
-4. Do not overwrite project-owned `core/config/extensions/**` files.
+2. Migrate Resource descriptors from `ontology.implements` / `actionKey` to `ontology.actions` / `ontology.primaryAction`; keep `codeRefs` with the Resource descriptor.
+3. Preserve `organizationModel.topology.relationships` when syncing template organization-model changes; keep secrets, credential values, provider webhook mechanics, and per-run state outside the OM.
+4. Keep `entities`, `actions`, and `System.content` aligned as compatibility mirrors until downstream consumers move fully to compiled ontology indexes.
+5. Do not overwrite project-owned `core/config/extensions/**` files.
 
 ## Verification
 
@@ -38,5 +40,6 @@ pnpm sync:verify --pre
 ## Not handled by /git-sync
 
 - Choosing project-specific ontology IDs for tenant-owned systems.
+- Choosing project-specific topology relationships for tenant-owned workflows, checkpoints, integrations, or schedules.
 - Migrating project-owned extension files under `core/config/extensions/**`.
 - Retiring compatibility mirrors before the full internal, SDK, scaffold, and external template-family green cycle.

package/reference/examples/organization-model.ts

@@ -217,13 +217,15 @@ export const customersAndOfferingsExample = defineOrganizationModel({
 export const workflowResourceDescriptorsExample = defineResources({
   leadEnrichment: {
     id: 'lead-enrichment-workflow',
+    title: 'Lead Enrichment',
+    description: 'Enriches lead records and writes qualified opportunities into CRM.',
     kind: 'workflow',
     systemPath: 'sales.lead-gen',
     ownerRoleId: 'role-ops-lead',
-    actionKey: 'prospecting.lead-enrichment',
     status: 'active' as const,
     ontology: {
-      implements: ['sales.lead-gen:action/lead.enrich'],
+      actions: ['sales.lead-gen:action/lead.enrich'],
+      primaryAction: 'sales.lead-gen:action/lead.enrich',
       reads: ['sales.lead-gen:object/lead'],
       writes: ['sales.crm:object/deal'],
       usesCatalogs: ['sales.crm:catalog/pipeline'],
@@ -256,6 +258,28 @@ export const compatibilityGraphLinksExample = {
   ]
 }
 
+export const topologyRelationshipsExample = defineOrganizationModel({
+  topology: {
+    relationships: [
+      {
+        source: { kind: 'trigger', id: 'daily-lead-enrichment' },
+        target: { kind: 'resource', id: workflowResourceDescriptorsExample.leadEnrichment.id },
+        kind: 'triggers'
+      },
+      {
+        source: { kind: 'resource', id: workflowResourceDescriptorsExample.leadEnrichment.id },
+        target: { kind: 'externalResource', id: 'apollo' },
+        kind: 'uses'
+      },
+      {
+        source: { kind: 'resource', id: workflowResourceDescriptorsExample.leadEnrichment.id },
+        target: { kind: 'role', id: 'role-ops-lead' },
+        kind: 'approval'
+      }
+    ]
+  }
+})
+
 // ---------------------------------------------------------------------------
 // Roles and goals
 // ---------------------------------------------------------------------------

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

@@ -138,17 +138,22 @@ Resource identity is authored in the OM Resources domain. Operations imports des
 ```ts
 import { defineResources } from '@elevasis/core/organization-model'
 
-export const resourceDescriptors = defineResources({
-  leadImport: {
-    id: 'lgn-01c-apollo-import-workflow',
-    kind: 'workflow',
-    systemPath: 'sales.lead-gen',
-    ownerRoleId: 'role-ops-lead',
-    status: 'active',
-    actionKey: 'lead-gen.company.apollo-import',
-    codeRefs: [
-      {
-        path: 'packages/elevasis-operations/src/sales/prospecting/scrape/apollo-import.ts',
+export const resourceDescriptors = defineResources({
+  leadImport: {
+    id: 'lgn-01c-apollo-import-workflow',
+    title: 'Apollo Import',
+    description: 'Imports Apollo company records into the lead generation pipeline.',
+    kind: 'workflow',
+    systemPath: 'sales.lead-gen',
+    ownerRoleId: 'role-ops-lead',
+    status: 'active',
+    ontology: {
+      actions: ['sales.lead-gen:action/company.apollo-import'],
+      primaryAction: 'sales.lead-gen:action/company.apollo-import'
+    },
+    codeRefs: [
+      {
+        path: 'packages/elevasis-operations/src/sales/prospecting/scrape/apollo-import.ts',
         role: 'entrypoint',
         symbol: 'lgnApolloImportWorkflow'
       }

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

@@ -176,15 +176,16 @@ Resources are governed descriptors for executable workflows, agents, integration
 import { defineResources } from '@elevasis/core/organization-model'
 
 export const resourceDescriptors = defineResources({
-  approveReviewItem: {
-    id: 'approve-review-item-workflow',
-    order: 10,
-    kind: 'workflow',
-    systemPath: 'operations.review',
-    ownerRoleId: 'role-ops-lead',
-    status: 'active',
-    actionKey: 'operations.review.approve',
-    codeRefs: [
+  approveReviewItem: {
+    id: 'approve-review-item-workflow',
+    title: 'Approve review item',
+    description: 'Routes a review item through the operations approval workflow.',
+    order: 10,
+    kind: 'workflow',
+    systemPath: 'operations.review',
+    ownerRoleId: 'role-ops-lead',
+    status: 'active',
+    codeRefs: [
       {
         path: 'operations/src/review/approve-review-item/index.ts',
         role: 'entrypoint',
@@ -194,9 +195,10 @@ export const resourceDescriptors = defineResources({
         path: 'operations/src/review/approve-review-item/approve-review-item.test.ts',
         role: 'test'
       }
-    ],
+    ],
     ontology: {
-      implements: ['operations.review:action/review-item.approve'],
+      actions: ['operations.review:action/review-item.approve'],
+      primaryAction: 'operations.review:action/review-item.approve',
       reads: ['operations.review:object/review-item'],
       writes: ['operations.review:object/review-item'],
       emits: ['operations.review:event/review-item.approved']
@@ -205,15 +207,15 @@ export const resourceDescriptors = defineResources({
 })
 ```
 
-Use `actionKey` only when a Resource implements a stable action contract. Keep it URL-safe because some runtimes expose action keys in route params. Resource-only workflows, diagnostics, and helper scripts can stay unbound.
+Use descriptor `title` and `description` for executable display metadata.
 
-Use nested `resource.ontology` bindings for the semantic actions, objects, catalogs, and events a Resource implements, reads, writes, uses, or emits. Top-level resource `emits` remains readable for bridge-era descriptors, but new descriptors should keep event bindings in `resource.ontology.emits`.
+Use nested `resource.ontology` bindings for the semantic actions, objects, catalogs, and events a Resource performs, reads, writes, uses, or emits. `resource.ontology.primaryAction` is the default/selectable ontology action and must be included in `resource.ontology.actions`. Top-level resource `emits` remains readable for bridge-era descriptors, but new descriptors should keep event bindings in `resource.ontology.emits`.
 
 Use `codeRefs` as repo-relative breadcrumbs for agents and operators. They point from the governed Resource descriptor to implementation files; they do not define resource identity, System membership, runtime topology, or graph links.
 
 ## 6. Bind Runtime to the Descriptor
 
-Workflow and agent code owns schemas, handlers, steps, and runtime behavior. It should import the descriptor and derive `resourceId`, `type`, and `actionKey`.
+Workflow and agent code owns schemas, handlers, steps, and runtime behavior. It should import the descriptor and derive `resourceId`, `type`, and display metadata from it.
 
 ```ts
 import type { WorkflowDefinition } from '@elevasis/sdk'
@@ -221,15 +223,15 @@ import { resourceDescriptors } from '@core/config/organization-model'
 
 export const approveReviewItemWorkflow: WorkflowDefinition = {
   config: {
-    resource: resourceDescriptors.approveReviewItem,
-    resourceId: resourceDescriptors.approveReviewItem.id,
-    name: 'Approve review item',
-    type: resourceDescriptors.approveReviewItem.kind,
-    version: '1.0.0',
-    status: 'dev',
-    category: 'production',
-    actionKey: resourceDescriptors.approveReviewItem.actionKey
-  },
+    resource: resourceDescriptors.approveReviewItem,
+    resourceId: resourceDescriptors.approveReviewItem.id,
+    name: resourceDescriptors.approveReviewItem.title,
+    description: resourceDescriptors.approveReviewItem.description,
+    type: resourceDescriptors.approveReviewItem.kind,
+    version: '1.0.0',
+    status: 'dev',
+    category: 'production'
+  },
   contract: {
     inputSchema,
     outputSchema
@@ -255,7 +257,7 @@ export const org = {
 }
 ```
 
-Use `relationships` for execution topology. Use `systemPath`, `resource.ontology`, and `actionKey` for semantic topology. Existing compatibility graph links can stay readable while old consumers migrate.
+Use `organizationModel.topology.relationships` for durable execution topology. The initial topology relationship kinds are `triggers`, `uses`, and `approval`; use `systemPath` and `resource.ontology` for semantic binding. Existing compatibility graph links can stay readable while old consumers migrate.
 
 ## 7. Add UI Wiring
 
@@ -304,7 +306,7 @@ function ReviewLayout() {
 Add tests for the boundaries you changed:
 
 - OM config tests for systems, ontology object/action/catalog records, resources, and any compatibility `System.content`.
-- Runtime registry tests that deployed workflows import descriptors and keep `resourceId`, `type`, and `actionKey` aligned.
+- Runtime registry tests that deployed workflows import descriptors and keep `resourceId`, `type`, title, description, and `resource.ontology.primaryAction` aligned.
 - UI tests or type checks for route, manifest, and guard wiring.
 - Graph or knowledge tests when new ontology records, resources, compatibility content nodes, or emitted events should appear in Command View.
 - Scaffold sync when new docs or generated scaffold references are affected.
@@ -327,7 +329,7 @@ pnpm verify:scaffold-reference
 - Ontology catalog types contain local vocabularies such as pipelines, stages, templates, and status flows.
 - Compatibility `System.content` is used only for existing bridge-era local catalogs or schemas.
 - Each executable workflow or agent has an OM Resource descriptor with `systemPath`.
-- `actionKey` is present only when the Resource implements a stable action contract.
+- Executable Resources use descriptor `title` / `description`, `resource.ontology.actions`, and `resource.ontology.primaryAction`.
 - `codeRefs` point to useful entrypoints, handlers, schemas, tests, docs, or config.
 - Runtime assembly imports descriptors and derives identity from them.
 - UI routes, manifests, and guards use the same System ID.

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

@@ -20,16 +20,18 @@ Add the descriptor in `core/config/organization-model.ts`:
 import { defineResources } from '@elevasis/core/organization-model'
 
 export const resourceDescriptors = defineResources({
-  myWorkflow: {
+  myWorkflow: {
     id: 'my-workflow',
+    title: 'My Workflow',
+    description: 'Runs the governed work item workflow.',
     order: 10,
     kind: 'workflow',
     systemPath: 'operations',
     ownerRoleId: 'role-ops-lead',
     status: 'active',
-    actionKey: 'operations.my-workflow',
     ontology: {
-      implements: ['operations:action/my-workflow.run'],
+      actions: ['operations:action/my-workflow.run'],
+      primaryAction: 'operations:action/my-workflow.run',
       reads: ['operations:object/work-item'],
       writes: ['operations:object/work-item'],
       usesCatalogs: ['operations:catalog/workflow-status'],
@@ -63,7 +65,7 @@ Use `organizationModel.resources` as the Resources descriptor catalog. Graph ref
 
 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 `actionKey` only when the resource implements a stable runtime action key. Use nested `resource.ontology` bindings to declare which ontology actions, objects, catalogs, and events the resource implements, reads, writes, uses, or emits. Optional top-level resource `emits` remains readable for bridge-era event descriptors, but new descriptors should keep event bindings in `resource.ontology.emits`.
+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
 
@@ -124,18 +126,26 @@ Use `.js` extensions in TypeScript source imports for ESM compatibility.
 
 ## 4. Declare runtime relationships
 
-Use `DeploymentSpec.relationships` for execution topology:
-
-```ts
-relationships: {
-  'my-workflow': {
-    triggers: { workflows: ['email-notification'] },
-    uses: { integrations: ['hubspot'] }
-  }
-}
-```
-
-Use `relationships` for runtime execution relationships. 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.
+Use `organizationModel.topology.relationships` for durable execution topology:
+
+```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'
+    }
+  ]
+}
+```
+
+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
 

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

@@ -206,14 +206,16 @@ import { defineResources } from '@elevasis/core/organization-model'
 export const resourceDescriptors = defineResources({
   leadImport: {
     id: 'lead-import',
+    title: 'Lead Import',
+    description: 'Updates CRM deal stage data from imported lead records.',
     order: 10,
     kind: 'workflow',
     systemPath: 'sales.crm',
     ownerRoleId: 'role-ops-lead',
     status: 'active',
-    actionKey: 'sales.crm.deal.update-stage',
     ontology: {
-      implements: ['sales.crm:action/deal.update-stage'],
+      actions: ['sales.crm:action/deal.update-stage'],
+      primaryAction: 'sales.crm:action/deal.update-stage',
       reads: ['sales.crm:object/deal'],
       writes: ['sales.crm:object/deal'],
       usesCatalogs: ['sales.crm:catalog/pipeline'],
@@ -243,7 +245,7 @@ Use kind-prefixed graph IDs for cross-collection links:
 
 `category` is one of `production`, `diagnostic`, `internal`, or `testing`.
 
-`actionKey` mirrors a stable runtime action key when the resource has one. Use nested `resource.ontology` bindings to declare which ontology actions, objects, catalogs, and events the resource implements, reads, writes, uses, or emits. Resource event emissions can still be declared through top-level `emits` for older descriptors, but new descriptors should use `resource.ontology.emits`.
+Descriptor `title` and `description` own 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` names the default/selectable action and must be included in `resource.ontology.actions`. Resource event emissions can still be declared through top-level `emits` for older descriptors, but new descriptors should use `resource.ontology.emits`.
 
 ## Compatibility Domain Mirrors
 

package/reference/scaffold/recipes/extend-lead-gen.md

@@ -210,15 +210,15 @@ const companyCleanupLayout: StepConfigLayout<CompanyCleanupInput> = {
 }
 
 const listActions: ListBuilderRegistry = [
-  {
-    resourceId: companyCleanupResource.id,
-    workflowId: companyCleanupResource.id,
-    actionKey: 'lead-gen.company.cleanup',
-    label: 'Company Cleanup',
-    description: 'Normalize and clean company records for the list.',
-    category: 'utility',
-    stagesAffected: ['populated'],
-    schema: companyCleanupInputSchema,
+  {
+    resourceId: companyCleanupResource.id,
+    workflowId: companyCleanupResource.id,
+    actionKey: companyCleanupResource.ontology.primaryAction ?? companyCleanupResource.ontology.actions[0],
+    label: companyCleanupResource.title,
+    description: companyCleanupResource.description,
+    category: 'utility',
+    stagesAffected: ['populated'],
+    schema: companyCleanupInputSchema,
     layout: companyCleanupLayout,
     defaultInput: (list) => ({
       listId: list.id,

package/reference/scaffold/recipes/index.md

@@ -17,7 +17,7 @@ Before starting, read [glossary.md](../reference/glossary.md) to disambiguate ov
 ## Recipes
 
 **[Add an OM-Backed System](add-a-feature.md)**
-You want a new system with cohesive Organization Model semantics, executable resources, and optional UI. Covers Systems, System-owned ontology and config, Resource descriptors with `resource.ontology`, `actionKey`, `codeRefs`, runtime assembly, manifests, routes, guards, tests, and compatibility notes for old `System.content` consumers.
+You want a new system with cohesive Organization Model semantics, executable resources, and optional UI. Covers Systems, System-owned ontology and config, Resource descriptors with `title`, `description`, `resource.ontology.actions`, `primaryAction`, `codeRefs`, OM topology, runtime assembly, manifests, routes, guards, tests, and compatibility notes for old `System.content` consumers.
 
 **[Add a Resource](add-a-resource.md)**
 You want a new workflow or agent deployed to the platform. Covers OM Resource descriptor authoring, descriptor-backed `WorkflowDefinition` binding, `DeploymentSpec` assembly, relationship declarations, and CLI verification.

package/reference/scaffold/reference/contracts.md

@@ -421,6 +421,42 @@ export type OrganizationModelIntegrationResourceEntry = z.infer<typeof Integrati
 export type OrganizationModelScriptResourceEntry = z.infer<typeof ScriptResourceEntrySchema>
 ```
 
+### `OrganizationModelTopology`
+
+```typescript
+export type OrganizationModelTopology = z.infer<typeof OmTopologyDomainSchema>
+```
+
+### `OrganizationModelTopologyNodeKind`
+
+```typescript
+export type OrganizationModelTopologyNodeKind = z.infer<typeof OmTopologyNodeKindSchema>
+```
+
+### `OrganizationModelTopologyNodeRef`
+
+```typescript
+export type OrganizationModelTopologyNodeRef = z.infer<typeof OmTopologyNodeRefSchema>
+```
+
+### `OrganizationModelTopologyRelationshipKind`
+
+```typescript
+export type OrganizationModelTopologyRelationshipKind = z.infer<typeof OmTopologyRelationshipKindSchema>
+```
+
+### `OrganizationModelTopologyRelationship`
+
+```typescript
+export type OrganizationModelTopologyRelationship = z.infer<typeof OmTopologyRelationshipSchema>
+```
+
+### `OrganizationModelTopologyMetadata`
+
+```typescript
+export type OrganizationModelTopologyMetadata = z.infer<typeof OmTopologyMetadataSchema>
+```
+
 ### `OrganizationModelActions`
 
 ```typescript
@@ -1290,13 +1326,15 @@ export interface HumanCheckpointDefinition extends ResourceDefinition {
  * Used by ResourceRegistry for discovery and Command View for visualization.
  */
 export interface DeploymentSpec {
-  /** Deployment version (semver) */
-  version: string
-  /** Optional Organization Model governance catalog used for OM-code validation */
-  organizationModel?: {
-    systems?: OrganizationModelSystems
-    resources?: OrganizationModelResources
-  }
+  /** Deployment version (semver) */
+  version: string
+  /** Optional Organization Model governance catalog used for OM-code validation */
+  organizationModel?: Partial<
+    Pick<
+      OrganizationModel,
+      'systems' | 'resources' | 'ontology' | 'topology' | 'roles' | 'policies' | 'entities' | 'actions'
+    >
+  >
   /** Workflow definitions */
   workflows?: WorkflowDefinition[]
   /** Agent definitions */

package/reference/scaffold/reference/glossary.md

@@ -32,7 +32,7 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **MembershipFeatureConfig** -- legacy per-member feature override config. Current System visibility should be authored through Organization Model System lifecycle/access metadata and resolved through provider compatibility layers for older consumers.
 
-**OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `version`, `domainMetadata`, `branding`, `navigation`, `ontology`, `systems`, `resources`, `identity`, `customers`, `offerings`, `roles`, `goals`, `policies`, `statuses`, and `knowledge`. Legacy domain keys such as `sales`, `prospecting`, `projects`, `actions`, and `entities` remain compatibility inputs while projects migrate to System-owned ontology/config/resource contracts.
+**OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `version`, `domainMetadata`, `branding`, `navigation`, `ontology`, `systems`, `resources`, `topology`, `identity`, `customers`, `offerings`, `roles`, `goals`, `policies`, `statuses`, and `knowledge`. Legacy domain keys such as `sales`, `prospecting`, `projects`, `actions`, and `entities` remain compatibility inputs while projects migrate to System-owned ontology/config/resource contracts.
 
 **OrganizationModelSystemEntry** -- System node in `OrganizationModel.systems`. Primary authoring fields include `id`, `label`, `description`, `parentSystemId`, `systems`, `lifecycle`, `ui`, `requiresAdmin`, `devOnly`, `responsibleRoleId`, `governedByKnowledge`, `drivesGoals`, `actions`, `policies`, `ontology`, `config`, and `order`. `subsystems` and `content` are retained compatibility inputs for older projects and should not be used for new recursive Systems, schemas, catalogs, or config.
 
@@ -40,7 +40,7 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **Resource** -- governance-only descriptor in `OrganizationModel.resources` for a workflow, agent, integration, or script. Runtime code derives `resourceId` and kind from the descriptor, then attaches executable behavior in operations.
 
-**Resource descriptor** -- OM entry with canonical `id`, required `systemPath`, governance `status`, optional role ownership, optional `actionKey`, `codeRefs`, and nested `ontology` bindings for implemented actions, read/write objects, used catalogs, and emitted events. Top-level `emits` remains a compatibility mirror for older descriptors.
+**Resource descriptor** -- OM entry with canonical `id`, required `systemPath`, descriptor `title` / `description`, governance `status`, optional role ownership, `codeRefs`, and nested `ontology` bindings for `actions`, optional `primaryAction`, read/write objects, used catalogs, and emitted events. Top-level `emits` remains a compatibility mirror for older descriptors.
 
 **System** -- tenant-defined bounded context in `OrganizationModel.systems` that groups operational resources and carries governance metadata such as responsible role, governing knowledge, driven goals, kind, lifecycle, System-local ontology, and System-local config.
 
@@ -54,7 +54,7 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **Subshell / Sidebar** -- System- or route-prefix-scoped UI region rendered when the current route matches a module whose manifest supplies a sidebar.
 
-**Topology** -- runtime resource relationships declared in `DeploymentSpec.relationships`.
+**Topology** -- durable OM operational wiring declared in `OrganizationModel.topology.relationships`. Initial relationship kinds are `triggers`, `uses`, and `approval`; relationships use typed refs such as `{ kind: 'resource', id: 'lead-import' }`.
 
 ## Package Boundary