@elevasis/sdk 1.21.0 → 1.22.0

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

@@ -1,117 +1,208 @@
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
----
-title: Customize organization-model.ts
-description: Annotated walkthrough for customizing the System-backed Organization Model in template-derived projects.
----
-
-# Customize organization-model.ts
+---
+title: Customize organization-model.ts
+description: Annotated walkthrough for customizing the System-backed Organization Model in template-derived projects.
+---
+
+# Customize organization-model.ts
+
+`core/config/organization-model.ts` is the semantic contract between the UI shell and platform operations. The shell reads the id-keyed `systems` map for semantic ownership and access, reads `navigation.sidebar` for shell navigation, and binds resources through the id-keyed `resources` map.
+
+## Imports
+
+```ts
+import {
+  createFoundationOrganizationModel,
+  defineOrganizationModel,
+  type OrganizationModel
+} from '@elevasis/core/organization-model'
+```
+
+- `defineOrganizationModel` gives a typed override shape.
+- `createFoundationOrganizationModel` resolves defaults and returns the canonical model plus UI-facing helpers.
+- `OrganizationModel` is the fully resolved model type.
+
+## Systems
+
+The `systems` map is the source of truth for semantic hierarchy, lifecycle, admin visibility, and governed ownership.
+
+```ts
+const override = defineOrganizationModel({
+  systems: {
+    dashboard: {
+      id: 'dashboard',
+      order: 10,
+      label: 'Dashboard',
+      lifecycle: 'active',
+      description: 'Command Center home'
+    },
+    sales: {
+      id: 'sales',
+      order: 20,
+      label: 'Sales',
+      lifecycle: 'active'
+    },
+    'sales.crm': {
+      id: 'sales.crm',
+      order: 30,
+      label: 'CRM',
+      parentSystemId: 'sales',
+      lifecycle: 'active',
+      description: 'CRM pipeline and deal operations'
+    }
+  },
+  navigation: {
+    sidebar: {
+      primary: {
+        dashboard: {
+          type: 'surface',
+          order: 10,
+          label: 'Dashboard',
+          path: '/',
+          surfaceType: 'dashboard',
+          icon: 'feature.dashboard',
+          targets: { systems: ['dashboard'] }
+        },
+        business: {
+          type: 'group',
+          order: 20,
+          label: 'Business',
+          children: {
+            crm: {
+              type: 'surface',
+              order: 10,
+              label: 'CRM',
+              path: '/crm',
+              surfaceType: 'page',
+              targets: { systems: ['sales.crm'] }
+            }
+          }
+        }
+      },
+      bottom: {}
+    }
+  }
+})
+```
+
+System field reference:
+
+- `id` -- lowercase dotted path. Parent Systems are inferred from prefix segments or declared through `parentSystemId`.
+- `order` -- deterministic map iteration order. Use multiples of 10 for easy insertion.
+- `label` -- sidebar and breadcrumb label.
+- `description` -- optional settings/help text.
+- `kind` -- product, operational, platform, or diagnostic.
+- `parentSystemId` -- explicit parent System link.
+- `lifecycle` -- draft, beta, active, deprecated, or archived.
+- `ui` -- optional route metadata used by shell matching during migration.
+- `requiresAdmin` -- hides the node for non-admin members; descendants inherit it.
+- `actions` / `policies` -- references to cross-cutting domains.
+- `ontology` -- System-owned object, link, action, catalog, event, surface, interface, value-type, property, or group records.
+- `config` -- JSON-serializable settings local to this System.
+- `systems` -- nested child Systems. Use this for new recursive authoring; `subsystems` is a compatibility alias only.
 
-`core/config/organization-model.ts` is the semantic contract between the UI shell and platform operations. The shell reads the id-keyed `systems` map for semantic ownership and access, reads `navigation.sidebar` for shell navigation, and binds resources through the id-keyed `resources` map.
+## Ontology
 
-## Imports
+Use top-level `ontology` for global/shared primitives and `System.ontology` for owned contracts. The resolved ontology index is compiled from root and System scopes and validated for ID shape, kind mismatch, and duplicate IDs.
 
 ```ts
-import {
-  createFoundationOrganizationModel,
-  defineOrganizationModel,
-  type OrganizationModel
-} from '@elevasis/core/organization-model'
+const override = defineOrganizationModel({
+  ontology: {
+    valueTypes: {
+      'global:value-type/text': {
+        id: 'global:value-type/text',
+        label: 'Text'
+      }
+    }
+  },
+  systems: {
+    sales: {
+      id: 'sales',
+      order: 20,
+      label: 'Sales',
+      lifecycle: 'active',
+      systems: {
+        crm: {
+          id: 'sales.crm',
+          order: 30,
+          label: 'CRM',
+          parentSystemId: 'sales',
+          lifecycle: 'active',
+          ontology: {
+            objectTypes: {
+              'sales.crm:object/deal': {
+                id: 'sales.crm:object/deal',
+                label: 'Deal',
+                ownerSystemId: 'sales.crm'
+              }
+            },
+            actionTypes: {
+              'sales.crm:action/deal.update-stage': {
+                id: 'sales.crm:action/deal.update-stage',
+                label: 'Update Deal Stage',
+                ownerSystemId: 'sales.crm',
+                actsOn: ['sales.crm:object/deal']
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+})
 ```
 
-- `defineOrganizationModel` gives a typed override shape.
-- `createFoundationOrganizationModel` resolves defaults and returns the canonical model plus UI-facing helpers.
-- `OrganizationModel` is the fully resolved model type.
+Top-level `entities`, top-level `actions`, and `System.content kind: "schema"` remain accepted for existing consumers and are projected into compiled ontology indexes. Prefer `System.ontology` for new object/action/catalog contracts.
 
-## Systems
+## System Config
 
-The `systems` map is the source of truth for semantic hierarchy, lifecycle, admin visibility, and governed ownership.
+Use `systems[*].config` for local settings and defaults that are not semantic contracts:
 
 ```ts
 const override = defineOrganizationModel({
   systems: {
-    dashboard: {
-      id: 'dashboard',
-      order: 10,
-      label: 'Dashboard',
-      lifecycle: 'active',
-      description: 'Command Center home'
-    },
     sales: {
       id: 'sales',
       order: 20,
       label: 'Sales',
-      lifecycle: 'active'
-    },
-    'sales.crm': {
-      id: 'sales.crm',
-      order: 30,
-      label: 'CRM',
-      parentSystemId: 'sales',
       lifecycle: 'active',
-      description: 'CRM pipeline and deal operations'
-    }
-  },
-  navigation: {
-    sidebar: {
-      primary: {
-        dashboard: {
-          type: 'surface',
-          order: 10,
-          label: 'Dashboard',
-          path: '/',
-          surfaceType: 'dashboard',
-          icon: 'feature.dashboard',
-          targets: { systems: ['dashboard'] }
-        },
-        business: {
-          type: 'group',
-          order: 20,
-          label: 'Business',
-          children: {
-            crm: {
-              type: 'surface',
-              order: 10,
-              label: 'CRM',
-              path: '/crm',
-              surfaceType: 'page',
-              targets: { systems: ['sales.crm'] }
+      systems: {
+        crm: {
+          id: 'sales.crm',
+          order: 30,
+          label: 'CRM',
+          parentSystemId: 'sales',
+          lifecycle: 'active',
+          config: {
+            defaultPipelineId: 'sales.crm:catalog/pipeline',
+            kanban: {
+              groupBy: 'stage',
+              showProbability: true
             }
           }
         }
-      },
-      bottom: {}
+      }
     }
   }
 })
 ```
 
-System field reference:
-
-- `id` -- lowercase dotted path. Parent Systems are inferred from prefix segments or declared through `parentSystemId`.
-- `order` -- deterministic map iteration order. Use multiples of 10 for easy insertion.
-- `label` -- sidebar and breadcrumb label.
-- `description` -- optional settings/help text.
-- `kind` -- product, operational, platform, or diagnostic.
-- `parentSystemId` -- explicit parent System link.
-- `lifecycle` -- draft, beta, active, deprecated, or archived.
-- `ui` -- optional route metadata used by shell matching during migration.
-- `requiresAdmin` -- hides the node for non-admin members; descendants inherit it.
-- `actions` / `policies` -- references to cross-cutting domains.
-
-## Sidebar Navigation
-
-Author shell navigation under `navigation.sidebar`. Groups can contain nested nodes; routeable surface leaves provide `path`, `surfaceType`, and `targets`. Dashboard should appear before Business, Business is a navigation group only, and `/clients` is the canonical clients route.
-
-## Resource Binding
-
-Resource identity and governance metadata live in `OrganizationModel` under `resources`. Workflows, agents, integrations, and scripts import those descriptors and derive runtime `resourceId` / `type` from them. The graph derives System membership from `ResourceEntry.systemPath`.
-
-```ts
-// core/config/organization-model.ts
-import { defineResources } from '@elevasis/core/organization-model'
-
+Keep semantic nouns, verbs, relationships, events, catalogs, interfaces, and value types in ontology. Keep secrets, credentials, per-run execution state, logs, and external service state outside the Organization Model.
+
+## Sidebar Navigation
+
+Author shell navigation under `navigation.sidebar`. Groups can contain nested nodes; routeable surface leaves provide `path`, `surfaceType`, and `targets`. Dashboard should appear before Business, Business is a navigation group only, and `/clients` is the canonical clients route.
+
+## Resource Binding
+
+Resource identity and governance metadata live in `OrganizationModel` under `resources`. Workflows, agents, integrations, and scripts import those descriptors and derive runtime `resourceId` / `type` from them. The graph derives System membership from `ResourceEntry.systemPath`.
+
+```ts
+// core/config/organization-model.ts
+import { defineResources } from '@elevasis/core/organization-model'
+
 export const resourceDescriptors = defineResources({
   leadImport: {
     id: 'lead-import',
@@ -119,69 +210,113 @@ export const resourceDescriptors = defineResources({
     kind: 'workflow',
     systemPath: 'sales.crm',
     ownerRoleId: 'role-ops-lead',
-    status: 'active'
+    status: 'active',
+    actionKey: 'sales.crm.deal.update-stage',
+    ontology: {
+      implements: ['sales.crm:action/deal.update-stage'],
+      reads: ['sales.crm:object/deal'],
+      writes: ['sales.crm:object/deal'],
+      usesCatalogs: ['sales.crm:catalog/pipeline'],
+      emits: ['sales.crm:event/deal-stage-updated']
+    }
   }
 })
+
+// operations/src/lead-import/index.ts
+config: {
+  resource: resourceDescriptors.leadImport,
+  resourceId: resourceDescriptors.leadImport.id,
+  name: 'Lead Import',
+  type: resourceDescriptors.leadImport.kind,
+  version: '1.0.0',
+  status: 'prod',
+  category: 'production'
+}
+```
+
+Use kind-prefixed graph IDs for cross-collection links:
+
+- `system:sales.crm`
+- `integration:instantly`
+- `resource:lead-import`
+- `action:operations.queue.review`
+
+`category` is one of `production`, `diagnostic`, `internal`, or `testing`.
 
-// operations/src/lead-import/index.ts
-config: {
-  resource: resourceDescriptors.leadImport,
-  resourceId: resourceDescriptors.leadImport.id,
-  name: 'Lead Import',
-  type: resourceDescriptors.leadImport.kind,
-  version: '1.0.0',
-  status: 'prod',
-  category: 'production'
-}
-```
-
-Use kind-prefixed graph IDs for cross-collection links:
-
-- `system:sales.crm`
-- `integration:instantly`
-- `resource:lead-import`
-- `action:operations.queue.review`
+`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`.
 
-`category` is one of `production`, `diagnostic`, `internal`, or `testing`.
+## Compatibility Domain Mirrors
 
-## Domain Config
+The old `sales`, `prospecting`, and `projects` top-level keys are not part of the current primary Organization Model schema. If an older local project still has bridge-era examples for those concepts, migrate the data toward owning Systems:
 
-The `sales`, `prospecting`, and `projects` top-level keys configure business semantics such as pipeline stages, entity IDs, and status vocabularies. They are not shell navigation.
+- durable objects -> `System.ontology.objectTypes`
+- stable verbs -> `System.ontology.actionTypes`
+- pipelines, stages, templates, and status vocabularies -> `System.ontology.catalogTypes`
+- local settings and defaults -> `System.config`
+- existing `System.content kind: "schema"` nodes -> compatibility catalog projections
 
 ```ts
-sales: {
-  entityId: 'crm.deal',
-  defaultPipelineId: 'default',
-  pipelines: [
-    {
-      id: 'default',
-      label: 'Default Pipeline',
-      entityId: 'crm.deal',
-      stages: [
-        { id: 'interested', label: 'Interested', color: 'blue', order: 1, semanticClass: 'open' },
-        { id: 'closed_won', label: 'Closed Won', color: 'green', order: 4, semanticClass: 'closed_won' }
-      ]
+systems: {
+  sales: {
+    id: 'sales',
+    order: 20,
+    label: 'Sales',
+    lifecycle: 'active',
+    systems: {
+      crm: {
+        id: 'sales.crm',
+        order: 30,
+        label: 'CRM',
+        lifecycle: 'active',
+        parentSystemId: 'sales',
+        ontology: {
+          catalogTypes: {
+            'sales.crm:catalog/pipeline': {
+              id: 'sales.crm:catalog/pipeline',
+              label: 'Default Pipeline',
+              kind: 'pipeline',
+              ownerSystemId: 'sales.crm',
+              entries: {
+                interested: { label: 'Interested', color: 'blue', order: 10, semanticClass: 'open' },
+                closed_won: { label: 'Closed Won', color: 'green', order: 20, semanticClass: 'closed_won' }
+              }
+            }
+          }
+        }
+      }
     }
-  ]
+  }
 }
 ```
-
+
 Keep `semanticClass` values stable; platform analytics and triggers depend on them.
 
-## Export Pattern
-
-```ts
-const foundation = createFoundationOrganizationModel(override)
-
-export const canonicalOrganizationModel: OrganizationModel = foundation.canonical
-export const organizationModel = foundation.model
-export const { getOrganizationSurface } = foundation
+Policy and role integration remains outside ontology in this pass. Use `roles`, `policies`, `responsibleRoleId`, and `ownerRoleId` for accountability and access semantics until a dedicated policy/role ontology design is published.
+
+## Export Pattern
+
+```ts
+const foundation = createFoundationOrganizationModel(override)
+
+export const canonicalOrganizationModel: OrganizationModel = foundation.canonical
+export const organizationModel = foundation.model
+export const { getOrganizationSurface } = foundation
+```
+
+Pass `canonicalOrganizationModel` to `ElevasisSystemsProvider` in `ui/src/routes/__root.tsx`.
+
+## Resolve Behavior
+
+`createFoundationOrganizationModel(override)` resolves defaults, validates System hierarchy, and exposes helper functions used by the shell. Id-keyed domain maps merge additively by key, so tenant overrides can add one System or resource without re-authoring every default entry.
+
+Validation catches duplicate System IDs, missing parent Systems, invalid graph IDs, invalid UI paths, invalid ontology IDs, ontology kind mismatches, and duplicate ontology IDs.
+
+## Refresh Generated Scaffold Copies
+
+This file is source guidance for generated SDK reference copies. After changing Organization Model scaffold docs, refresh and verify generated outputs from the monorepo root:
+
+```bash
+pnpm scaffold:sync
+pnpm scaffold:verify
+pnpm verify:scaffold-reference
 ```
-
-Pass `canonicalOrganizationModel` to `ElevasisSystemsProvider` in `ui/src/routes/__root.tsx`.
-
-## Resolve Behavior
-
-`createFoundationOrganizationModel(override)` resolves defaults, validates System hierarchy, and exposes helper functions used by the shell. Id-keyed domain maps merge additively by key, so tenant overrides can add one System or resource without re-authoring every default entry.
-
-Validation catches duplicate System IDs, missing parent Systems, invalid graph IDs, and invalid UI paths.

package/reference/scaffold/recipes/extend-a-base-entity.md

@@ -10,7 +10,7 @@ description: Add project-specific metadata to the canonical entity shapes (Proje
 
 Workflows and UI features often operate on domain entities such as projects, deals, companies, or contacts. Rather than each project declaring its own shape from scratch, `@elevasis/core/entities` provides typed base interfaces generic over a `<TMeta>` slot. External projects extend these to add project-specific fields while keeping the canonical shape stable and interoperable with platform tooling.
 
-The canonical demo lives in `core/types/entities.ts` of any scaffold project.
+The canonical demo lives in `core/types/entities.ts` of any scaffold project.
 
 ---
 
@@ -33,7 +33,7 @@ All imports come from `@elevasis/core/entities`.
 
 ## Recipe 1 -- Extend a base entity with custom metadata
 
-Place this in `core/types/entities.ts`. This is the primary pattern -- the scaffold template ships this exact example.
+Place this in `core/types/entities.ts`. This is the primary pattern -- the scaffold template ships this exact example.
 
 ```ts
 import { z } from 'zod'
@@ -59,7 +59,7 @@ Key points:
 - `BaseProjectSchema.extend({ metadata: ... })` merges your metadata Zod schema into the validated shape. Zod handles the rest.
 - `BaseProject<ProjectMeta>` infers the TypeScript type with your metadata typed correctly.
 - Only the `metadata` field is extended -- all other base fields (`id`, `organizationId`, `name`, `status`, `createdAt`, `updatedAt`, etc.) are inherited unchanged.
-- This file is the single source of truth for entity shapes across `core/`, `operations/`, and `ui/`.
+- This file is the single source of truth for entity shapes across `core/`, `operations/`, and `ui/`.
 
 ---
 
@@ -87,7 +87,7 @@ Workflows that operate on projects or deals should reference the project-local e
 ```ts
 import { z } from 'zod'
 import type { WorkflowDefinition } from '@elevasis/sdk'
-import { ProjectSchema } from '@core/types/entities'
+import { ProjectSchema } from '@core/types/entities'
 
 export const myWorkflow: WorkflowDefinition = {
   id: 'my-workflow',
@@ -99,16 +99,16 @@ export const myWorkflow: WorkflowDefinition = {
 }
 ```
 
-The `@core/*` alias maps to the `core/` workspace package. This keeps entity contracts in one place and ensures the workflow input type matches whatever the UI passes as the execution payload.
+The `@core/*` alias maps to the `core/` workspace package. This keeps entity contracts in one place and ensures the workflow input type matches whatever the UI passes as the execution payload.
 
 ---
 
 ## Recipe 4 -- Reference entity types from the UI
 
-UI components accept entity types directly in props. The entity type flows from the `core` package through the component into the workflow execution payload:
+UI components accept entity types directly in props. The entity type flows from the `core` package through the component into the workflow execution payload:
 
 ```tsx
-import type { Project } from '@core/types/entities'
+import type { Project } from '@core/types/entities'
 
 interface ProjectCardProps {
   project: Project
@@ -130,7 +130,7 @@ When wiring this to a `RunResourceButton`, the entity instance becomes the workf
 
 ## Verification
 
-- **Test core contracts:** `pnpm -C core test` runs the Vitest suite. The template ships `core/types/entities.test.ts` as a working smoke-check -- it `safeParse`s a valid project (expects success) and an invalid one (expects failure). Run this after any schema change.
+- **Test core contracts:** `pnpm -C core test` runs the Vitest suite. The template ships `core/types/entities.test.ts` as a working smoke-check -- it `safeParse`s a valid project (expects success) and an invalid one (expects failure). Run this after any schema change.
 - **Round-trip safeParse:** Call `ProjectSchema.safeParse(candidateObject)` in a test or REPL to confirm the Zod shape accepts the data your workflows and UI will produce.
 - **Cross-package type check:** `pnpm -C ui build` will surface any TypeScript errors if a UI component or hook passes a mismatched entity type to a workflow input.
 

package/reference/scaffold/recipes/extend-crm.md

@@ -20,7 +20,7 @@ Good trigger phrases:
 
 CRM is a layered platform surface, not one component:
 
-- **Organization OS:** System access, sales pipeline semantics, quick access, and labels live in the organization model.
+- **Organization OS:** System access, sales pipeline semantics, quick access, and labels live in the organization model.
 - **Shared UI:** CRM pages, sidebars, workbench panels, overview widgets, and Kanban/detail components live in `@elevasis/ui`.
 - **Headless hooks:** deal, company, contact, note, task, list, transition, and action hooks live under `@elevasis/ui/hooks`.
 - **Action system:** `ActionDef`, `DEFAULT_CRM_ACTIONS`, `deriveActions`, and provider-level `crmActions` configure deal actions.
@@ -31,7 +31,7 @@ CRM is a layered platform surface, not one component:
 
 | User wants | Start here | Notes |
 | --- | --- | --- |
-| Change CRM System availability, labels, pipeline stages, or resource descriptors | `core/config/organization-model.ts` | Treat this as Organization OS work. Use the project's configure ceremony if available. |
+| Change CRM System availability, labels, pipeline stages, or resource descriptors | `core/config/organization-model.ts` | Treat this as Organization OS work. Use the project's configure ceremony if available. |
 | Add CRM sidebar nav or a CRM route | `@elevasis/ui/features/crm` and `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` | Prefer manifest/sidebar composition. Do not fork shared source first. |
 | Wrap a shared CRM page with project chrome | `DealsListPage`, `DealDetailPage`, `CrmOverview` from `@elevasis/ui/features/crm` | Keep route files thin and put project-specific logic in local feature modules. |
 | Build a custom deal page | `useDealDetail`, `useDealNotes`, `useDealTasks`, `useExecuteAction` from `@elevasis/ui/hooks` | Use hooks for platform data and compose your own UI. |
@@ -225,7 +225,7 @@ Use `crm` for focused CRM deal reads, notes, tasks, activity, and cleanup. Use `
 
 ## 5. Customize Pipeline Semantics
 
-CRM System identity is `sales.crm`, but the organization-model domain is `sales`.
+CRM System identity is `sales.crm`, but the organization-model domain is `sales`.
 
 For stage labels or stage sets, update the project model: