@elevasis/sdk 1.44.3 → 1.46.0

package/reference/examples/organization-model.ts

@@ -4,7 +4,13 @@
 // Pure reference file -- NOT imported anywhere.
 // Copy individual examples into core/config/organization-model.ts or resource definitions as needed.
 
-import { defineOrganizationModel, defineResources } from '@elevasis/core/organization-model'
+import {
+  defineOrganizationModel,
+  defineResources,
+  defineTopology,
+  topologyRef,
+  topologyRelationship
+} from '@elevasis/core/organization-model'
 
 // ---------------------------------------------------------------------------
 // Identity and branding override
@@ -206,36 +212,36 @@ export const identityExample = defineOrganizationModel({
 // Customers and offerings
 // ---------------------------------------------------------------------------
 export const customersAndOfferingsExample = defineOrganizationModel({
+  // Both domains are id-keyed records, not arrays. The map key must equal the entry's `id`,
+  // and `order` is required on every entry.
   customers: {
-    segments: [
-      {
-        id: 'segment-smb-agencies',
-        name: 'SMB Marketing Agencies',
-        description: 'Growth-oriented digital agencies with 5-50 staff.',
-        jobsToBeDone: 'Run more client campaigns without growing headcount.',
-        pains: ['Manual data entry', 'Slow lead qualification'],
-        gains: ['Automated pipelines', 'Structured human review'],
-        firmographics: {
-          industry: 'Marketing / Digital Agency',
-          companySize: '5-50',
-          region: 'North America'
-        },
-        valueProp: 'Automate agency operations so the team focuses on strategy and clients.'
-      }
-    ]
+    'segment-smb-agencies': {
+      id: 'segment-smb-agencies',
+      order: 10,
+      name: 'SMB Marketing Agencies',
+      description: 'Growth-oriented digital agencies with 5-50 staff.',
+      jobsToBeDone: 'Run more client campaigns without growing headcount.',
+      pains: ['Manual data entry', 'Slow lead qualification'],
+      gains: ['Automated pipelines', 'Structured human review'],
+      firmographics: {
+        industry: 'Marketing / Digital Agency',
+        companySize: '5-50',
+        region: 'North America'
+      },
+      valueProp: 'Automate agency operations so the team focuses on strategy and clients.'
+    }
   },
   offerings: {
-    products: [
-      {
-        id: 'product-starter',
-        name: 'Starter Automation Pack',
-        description: 'Workflow bundle for lead enrichment, CRM follow-up, and project delivery automation.',
-        pricingModel: 'subscription',
-        price: 299,
-        currency: 'USD',
-        targetSegmentIds: ['segment-smb-agencies']
-      }
-    ]
+    'product-starter': {
+      id: 'product-starter',
+      order: 10,
+      name: 'Starter Automation Pack',
+      description: 'Workflow bundle for lead enrichment, CRM follow-up, and project delivery automation.',
+      pricingModel: 'subscription',
+      price: 299,
+      currency: 'USD',
+      targetSegmentIds: ['segment-smb-agencies']
+    }
   }
 })
 
@@ -245,6 +251,7 @@ export const customersAndOfferingsExample = defineOrganizationModel({
 export const workflowResourceDescriptorsExample = defineResources({
   leadEnrichment: {
     id: 'lead-enrichment-workflow',
+    order: 10,
     title: 'Lead Enrichment',
     description: 'Enriches lead records and writes qualified opportunities into CRM.',
     kind: 'workflow',
@@ -286,67 +293,66 @@ export const compatibilityGraphLinksExample = {
   ]
 }
 
+// `topology.relationships` is an id-keyed record, and each relationship uses `from`/`to`.
+// Author it through `defineTopology` so the refs are compiled and validated for you.
 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'
-      }
-    ]
-  }
+  topology: defineTopology({
+    dailyEnrichmentTrigger: topologyRelationship.triggers(
+      topologyRef.trigger('daily-lead-enrichment'),
+      topologyRef.resource(workflowResourceDescriptorsExample.leadEnrichment.id)
+    ),
+    enrichmentUsesApollo: topologyRelationship.uses(
+      topologyRef.resource(workflowResourceDescriptorsExample.leadEnrichment.id),
+      topologyRef.externalResource('apollo')
+    ),
+    enrichmentApprovedByOpsLead: topologyRelationship.approval(
+      topologyRef.resource(workflowResourceDescriptorsExample.leadEnrichment.id),
+      topologyRef.role('role-ops-lead')
+    )
+  })
 })
 
 // ---------------------------------------------------------------------------
 // Roles and goals
 // ---------------------------------------------------------------------------
 export const rolesAndGoalsExample = defineOrganizationModel({
+  // Both domains are id-keyed records with a required `order`.
+  // `heldBy` is a discriminated union on `kind`, not a display name.
   roles: {
-    roles: [
-      {
-        id: 'role-ceo',
-        title: 'CEO',
-        responsibilities: ['Set company direction', 'Approve strategic initiatives'],
-        heldBy: 'Alex Johnson'
-      },
-      {
-        id: 'role-head-of-ops',
-        title: 'Head of Operations',
-        responsibilities: ['Manage workflow deployments', 'Review human-in-the-loop queue'],
-        reportsToId: 'role-ceo',
-        heldBy: 'Jordan Lee'
-      }
-    ]
+    'role-ceo': {
+      id: 'role-ceo',
+      order: 10,
+      title: 'CEO',
+      responsibilities: ['Set company direction', 'Approve strategic initiatives'],
+      heldBy: { kind: 'human', userId: 'user-alex-johnson' }
+    },
+    'role-head-of-ops': {
+      id: 'role-head-of-ops',
+      order: 20,
+      title: 'Head of Operations',
+      responsibilities: ['Manage workflow deployments', 'Review human-in-the-loop queue'],
+      reportsToId: 'role-ceo',
+      heldBy: { kind: 'human', userId: 'user-jordan-lee' }
+    }
   },
   goals: {
-    objectives: [
-      {
-        id: 'goal-grow-arr-q2-2026',
-        description: 'Grow monthly recurring revenue by end of Q2 2026.',
-        periodStart: '2026-04-01',
-        periodEnd: '2026-06-30',
-        keyResults: [
-          {
-            id: 'kr-mrr-10k',
-            description: 'Reach $10K MRR',
-            targetMetric: 'Monthly recurring revenue',
-            currentValue: 2800,
-            targetValue: 10000
-          }
-        ]
-      }
-    ]
+    'goal-grow-arr-q2-2026': {
+      id: 'goal-grow-arr-q2-2026',
+      order: 10,
+      description: 'Grow monthly recurring revenue by end of Q2 2026.',
+      periodStart: '2026-04-01',
+      periodEnd: '2026-06-30',
+      // `keyResults` genuinely is an array — it is nested inside the entry, not a domain map.
+      keyResults: [
+        {
+          id: 'kr-mrr-10k',
+          description: 'Reach $10K MRR',
+          targetMetric: 'Monthly recurring revenue',
+          currentValue: 2800,
+          targetValue: 10000
+        }
+      ]
+    }
   }
 })
 
@@ -354,38 +360,38 @@ export const rolesAndGoalsExample = defineOrganizationModel({
 // Knowledge nodes
 // ---------------------------------------------------------------------------
 export const knowledgeExample = defineOrganizationModel({
+  // `knowledge` is a flat id-keyed record. The old `{ version, lastModified, nodes[] }`
+  // wrapper was removed in the Phase 4 cut.
   knowledge: {
-    nodes: [
-      {
-        id: 'knowledge.example-outreach-playbook',
-        kind: 'playbook',
-        title: 'Example Outreach Playbook',
-        summary: 'Step-by-step runbook for launching a cold outreach campaign.',
-        body: '## Overview\n\nThis playbook walks through prospect sourcing, message templates, scheduling, and reply triage.\n\n## Steps\n\n1. Source prospects from the lead-gen list.\n2. Personalize the cold email template.\n3. Schedule the sending campaign.\n4. Triage replies in the CRM.',
-        links: [{ nodeId: 'system:sales.crm' }, { nodeId: 'system:sales.lead-gen' }],
-        ownerIds: [],
-        updatedAt: '2026-05-01'
-      },
-      {
-        id: 'knowledge.example-icp-strategy',
-        kind: 'strategy',
-        title: 'Example ICP Strategy',
-        summary: 'Describes the ideal customer profile and qualification thresholds.',
-        body: '## ICP Profile\n\n- **Industry:** SMB marketing agencies\n- **Size:** 5-50 employees\n- **Region:** North America\n\nProspects scoring \\<60 are excluded from outreach.',
-        links: [{ nodeId: 'system:sales' }],
-        ownerIds: [],
-        updatedAt: '2026-05-01'
-      },
-      {
-        id: 'knowledge.example-org-model-reference',
-        kind: 'reference',
-        title: 'Example Organization Model Reference',
-        summary: 'Glossary of OM domains and how they relate to systems and resources.',
-        body: '## Domains\n\nThe organization model separates semantic contracts in ontology, system-local settings in config, executable governance in resources, and explanatory material in knowledge. Secrets and runtime state stay outside the Organization Model.',
-        links: [],
-        ownerIds: [],
-        updatedAt: '2026-05-01'
-      }
-    ]
+    'knowledge.example-outreach-playbook': {
+      id: 'knowledge.example-outreach-playbook',
+      kind: 'playbook',
+      title: 'Example Outreach Playbook',
+      summary: 'Step-by-step runbook for launching a cold outreach campaign.',
+      body: '## Overview\n\nThis playbook walks through prospect sourcing, message templates, scheduling, and reply triage.\n\n## Steps\n\n1. Source prospects from the lead-gen list.\n2. Personalize the cold email template.\n3. Schedule the sending campaign.\n4. Triage replies in the CRM.',
+      links: [{ nodeId: 'system:sales.crm' }, { nodeId: 'system:sales.lead-gen' }],
+      ownerIds: [],
+      updatedAt: '2026-05-01'
+    },
+    'knowledge.example-icp-strategy': {
+      id: 'knowledge.example-icp-strategy',
+      kind: 'strategy',
+      title: 'Example ICP Strategy',
+      summary: 'Describes the ideal customer profile and qualification thresholds.',
+      body: '## ICP Profile\n\n- **Industry:** SMB marketing agencies\n- **Size:** 5-50 employees\n- **Region:** North America\n\nProspects scoring \\<60 are excluded from outreach.',
+      links: [{ nodeId: 'system:sales' }],
+      ownerIds: [],
+      updatedAt: '2026-05-01'
+    },
+    'knowledge.example-org-model-reference': {
+      id: 'knowledge.example-org-model-reference',
+      kind: 'reference',
+      title: 'Example Organization Model Reference',
+      summary: 'Glossary of OM domains and how they relate to systems and resources.',
+      body: '## Domains\n\nThe organization model separates semantic contracts in ontology, system-local settings in config, executable governance in resources, and explanatory material in knowledge. Secrets and runtime state stay outside the Organization Model.',
+      links: [],
+      ownerIds: [],
+      updatedAt: '2026-05-01'
+    }
   }
 })

package/reference/index.mdx

@@ -31,7 +31,7 @@ You do not need all three packages. A pure automation project needs only `@eleva
 
 ## Packages
 
-### @elevasis/sdk (v1.30.2)
+### @elevasis/sdk (v1.45.0)
 
 The primary developer package. Provides the TypeScript API for defining workflows and agents, the `elevasis-sdk` CLI for validation and deployment, and typed worker adapters for 25 platform and integration tools.
 
@@ -41,7 +41,7 @@ The primary developer package. Provides the TypeScript API for defining workflow
 
 See [@elevasis/sdk](sdk/index.mdx) for the full group overview, getting started guide, CLI reference, adapter catalog, and more.
 
-### @elevasis/core (v0.39.0)
+### @elevasis/core (v0.60.0)
 
 The shared contract layer. Exports Zod schemas and TypeScript types that are shared between the SDK, the UI, and the platform API. Useful when you need the typed contracts (organization model, entities, knowledge, auth) in a package that does not pull in the full SDK runtime.
 
@@ -51,9 +51,9 @@ The shared contract layer. Exports Zod schemas and TypeScript types that are sha
 
 See [@elevasis/core](core/index.mdx) for subpath details, browser/server split, and when to use it.
 
-### @elevasis/ui (v2.42.0)
+### @elevasis/ui (v2.68.0)
 
-The shared React feature-shell. Provides an `ElevasisProvider` and manifest-backed feature modules that a host UI embeds. Many peer dependencies are optional -- pull only what the features you use require.
+The shared React feature-shell. Provides `ElevasisCoreProvider` / `ElevasisSystemsProvider` and manifest-backed feature modules that a host UI embeds. Many peer dependencies are optional -- pull only what the features you use require.
 
 **Install:** `pnpm add @elevasis/ui`
 

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

@@ -47,6 +47,9 @@ export type Deal = BaseDeal
 
 ## Recipe
 
-The full pattern is documented in the SDK scaffold bundle: `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-a-base-entity.md`.
+The full pattern is documented in the SDK scaffold bundle. Internally, read the workspace source at
+`packages/sdk/docs/scaffold/recipes/extend-a-base-entity.md`; a tenant reads the published mirror at
+`operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-a-base-entity.md`, which does
+not resolve from the monorepo root.
 
 The canonical template demo lives at `external/_template/core/types/entities.ts`.

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

@@ -0,0 +1,19 @@
+# @elevasis/core/content
+
+Content pipeline API schemas and platform-content typed interfaces. Browser-safe (no Node APIs).
+
+## Surface
+
+| Export                                                                                                                                         | Purpose                                                                                                                                                                 |
+| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ContentItemResponseSchema`, `CreateContentItemRequestSchema`, `UpdateContentItemRequestSchema`                                                | `content_items` transport shape. `processingState` is intentionally absent from create/update — factory-write-only.                                                     |
+| `ContentProcessingStateSchema`                                                                                                                 | `{ stepKey: { status, data? } }`, keyed by `ContentStepKeySchema` — a content-specific key, not lead-gen's `LeadGenStageKeySchema`.                                     |
+| `ContentPayloadEnvelopeSchema`                                                                                                                 | The producer's immutable emission stored in `payload`. Never edited — `body` is the human's canonical text.                                                             |
+| `ReviewContentItemRequestSchema`                                                                                                               | Approve, or reject with a required `rejectReason`. Writes `reviewed_at` / `reviewed_by`.                                                                                |
+| `ContentItemAttemptResponseSchema`, `CreateContentItemAttemptRequestSchema`                                                                    | `content_item_attempts` transport shape. No `attemptNumber` field on create — the API service assigns it inside the write. `stepKey` is producer-supplied and nullable. |
+| `ContentDistributionResponseSchema`, `CreateContentDistributionRequestSchema`, `UpdateContentDistributionRequestSchema`                        | `content_distributions` transport shape, including the manual-publish fields (`publishMethod`, `platformPostId`, `platformUrl`).                                        |
+| `PlatformContent`, `YouTubeContent`, `LinkedInContent`, `InstagramContent`, `XContent`, `AnyPlatformContent`, `PlatformContentMap`, `Platform` | Typed interfaces for platform-specific content stored in `content_distributions.platform_content`.                                                                      |
+
+## Step catalog reconciliation
+
+`ContentStepKeySchema` is free text today — the content System's step catalog (`content:catalog/<pipeline>-steps`) is authored separately in `packages/elevasis/core/config/organization-model`. Closed-catalog membership is enforced by the caller/API layer via model-injected validators once that catalog lands, mirroring how `LeadGenStageKeySchema` and `CrmStageKeySchema` are validated today.

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

@@ -1,149 +1,148 @@
-# Organization Model
-
-The organization model is the published semantic contract that maps a tenant's System hierarchy, shell navigation, business semantics, resource governance, and graph bindings.
-
-Use this module when resolving or validating an organization's contract before wiring UI shells, routing, system gates, or domain-specific capability checks.
-
-## Published Exports
-
-The public entry point exposes:
-
-- `OrganizationModelSchema`
-- `DEFAULT_ORGANIZATION_MODEL`
-- `defineOrganizationModel`
-- `resolveOrganizationModel`
-- `createFoundationOrganizationModel`
-- node ID and System helper types
-- `OrganizationModel` and supporting domain types
-
-Import it from the published subpath:
-
-```ts
-import {
-  DEFAULT_ORGANIZATION_MODEL,
-  createFoundationOrganizationModel,
-  defineOrganizationModel,
-  resolveOrganizationModel,
-  type OrganizationModel
-} from '@elevasis/core/organization-model'
-```
-
-## Contract Shape
-
-The model is versioned and currently validates against `version: 1`.
-
-Top-level fields:
-
-- `version`
-- `domainMetadata`
-- `branding`
-- `navigation`
-- `sales`
-- `prospecting`
-- `projects`
-- `identity`
-- `customers`
-- `offerings`
-- `roles`
-- `goals`
-- `systems`
-- `resources`
-- `capabilities`
-- `policies`
-- `statuses`
-- `knowledge`
-
-The pure collection domains are id-keyed maps: `systems`, `roles`, `goals`, `customers`, `offerings`, `resources`, `capabilities`, `policies`, and `statuses`. The map key must match the entry `id`. Entries carry `order` for deterministic ordered views; use `listDomain(record)` when order matters.
-
-Resource identity is authored in `resources`. Runtime workflows, agents, integrations, and scripts import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
-
-## System Set
-
-System hierarchy is authored as an id-keyed `systems` map. Dotted IDs and `parentSystemId` define parent/child relationships:
-
-```ts
-systems: {
-  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
-  sales: { id: 'sales', order: 20, label: 'Sales', lifecycle: 'active' },
-  clients: { id: 'clients', order: 30, label: 'Clients', lifecycle: 'active' },
-  projects: { id: 'projects', order: 40, label: 'Projects', lifecycle: 'active' }
-}
-```
-
-Systems describe semantic ownership, hierarchy, lifecycle, access, and governance. Sidebar presentation is authored separately under `navigation.sidebar`; UI-backed Systems may still provide `ui.path` for route matching during the migration, but they do not author composed surface lists. Lifecycle values such as `active`, `beta`, `deprecated`, and `archived` replace the old feature enabled/dev-only split.
-
-## Sidebar Navigation
-
-Shell navigation is authored as a recursive sidebar tree:
-
-```ts
-navigation: {
-  sidebar: {
-    primary: {
-      dashboard: {
-        type: 'surface',
-        order: 10,
-        label: 'Dashboard',
-        path: '/',
-        surfaceType: 'dashboard',
-        targets: { systems: ['dashboard'] }
-      },
-      business: {
-        type: 'group',
-        order: 20,
-        label: 'Business',
-        children: {
-          clients: {
-            type: 'surface',
-            order: 20,
-            label: 'Clients',
-            path: '/clients',
-            surfaceType: 'list',
-            targets: { systems: ['clients'] }
-          }
-        }
-      }
-    },
-    bottom: {}
-  }
-}
-```
-
-Routeable sidebar leaves are projected into flat semantic surface DTOs by `projectOrganizationSurfaces(model)`. Do not author top-level `surfaces` or `navigationGroups` fields on `OrganizationModel`.
-
-## Graph IDs
-
-Cross-collection links use kind-prefixed IDs:
-
-- `system:sales.crm`
-- `integration:instantly`
-- `resource:lead-import`
-- `action:operations.queue.review`
-
-## Resource Descriptors
-
-The OM Resources domain is governance-only. Descriptors declare canonical `id`, required `systemPath`, 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.
-- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates it.
-- `createFoundationOrganizationModel()` resolves the canonical model and returns UI-facing helper outputs.
-- Plain objects merge recursively.
-- Id-keyed domain maps merge additively by key.
-- Arrays replace the default value.
-- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
-
-## Referential Integrity
-
-- System IDs must be unique.
-- Child System IDs require valid ancestors or `parentSystemId` links.
-- Systems with UI provide `ui.path`.
-- 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 System IDs stable because shell routing, gating, breadcrumbs, and docs depend on them.
-- Put resource identity and governance in `resources`; attach executable behavior in operations.
+# Organization Model
+
+The organization model is the published semantic contract that maps a tenant's System hierarchy, shell navigation, business semantics, resource governance, and graph bindings.
+
+Use this module when resolving or validating an organization's contract before wiring UI shells, routing, system gates, or domain-specific capability checks.
+
+## Published Exports
+
+The public entry point exposes:
+
+- `OrganizationModelSchema`
+- `DEFAULT_ORGANIZATION_MODEL`
+- `defineOrganizationModel`
+- `resolveOrganizationModel`
+- `createFoundationOrganizationModel`
+- node ID and System helper types
+- `OrganizationModel` and supporting domain types
+
+Import it from the published subpath:
+
+```ts
+import {
+  DEFAULT_ORGANIZATION_MODEL,
+  createFoundationOrganizationModel,
+  defineOrganizationModel,
+  resolveOrganizationModel,
+  type OrganizationModel
+} from '@elevasis/core/organization-model'
+```
+
+## Contract Shape
+
+The model is versioned and currently validates against `version: 1`.
+
+Top-level fields:
+
+- `version`
+- `domainMetadata`
+- `branding`
+- `navigation`
+- `sales`
+- `prospecting`
+- `projects`
+- `identity`
+- `customers`
+- `offerings`
+- `roles`
+- `goals`
+- `systems`
+- `resources`
+- `capabilities`
+- `statuses`
+- `knowledge`
+
+The pure collection domains are id-keyed maps: `systems`, `roles`, `goals`, `customers`, `offerings`, `resources`, `capabilities`, and `statuses`. The map key must match the entry `id`. Entries carry `order` for deterministic ordered views; use `listDomain(record)` when order matters.
+
+Resource identity is authored in `resources`. Runtime workflows, agents, integrations, and scripts import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
+
+## System Set
+
+System hierarchy is authored as an id-keyed `systems` map. Dotted IDs and `parentSystemId` define parent/child relationships:
+
+```ts
+systems: {
+  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
+  sales: { id: 'sales', order: 20, label: 'Sales', lifecycle: 'active' },
+  clients: { id: 'clients', order: 30, label: 'Clients', lifecycle: 'active' },
+  projects: { id: 'projects', order: 40, label: 'Projects', lifecycle: 'active' }
+}
+```
+
+Systems describe semantic ownership, hierarchy, lifecycle, access, and governance. Sidebar presentation is authored separately under `navigation.sidebar`; UI-backed Systems may still provide `ui.path` for route matching during the migration, but they do not author composed surface lists. Lifecycle values such as `active`, `beta`, `deprecated`, and `archived` replace the old feature enabled/dev-only split.
+
+## Sidebar Navigation
+
+Shell navigation is authored as a recursive sidebar tree:
+
+```ts
+navigation: {
+  sidebar: {
+    primary: {
+      dashboard: {
+        type: 'surface',
+        order: 10,
+        label: 'Dashboard',
+        path: '/',
+        surfaceType: 'dashboard',
+        targets: { systems: ['dashboard'] }
+      },
+      business: {
+        type: 'group',
+        order: 20,
+        label: 'Business',
+        children: {
+          clients: {
+            type: 'surface',
+            order: 20,
+            label: 'Clients',
+            path: '/clients',
+            surfaceType: 'list',
+            targets: { systems: ['clients'] }
+          }
+        }
+      }
+    },
+    bottom: {}
+  }
+}
+```
+
+Routeable sidebar leaves are projected into flat semantic surface DTOs by `projectOrganizationSurfaces(model)`. Do not author top-level `surfaces` or `navigationGroups` fields on `OrganizationModel`.
+
+## Graph IDs
+
+Cross-collection links use kind-prefixed IDs:
+
+- `system:sales.crm`
+- `integration:instantly`
+- `resource:lead-import`
+- `action:operations.queue.review`
+
+## Resource Descriptors
+
+The OM Resources domain is governance-only. Descriptors declare canonical `id`, required `systemPath`, 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.
+- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates it.
+- `createFoundationOrganizationModel()` resolves the canonical model and returns UI-facing helper outputs.
+- Plain objects merge recursively.
+- Id-keyed domain maps merge additively by key.
+- Arrays replace the default value.
+- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
+
+## Referential Integrity
+
+- System IDs must be unique.
+- Child System IDs require valid ancestors or `parentSystemId` links.
+- Systems with UI provide `ui.path`.
+- 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 System IDs stable because shell routing, gating, breadcrumbs, and docs depend on them.
+- Put resource identity and governance in `resources`; attach executable behavior in operations.