@elevasis/core 0.42.1 → 0.44.0

package/src/organization-model/__tests__/schema-refinements.test.ts

@@ -4,6 +4,15 @@ import { DEFAULT_ORGANIZATION_MODEL } from '../defaults'
 import { refineOrganizationModel } from '../schema-refinements'
 import type { OrganizationModel } from '../types'
 
+type RefinementCase = {
+  name: string
+  model: OrganizationModel
+  expected: {
+    message: string
+    path: Array<string | number>
+  }
+}
+
 function collectRefinementIssues(model: OrganizationModel): z.ZodIssue[] {
   const issues: z.ZodIssue[] = []
   const ctx = {
@@ -16,6 +25,21 @@ function collectRefinementIssues(model: OrganizationModel): z.ZodIssue[] {
   return issues
 }
 
+function makeModel(overrides: Partial<OrganizationModel>): OrganizationModel {
+  return {
+    ...DEFAULT_ORGANIZATION_MODEL,
+    systems: {
+      test: {
+        id: 'test',
+        order: 10,
+        label: 'Test',
+        lifecycle: 'active'
+      }
+    },
+    ...overrides
+  }
+}
+
 describe('refineOrganizationModel', () => {
   it('emits resource systemPath issues through the extracted refinement boundary', () => {
     const model: OrganizationModel = {
@@ -69,4 +93,158 @@ describe('refineOrganizationModel', () => {
       true
     )
   })
+
+  it.each<RefinementCase>([
+    {
+      name: 'system parent cycle',
+      model: makeModel({
+        systems: {
+          a: { id: 'a', order: 10, label: 'A', parentSystemId: 'b' },
+          b: { id: 'b', order: 20, label: 'B', parentSystemId: 'a' }
+        }
+      }),
+      expected: {
+        path: ['systems', 'a', 'parentSystemId'],
+        message: 'System "a" has a parent cycle'
+      }
+    },
+    {
+      name: 'role reportsToId cycle',
+      model: makeModel({
+        roles: {
+          'role.a': { id: 'role.a', order: 10, title: 'Role A', reportsToId: 'role.b' },
+          'role.b': { id: 'role.b', order: 20, title: 'Role B', reportsToId: 'role.a' }
+        }
+      }),
+      expected: {
+        path: ['roles', 'role.a', 'reportsToId'],
+        message: 'Role "role.a" has a reportsToId cycle'
+      }
+    },
+    {
+      name: 'duplicate sidebar paths',
+      model: makeModel({
+        navigation: {
+          ...DEFAULT_ORGANIZATION_MODEL.navigation,
+          sidebar: {
+            primary: {
+              first: { type: 'surface', label: 'First', path: '/shared', surfaceType: 'page', order: 10 },
+              second: { type: 'surface', label: 'Second', path: '/shared/', surfaceType: 'page', order: 20 }
+            },
+            bottom: {}
+          }
+        }
+      }),
+      expected: {
+        path: ['navigation', 'sidebar', 'primary', 'second', 'path'],
+        message: 'Sidebar surface path "/shared/" duplicates surface "first"'
+      }
+    },
+    {
+      name: 'topology invalid refs',
+      model: makeModel({
+        topology: {
+          version: 1,
+          relationships: {
+            missing: {
+              from: { kind: 'system', id: 'missing' },
+              kind: 'uses',
+              to: { kind: 'system', id: 'test' }
+            }
+          }
+        }
+      }),
+      expected: {
+        path: ['topology', 'relationships', 'missing', 'from'],
+        message: 'Topology relationship "missing" from references unknown system "missing"'
+      }
+    },
+    {
+      name: 'knowledge kind target mismatch',
+      model: makeModel({
+        roles: {
+          'role.ops': { id: 'role.ops', order: 10, title: 'Ops' }
+        },
+        knowledge: {
+          'knowledge.strategy': {
+            id: 'knowledge.strategy',
+            kind: 'strategy',
+            title: 'Strategy',
+            summary: 'Strategy summary',
+            body: 'Body',
+            updatedAt: '2026-06-04',
+            ownerIds: [],
+            links: [{ target: { kind: 'role', id: 'role.ops' }, nodeId: 'role:role.ops' }]
+          }
+        }
+      }),
+      expected: {
+        path: ['knowledge', 'knowledge.strategy', 'links', 0, 'target', 'kind'],
+        message: 'Knowledge node "knowledge.strategy" kind "strategy" cannot govern role targets'
+      }
+    },
+    {
+      name: 'entity unknown system',
+      model: makeModel({
+        entities: {
+          lead: { id: 'lead', order: 10, label: 'Lead', ownedBySystemId: 'missing' }
+        }
+      }),
+      expected: {
+        path: ['entities', 'lead', 'ownedBySystemId'],
+        message: 'Entity "lead" references unknown ownedBySystemId "missing"'
+      }
+    },
+    {
+      name: 'policy unknown action',
+      model: makeModel({
+        policies: {
+          'policy.test': {
+            id: 'policy.test',
+            order: 10,
+            label: 'Test Policy',
+            trigger: { kind: 'action-invocation', actionId: 'missing.action' },
+            actions: [{ kind: 'invoke-action', actionId: 'missing.action' }],
+            appliesTo: { systemIds: [], actionIds: ['missing.action'], resourceIds: [], roleIds: [] }
+          }
+        }
+      }),
+      expected: {
+        path: ['policies', 'policy.test', 'appliesTo', 'actionIds', 0],
+        message: 'Policy "policy.test" applies to unknown action "missing.action"'
+      }
+    },
+    {
+      name: 'active system with no enabled descendants',
+      model: makeModel({
+        systems: {
+          parent: {
+            id: 'parent',
+            order: 10,
+            label: 'Parent',
+            lifecycle: 'active',
+            systems: {
+              child: { id: 'child', order: 10, label: 'Child', lifecycle: 'archived' }
+            }
+          }
+        }
+      }),
+      expected: {
+        path: ['systems', 'parent', 'lifecycle'],
+        message: 'System "parent" is active but has no active descendants'
+      }
+    }
+  ])('emits focused refinement issues for $name', ({ model, expected }) => {
+    const issues = collectRefinementIssues(model)
+
+    expect(issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: z.ZodIssueCode.custom,
+          path: expected.path,
+          message: expected.message
+        })
+      ])
+    )
+  })
 })

package/src/organization-model/cross-ref.ts

@@ -11,7 +11,7 @@
 
 import { compileOrganizationOntology } from './ontology'
 import { listAllSystems } from './helpers'
-import type { OntologyKind } from './ontology'
+import type { OntologyCompilation, OntologyKind } from './ontology'
 import type { OrganizationModel } from './types'
 
 // ---------------------------------------------------------------------------
@@ -36,7 +36,7 @@ export const ONTOLOGY_REFERENCE_KEY_KINDS: Record<string, OntologyKind> = {
   interfaceType: 'interface',
   propertyType: 'property',
   groupType: 'group',
-  surfaceType: 'surface',
+  endpointType: 'endpoint',
   stepCatalog: 'catalog'
 } satisfies Record<string, OntologyKind>
 
@@ -69,12 +69,23 @@ export interface OmCrossRefIndex {
   stageIds: Set<string>
 }
 
+export interface OmCompilationContext {
+  crossRefIndex: OmCrossRefIndex
+  ontologyCompilation: OntologyCompilation
+}
+
+const omCompilationContextCache = new WeakMap<OrganizationModel, OmCompilationContext>()
+
 /**
- * Build the OmCrossRefIndex from a resolved OrganizationModel.
+ * Build the OmCrossRefIndex from a resolved OrganizationModel and a compiled
+ * ontology result.
  *
  * Call once per validation pass and share the result across all checks.
  */
-export function buildOmCrossRefIndex(model: OrganizationModel): OmCrossRefIndex {
+function buildOmCrossRefIndexFromOntology(
+  model: OrganizationModel,
+  ontologyCompilation: OntologyCompilation
+): OmCrossRefIndex {
   // Systems: keyed by path AND by system.id (path-OR-id resolution)
   const systemsById = new Map<string, unknown>()
   for (const { path, system } of listAllSystems(model)) {
@@ -91,8 +102,6 @@ export function buildOmCrossRefIndex(model: OrganizationModel): OmCrossRefIndex
   const customerSegmentIds = new Set(Object.keys(model.customers ?? {}))
   const offeringIds = new Set(Object.keys(model.offerings ?? {}))
 
-  const ontologyCompilation = compileOrganizationOntology(model)
-
   const ontologyIndexByKind: Record<OntologyKind, Record<string, unknown>> = {
     object: ontologyCompilation.ontology.objectTypes,
     link: ontologyCompilation.ontology.linkTypes,
@@ -103,7 +112,7 @@ export function buildOmCrossRefIndex(model: OrganizationModel): OmCrossRefIndex
     'value-type': ontologyCompilation.ontology.valueTypes,
     property: ontologyCompilation.ontology.sharedProperties,
     group: ontologyCompilation.ontology.groups,
-    surface: ontologyCompilation.ontology.surfaces
+    endpoint: ontologyCompilation.ontology.endpoints
   }
 
   const ontologyIds = new Set(Object.values(ontologyIndexByKind).flatMap((index) => Object.keys(index)))
@@ -136,6 +145,33 @@ export function buildOmCrossRefIndex(model: OrganizationModel): OmCrossRefIndex
   }
 }
 
+/**
+ * Build and memoize the shared OM compilation context for a resolved model.
+ *
+ * This combines ontology compilation and cross-reference indexing so validation
+ * gates can reuse one ontology pass while preserving browser-safe imports.
+ */
+export function buildOmCompilationContext(model: OrganizationModel): OmCompilationContext {
+  const cached = omCompilationContextCache.get(model)
+  if (cached !== undefined) return cached
+
+  const ontologyCompilation = compileOrganizationOntology(model)
+  const crossRefIndex = buildOmCrossRefIndexFromOntology(model, ontologyCompilation)
+  const context = { crossRefIndex, ontologyCompilation }
+  omCompilationContextCache.set(model, context)
+  return context
+}
+
+/**
+ * Build the OmCrossRefIndex from a resolved OrganizationModel.
+ *
+ * Back-compat helper retained for existing consumers. New validation paths that
+ * also need ontology diagnostics should prefer buildOmCompilationContext().
+ */
+export function buildOmCrossRefIndex(model: OrganizationModel): OmCrossRefIndex {
+  return buildOmCompilationContext(model).crossRefIndex
+}
+
 // ---------------------------------------------------------------------------
 // Canonical resolution functions
 // ---------------------------------------------------------------------------

package/src/organization-model/defaults.ts

@@ -7,11 +7,11 @@
  *
  * It does NOT contain Elevasis-specific identity, systems, or action entries.
  * Runtime consumers that need the full Elevasis canonical model should import
- * `canonicalOrganizationModel` from `@repo/elevasis-core` instead.
+ * `canonicalOrganizationModel` from the tenant-owned organization model package instead.
  *
  * Elevasis-specific systems, actions (LEAD_GEN_ACTION_ENTRIES, CRM_ACTION_ENTRIES,
  * DEFAULT_ORGANIZATION_MODEL_ACTIONS), and the platform system description have been
- * relocated to `@repo/elevasis-core/src/organization-model/`.
+ * relocated to the tenant-owned organization model package.
  */
 import type { OrganizationModel } from './types'
 import { DEFAULT_ORGANIZATION_MODEL_BRANDING } from './domains/branding'

package/src/organization-model/domains/actions.ts

@@ -96,7 +96,7 @@ export const ActionsDomainSchema = z
  * Generic empty default for the actions domain.
  * Elevasis-specific action entries (LEAD_GEN_ACTION_ENTRIES, CRM_ACTION_ENTRIES,
  * DEFAULT_ORGANIZATION_MODEL_ACTIONS) have been relocated to
- * `@repo/elevasis-core/src/organization-model/actions.ts`.
+ * the tenant-owned organization model package.
  * Tenant OM configs supply their own action entries via `resolveOrganizationModel`.
  */
 export const DEFAULT_ORGANIZATION_MODEL_ACTIONS: z.infer<typeof ActionsDomainSchema> = {}

package/src/organization-model/domains/resources.ts

@@ -123,7 +123,7 @@ export const ResourceOntologyBindingSchema = z
     /**
      * Optional typed contract binding for this resource's workflow I/O.
      * Each ref is a `package/subpath#ExportName` string that resolves to a
-     * Zod schema in `@repo/elevasis-core` (or the consumer's equivalent package).
+     * Zod schema in the tenant-owned organization model package.
      *
      * Absence of this field preserves all existing behavior — it is additive + optional.
      * Tier-1 validation (schema.ts): ref-string shape only (browser-safe, no imports).

package/src/organization-model/domains/systems.ts

@@ -1,7 +1,6 @@
 import { z, type ZodType } from 'zod'
 import { ActionRefSchema } from './actions'
 import {
-  ColorTokenSchema,
   DescriptionSchema,
   IconNameSchema,
   LabelSchema,
@@ -156,7 +155,6 @@ export interface SystemEntry {
   status?: 'active' | 'deprecated' | 'archived'
   path?: string
   icon?: string
-  color?: string
   uiPosition?: 'sidebar-primary' | 'sidebar-bottom'
   enabled?: boolean
   devOnly?: boolean
@@ -213,8 +211,6 @@ export const SystemEntrySchema: ZodType<SystemEntry> = z
     path: PathSchema.optional(),
     /** @deprecated Use ui.icon. Kept for one-cycle Feature compatibility. */
     icon: IconNameSchema.optional(),
-    /** @deprecated Feature color token, retained for one-cycle compatibility. */
-    color: ColorTokenSchema.optional(),
     /** @deprecated UI placement hint, retained for one-cycle compatibility. */
     uiPosition: UiPositionSchema.optional(),
     /** @deprecated Use lifecycle. */

package/src/organization-model/ontology.ts

@@ -10,7 +10,7 @@ export const OntologyKindSchema = z.enum([
   'value-type',
   'property',
   'group',
-  'surface'
+  'endpoint'
 ])
 
 export type OntologyKind = z.infer<typeof OntologyKindSchema>
@@ -25,10 +25,7 @@ export const OntologyIdSchema = z
   .trim()
   .min(1)
   .max(300)
-  .regex(
-    ONTOLOGY_ID_REGEX,
-    'Ontology IDs must use <system-path>:<kind>/<local-id> or global:<kind>/<local-id>'
-  )
+  .regex(ONTOLOGY_ID_REGEX, 'Ontology IDs must use <system-path>:<kind>/<local-id> or global:<kind>/<local-id>')
 
 export type OntologyId = z.infer<typeof OntologyIdSchema>
 
@@ -56,11 +53,7 @@ export function parseOntologyId(id: string): ParsedOntologyId {
   }
 }
 
-export function formatOntologyId(input: {
-  scope: string
-  kind: OntologyKind
-  localId: string
-}): OntologyId {
+export function formatOntologyId(input: { scope: string; kind: OntologyKind; localId: string }): OntologyId {
   return OntologyIdSchema.parse(`${input.scope}:${input.kind}/${input.localId}`)
 }
 
@@ -122,7 +115,7 @@ export const OntologyGroupSchema = OntologyRecordBaseSchema.extend({
   members: OntologyReferenceListSchema
 })
 
-export const OntologySurfaceTypeSchema = OntologyRecordBaseSchema.extend({
+export const OntologyEndpointTypeSchema = OntologyRecordBaseSchema.extend({
   route: z.string().trim().min(1).max(500).optional()
 })
 
@@ -137,7 +130,7 @@ export const OntologyScopeSchema = z
     valueTypes: z.record(OntologyIdSchema, OntologyValueTypeSchema).default({}).optional(),
     sharedProperties: z.record(OntologyIdSchema, OntologySharedPropertySchema).default({}).optional(),
     groups: z.record(OntologyIdSchema, OntologyGroupSchema).default({}).optional(),
-    surfaces: z.record(OntologyIdSchema, OntologySurfaceTypeSchema).default({}).optional()
+    endpoints: z.record(OntologyIdSchema, OntologyEndpointTypeSchema).default({}).optional()
   })
   .default({})
 
@@ -175,7 +168,7 @@ export type OntologyInterfaceType = z.infer<typeof OntologyInterfaceTypeSchema>
 export type OntologyValueType = z.infer<typeof OntologyValueTypeSchema>
 export type OntologySharedProperty = z.infer<typeof OntologySharedPropertySchema>
 export type OntologyGroup = z.infer<typeof OntologyGroupSchema>
-export type OntologySurfaceType = z.infer<typeof OntologySurfaceTypeSchema>
+export type OntologyEndpointType = z.infer<typeof OntologyEndpointTypeSchema>
 export type OntologyScope = z.infer<typeof OntologyScopeSchema>
 
 export type ResolvedOntologyIndex = {
@@ -188,7 +181,7 @@ export type ResolvedOntologyIndex = {
   valueTypes: Record<OntologyId, ResolvedOntologyRecord<OntologyValueType>>
   sharedProperties: Record<OntologyId, ResolvedOntologyRecord<OntologySharedProperty>>
   groups: Record<OntologyId, ResolvedOntologyRecord<OntologyGroup>>
-  surfaces: Record<OntologyId, ResolvedOntologyRecord<OntologySurfaceType>>
+  endpoints: Record<OntologyId, ResolvedOntologyRecord<OntologyEndpointType>>
 }
 
 export type OntologyRecordOrigin = {
@@ -230,7 +223,7 @@ export type ResolvedOntologyRecordEntry = {
     | OntologyValueType
     | OntologySharedProperty
     | OntologyGroup
-    | OntologySurfaceType
+    | OntologyEndpointType
   >
 }
 
@@ -246,7 +239,7 @@ const SCOPE_KIND: Record<ScopeKey, OntologyKind> = {
   valueTypes: 'value-type',
   sharedProperties: 'property',
   groups: 'group',
-  surfaces: 'surface'
+  endpoints: 'endpoint'
 }
 
 const SCOPE_KEYS = Object.keys(SCOPE_KIND) as ScopeKey[]
@@ -347,7 +340,7 @@ function createEmptyIndex(): ResolvedOntologyIndex {
     valueTypes: {},
     sharedProperties: {},
     groups: {},
-    surfaces: {}
+    endpoints: {}
   }
 }
 
@@ -541,7 +534,9 @@ function addLegacyActionProjections(
       label: action.label,
       description: action.description,
       ownerSystemId,
-      actsOn: action.affects?.map((entityId) => (entities[entityId] ? legacyObjectId(entities[entityId]) : undefined)).filter((id): id is OntologyId => id !== undefined),
+      actsOn: action.affects
+        ?.map((entityId) => (entities[entityId] ? legacyObjectId(entities[entityId]) : undefined))
+        .filter((id): id is OntologyId => id !== undefined),
       ...(action.resourceId !== undefined ? { resourceId: action.resourceId } : {}),
       ...(action.invocations !== undefined ? { invocations: action.invocations } : {}),
       ...(action.lifecycle !== undefined ? { lifecycle: action.lifecycle } : {}),

package/src/organization-model/organization-graph.mdx

@@ -43,17 +43,18 @@ Edge kinds:
 
 - `contains`
 - `references`
-- `maps_to`
-- `uses`
-- `governs`
-- `governed-by`
-- `links`
-- `affects`
-- `emits`
+- `maps_to`
+- `uses`
+- `governs`
+- `links`
+- `affects`
+- `emits`
 - `originates_from`
 - `triggers`
 - `applies_to`
-- `effects`
+- `effects`
+
+`governed-by` is a Knowledge Graph route verb for traversing incoming `governs` edges; it is not an Organization Graph edge kind.
 
 System nodes come from the id-keyed `OrganizationModel.systems` map. Their graph IDs use `system:<id>`, such as `system:sales.crm`.
 

package/src/organization-model/published.ts

@@ -11,7 +11,7 @@ export {
   OntologyObjectTypeSchema,
   OntologyScopeSchema,
   OntologySharedPropertySchema,
-  OntologySurfaceTypeSchema,
+  OntologyEndpointTypeSchema,
   OntologyValueTypeSchema,
   compileOrganizationOntology,
   formatOntologyId,
@@ -246,7 +246,13 @@ export { defineOrganizationModel, resolveOrganizationModel, resolveOrganizationM
 export type { ResolvedSystemEntry, ResolvedOrganizationModel } from './resolve'
 export { createFoundationOrganizationModel } from './foundation'
 export { scaffoldOrganizationModel } from './scaffolders'
-export { defineDomainRecord, getClientProfile, getClientProfileBySlug, listAllSystems, listClientProfiles } from './helpers'
+export {
+  defineDomainRecord,
+  getClientProfile,
+  getClientProfileBySlug,
+  listAllSystems,
+  listClientProfiles
+} from './helpers'
 export { projectOrganizationSurfaces, validateOrganizationSurfaceProjection } from './surface-projection'
 export type {
   BaseOmScaffoldSpec,
@@ -282,7 +288,7 @@ export type {
   OntologyRecordOrigin,
   OntologyScope,
   OntologySharedProperty,
-  OntologySurfaceType,
+  OntologyEndpointType,
   OntologyValueType,
   ParsedOntologyId,
   ResolvedOntologyIndex,

package/src/organization-model/resolve.ts

@@ -79,13 +79,15 @@ function pruneFlatSystemDescendantCollisions(
 }
 
 function deepMerge<T>(base: T, override: DeepPartial<T> | undefined): T {
-  if (override === undefined) {
-    return base
-  }
-
-  if (Array.isArray(base)) {
-    return (override as T) ?? base
-  }
+  if (override === undefined) {
+    return base
+  }
+
+  // Arrays are override-replaced, not concatenated. Flattened record domains get
+  // additive-by-id object merging; see flatten-additive-merge.test.ts.
+  if (Array.isArray(base)) {
+    return (override as T) ?? base
+  }
 
   if (!isPlainObject(base) || !isPlainObject(override)) {
     return (override as T) ?? base

package/src/organization-model/scaffolders/helpers.ts

@@ -65,7 +65,7 @@ export function ontologyMapName(kind: OntologyKind): string {
     'value-type': 'valueTypes',
     property: 'sharedProperties',
     group: 'groups',
-    surface: 'surfaces'
+    endpoint: 'endpoints'
   }
   return map[kind]
 }

package/src/organization-model/scaffolders/scaffoldKnowledgeNode.ts

@@ -13,6 +13,7 @@ export function scaffoldKnowledgeNode(model: OrganizationModel, spec: KnowledgeN
   const kind = spec.kind ?? 'reference'
   const links = spec.systemPath === undefined ? '' : `links:\n  - system:${spec.systemPath}\n`
   const ownerIds = spec.ownerRoleId === undefined ? '' : `ownerIds:\n  - ${spec.ownerRoleId}\n`
+  // Non-System scaffolds only create linked projects when explicitly requested.
 
   return {
     intent: 'knowledge',

package/src/organization-model/scaffolders/scaffoldOntologyRecord.ts

@@ -2,12 +2,39 @@ import type { OrganizationModel } from '..'
 import { assertSystemExists, makeOntologyId, ontologyMapName, titleize } from './helpers'
 import type { OmScaffoldPlan, OntologyRecordScaffoldSpec } from './types'
 
+function kindSpecificFields(spec: OntologyRecordScaffoldSpec): Record<string, unknown> {
+  if (spec.kind === 'link') {
+    return {
+      from: makeOntologyId(spec.systemPath, 'object', 'source-object'),
+      to: makeOntologyId(spec.systemPath, 'object', 'target-object')
+    }
+  }
+
+  if (spec.kind === 'action') {
+    return { actsOn: [] }
+  }
+
+  if (spec.kind === 'group') {
+    return { members: [] }
+  }
+
+  return {}
+}
+
 export function scaffoldOntologyRecord(model: OrganizationModel, spec: OntologyRecordScaffoldSpec): OmScaffoldPlan {
   assertSystemExists(model, spec.systemPath)
   const localId = spec.localId ?? spec.id
   const ontologyId = makeOntologyId(spec.systemPath, spec.kind, localId)
   const label = spec.label ?? titleize(localId)
   const mapName = ontologyMapName(spec.kind)
+  const snippetRecord = {
+    id: ontologyId,
+    label,
+    ownerSystemId: spec.systemPath,
+    ...(spec.description === undefined ? {} : { description: spec.description }),
+    ...kindSpecificFields(spec)
+  }
+  // Non-System scaffolds only create linked projects when explicitly requested.
 
   return {
     intent: 'ontology',
@@ -18,12 +45,7 @@ export function scaffoldOntologyRecord(model: OrganizationModel, spec: OntologyR
       {
         path: 'packages/elevasis-core/src/organization-model/systems.ts',
         description: `Add this record under ${spec.systemPath}.ontology.${mapName}.`,
-        snippet: `${JSON.stringify(ontologyId)}: {
-  id: ${JSON.stringify(ontologyId)},
-  label: ${JSON.stringify(label)},
-  ownerSystemId: ${JSON.stringify(spec.systemPath)}${spec.description === undefined ? '' : `,
-  description: ${JSON.stringify(spec.description)}`}
-}`
+        snippet: `${JSON.stringify(ontologyId)}: ${JSON.stringify(snippetRecord, null, 2)}`
       }
     ],
     warnings: [],

package/src/organization-model/scaffolders/scaffoldResource.ts

@@ -11,6 +11,7 @@ export function scaffoldResource(model: OrganizationModel, spec: ResourceScaffol
   const label = spec.label ?? titleize(spec.id)
   const kind = spec.kind ?? 'workflow'
   const slug = slugify(spec.id)
+  // Non-System scaffolds only create linked projects when explicitly requested.
   const writes = spec.withStubWorkflow
     ? [
         {

package/src/organization-model/scaffolders/scaffoldSystem.ts

@@ -22,6 +22,7 @@ export function scaffoldSystem(model: OrganizationModel, spec: SystemScaffoldSpe
   const featureSlug = slugify(systemPath.replaceAll('.', '-'))
   const knowledgeId = `knowledge.${featureSlug}-system-overview`
   const order = nextSystemOrder(model, parentPath)
+  // Systems default to opening a linked project because they usually start a multi-file build chain.
   const withProject = spec.withProject ?? !spec.noProject
 
   const systemEntry = `  ${JSON.stringify(localId)}: {
@@ -53,7 +54,7 @@ export function scaffoldSystem(model: OrganizationModel, spec: SystemScaffoldSpe
         path: `packages/ui/src/features/${featureSlug}/manifest.stub.ts`,
         mode: 'create',
         description: 'SystemModule manifest stub. Route files are intentionally not generated.',
-        content: `import type { SystemModule } from '@repo/ui'\n\nexport const ${featureSlug.replaceAll('-', '_')}Manifest: SystemModule = {\n  systemId: ${JSON.stringify(systemPath)},\n  label: ${JSON.stringify(label)},\n  routes: []\n}\n`
+        content: `import type { SystemModule } from '@repo/ui'\n\nexport const ${featureSlug.replaceAll('-', '_')}Manifest: SystemModule = {\n  key: ${JSON.stringify(featureSlug)},\n  systemId: ${JSON.stringify(systemPath)}\n}\n`
       },
       {
         path: `packages/elevasis-core/src/knowledge/nodes/${featureSlug}-system-overview.mdx.stub`,

package/src/organization-model/schema-refinements.ts

@@ -3,8 +3,8 @@ import type { SidebarNode } from './domains/navigation'
 import { ContractRefSchema } from './domains/resources'
 import type { SystemEntry } from './domains/systems'
 import type { OmTopologyNodeRef } from './domains/topology'
-import { buildOmCrossRefIndex, knowledgeTargetExists, ONTOLOGY_REFERENCE_KEY_KINDS } from './cross-ref'
-import { compileOrganizationOntology, listResolvedOntologyRecords, type OntologyKind } from './ontology'
+import { buildOmCompilationContext, knowledgeTargetExists, ONTOLOGY_REFERENCE_KEY_KINDS } from './cross-ref'
+import { listResolvedOntologyRecords, type OntologyKind } from './ontology'
 import type { OrganizationModel } from './types'
 
 function addIssue(ctx: z.RefinementCtx, path: Array<string | number>, message: string): void {
@@ -403,10 +403,8 @@ export function refineOrganizationModel(model: OrganizationModel, ctx: z.Refinem
     })
   })
   // Shared cross-reference index — single source of truth for (kind, id) resolution.
-  const idx = buildOmCrossRefIndex(model)
+  const { crossRefIndex: idx, ontologyCompilation } = buildOmCompilationContext(model)
   const { ontologyIndexByKind, ontologyIds } = idx
-  // ontologyCompilation retained locally for listResolvedOntologyRecords and diagnostics.
-  const ontologyCompilation = compileOrganizationOntology(model)
 
   function topologyTargetExists(ref: OmTopologyNodeRef): boolean {
     if (ref.kind === 'system') return systemsById.has(ref.id)