@elevasis/sdk 1.20.2 → 1.22.0

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

@@ -1,159 +1,322 @@
----
-title: Customize organization-model.ts
-description: Annotated walkthrough for customizing the flat Organization Model in template-derived projects.
----
 <!-- @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
+
+`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.
 
-# Customize organization-model.ts
-
-`core/config/organization-model.ts` is the semantic contract between the UI shell and platform operations. The shell reads one flat feature list, derives hierarchy from dotted IDs, and binds resources through graph links declared on resource metadata.
+## 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.
 
-## Features
+## System Config
 
-The `features` array is the source of truth for navigation, labels, enabled state, admin visibility, and development-only visibility.
+Use `systems[*].config` for local settings and defaults that are not semantic contracts:
 
 ```ts
 const override = defineOrganizationModel({
-  features: [
-    {
-      id: 'dashboard',
-      label: 'Dashboard',
-      enabled: true,
-      path: '/',
-      icon: 'feature.dashboard',
-      uiPosition: 'sidebar-primary'
-    },
-    {
+  systems: {
+    sales: {
       id: 'sales',
+      order: 20,
       label: 'Sales',
-      enabled: true,
-      icon: 'feature.sales',
-      uiPosition: 'sidebar-primary'
-    },
-    {
-      id: 'sales.crm',
-      label: 'CRM',
-      enabled: true,
-      path: '/crm'
-    },
-    {
-      id: 'admin',
-      label: 'Admin',
-      enabled: true,
-      path: '/admin',
-      uiPosition: 'sidebar-bottom',
-      requiresAdmin: true
+      lifecycle: 'active',
+      systems: {
+        crm: {
+          id: 'sales.crm',
+          order: 30,
+          label: 'CRM',
+          parentSystemId: 'sales',
+          lifecycle: 'active',
+          config: {
+            defaultPipelineId: 'sales.crm:catalog/pipeline',
+            kanban: {
+              groupBy: 'stage',
+              showProbability: true
+            }
+          }
+        }
+      }
     }
-  ]
+  }
 })
 ```
 
-Feature field reference:
-
-- `id` -- lowercase dotted path. Parent features are inferred from prefix segments.
-- `label` -- sidebar and breadcrumb label.
-- `description` -- optional settings/help text.
-- `enabled` -- organization default.
-- `path` -- route path for leaf nodes. Containers omit it.
-- `icon` and `color` -- optional display metadata. Use semantic icon tokens such as `feature.dashboard`, `feature.sales`, or project-owned `custom.*` tokens; UI icon libraries are implementation details.
-- `uiPosition` -- `sidebar-primary` or `sidebar-bottom`; descendants inherit it.
-- `requiresAdmin` -- hides the node for non-admin members; descendants inherit it.
-- `devOnly` -- hides the node outside development contexts; descendants inherit it.
-
-## Resource Binding
-
-Resource identity and governance metadata live in `OrganizationModel` under `resources.entries`. Workflows, agents, and integrations import those descriptors and derive runtime `resourceId` / `type` from them while still declaring semantic graph links in resource metadata.
-
-```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',
+    order: 10,
     kind: 'workflow',
-    systemId: 'sys.prospecting',
+    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',
-  links: [{ nodeId: 'feature:sales.lead-gen', kind: 'operates-on' }],
-  category: 'production'
-}
-```
-
-Use kind-prefixed graph IDs for cross-collection links:
-
-- `feature:sales.crm`
-- `integration:instantly`
-- `resource:lead-import`
-- `capability: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
-```
-
-Pass `canonicalOrganizationModel` to `ElevasisFeaturesProvider` in `ui/src/routes/__root.tsx`.
+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.
 
-## Resolve Behavior
+## Refresh Generated Scaffold Copies
 
-`createFoundationOrganizationModel(override)` resolves defaults, validates feature hierarchy, and exposes helper functions used by the shell. Arrays are replaced wholesale, so if you provide `features`, include every feature the app should expose.
+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:
 
-Validation catches duplicate feature IDs, missing parent containers, invalid graph IDs, and invalid sidebar positions.
+```bash
+pnpm scaffold:sync
+pnpm scaffold:verify
+pnpm verify:scaffold-reference
+```

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

@@ -1,10 +1,10 @@
----
-title: Build and Extend CRM
-description: Map the CRM platform primitives available to SDK projects: shared UI pages, sidebar composition, data hooks, action definitions, workflow adapters, contracts, and org-model extension boundaries.
----
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
+---
+title: Build and Extend CRM
+description: Map the CRM platform primitives available to SDK projects: shared UI pages, sidebar composition, data hooks, action definitions, workflow adapters, contracts, and org-model extension boundaries.
+---
 
 # Build and Extend CRM
 
@@ -20,7 +20,7 @@ Good trigger phrases:
 
 CRM is a layered platform surface, not one component:
 
-- **Organization OS:** feature gates, 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 feature 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. |
@@ -58,18 +58,18 @@ Read the generated contracts before changing typed boundaries:
 
 `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
 
-Look for the **CRM Platform Primitives** section. It includes deal stages, deal rows, task shapes, API schemas, action definitions, and the focused CRM workflow adapter map. The broader acquisition/list adapter maps live under **Lead Gen Platform Primitives**.
-
-Deal list and detail responses include a server-derived `priority` object. Use `deal.priority.bucketKey`, `rank`, `label`, `reason`, `latestActivityAt`, and `nextActionAt` when composing custom deal workspaces or workflow-side follow-up logic instead of re-deriving priority from `updated_at`.
+Look for the **CRM Platform Primitives** section. It includes deal stages, deal rows, task shapes, API schemas, action definitions, and the focused CRM workflow adapter map. The broader acquisition/list adapter maps live under **Lead Gen Platform Primitives**.
+
+Deal list and detail responses include a server-derived `priority` object. Use `deal.priority.bucketKey`, `rank`, `label`, `reason`, `latestActivityAt`, and `nextActionAt` when composing custom deal workspaces or workflow-side follow-up logic instead of re-deriving priority from `updated_at`.
 
 ## 1. Extend CRM Navigation or Sidebar
 
-For a simple nav addition, extend `CRM_ITEMS` and override the CRM feature manifest:
+For a simple nav addition, extend `CRM_ITEMS` and override the CRM system manifest:
 
 ```tsx
 // ui/src/routes/__root.tsx
 import { crmManifest, CRM_ITEMS, CrmSidebar, CrmSidebarMiddle } from '@elevasis/ui/features/crm'
-import type { FeatureModule } from '@elevasis/ui/provider'
+import type { SystemModule } from '@elevasis/ui/provider'
 import type { NavItem } from '@elevasis/ui/layout'
 import { IconFileText } from '@tabler/icons-react'
 
@@ -84,13 +84,13 @@ const CustomCrmSidebar = () => (
   </CrmSidebar>
 )
 
-export const customCrmManifest: FeatureModule = {
+export const customCrmManifest: SystemModule = {
   ...crmManifest,
   sidebar: CustomCrmSidebar
 }
 ```
 
-Then replace `crmManifest` with `customCrmManifest` in the local `FEATURE_MANIFESTS` array and add the matching route under `ui/src/routes/crm/`.
+Then replace `crmManifest` with `customCrmManifest` in the local `SYSTEM_MANIFESTS` array and add the matching route under `ui/src/routes/crm/`.
 
 For structural changes, compose `CrmSidebarTop`, `SubshellNavList`, `SubshellSidebarSection`, `MyTasksPanel`, and `QuickCreateActions`. The full sidebar decision tree lives in `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`.
 
@@ -164,10 +164,10 @@ Inside deployed workflows, use worker adapters instead of browser hooks or direc
 
 ```ts
 // operations/src/sales/follow-up-stale-deals.ts
-import type { WorkflowDefinition } from '@elevasis/sdk'
-import { crm } from '@elevasis/sdk/worker'
-import { resourceDescriptors } from '@core/config/organization-model'
-import { z } from 'zod'
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { crm } from '@elevasis/sdk/worker'
+import { resourceDescriptors } from '@core/config/organization-model'
+import { z } from 'zod'
 
 const inputSchema = z.object({
   stage: z.string().default('proposal')
@@ -177,15 +177,14 @@ const outputSchema = z.object({
   touched: z.number()
 })
 
-export const followUpStaleDealsWorkflow: WorkflowDefinition = {
-  config: {
-    resource: resourceDescriptors.followUpStaleDeals,
-    resourceId: resourceDescriptors.followUpStaleDeals.id,
-    name: 'Follow Up Stale Deals',
-    type: resourceDescriptors.followUpStaleDeals.kind,
-    version: '1.0.0',
-    status: 'dev',
-    links: [{ nodeId: 'feature:sales.crm', kind: 'operates-on' }]
+export const followUpStaleDealsWorkflow: WorkflowDefinition = {
+  config: {
+    resource: resourceDescriptors.followUpStaleDeals,
+    resourceId: resourceDescriptors.followUpStaleDeals.id,
+    name: 'Follow Up Stale Deals',
+    type: resourceDescriptors.followUpStaleDeals.kind,
+    version: '1.0.0',
+    status: 'dev',
   },
   contract: { inputSchema, outputSchema },
   steps: {
@@ -196,15 +195,15 @@ export const followUpStaleDealsWorkflow: WorkflowDefinition = {
       outputSchema,
       next: null,
       handler: async (input) => {
-        const deals = await crm.listDeals({ stage: input.stage })
-
-        for (const deal of deals) {
-          if (!['follow_up_due', 'stale'].includes(deal.priority.bucketKey)) continue
-
-          await crm.createDealTask({
-            dealId: deal.id,
-            title: 'Follow up',
-            kind: 'email'
+        const deals = await crm.listDeals({ stage: input.stage })
+
+        for (const deal of deals) {
+          if (!['follow_up_due', 'stale'].includes(deal.priority.bucketKey)) continue
+
+          await crm.createDealTask({
+            dealId: deal.id,
+            title: 'Follow up',
+            kind: 'email'
           })
           await crm.recordActivity({
             dealId: deal.id,
@@ -226,11 +225,11 @@ Use `crm` for focused CRM deal reads, notes, tasks, activity, and cleanup. Use `
 
 ## 5. Customize Pipeline Semantics
 
-CRM feature identity remains `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:
-
-`core/config/organization-model.ts`
+For stage labels or stage sets, update the project model:
+
+`core/config/organization-model.ts`
 
 Keep these boundaries straight:
 
@@ -255,3 +254,5 @@ If you changed platform-level CRM contracts in the monorepo, the platform mainta
 pnpm scaffold:sync
 pnpm scaffold:verify
 ```
+
+