@elevasis/core 0.18.0 → 0.20.0

package/src/organization-model/__tests__/icons.test.ts

@@ -24,4 +24,65 @@ describe('OrganizationModelIconTokenSchema', () => {
       expect(OrganizationModelIconTokenSchema.safeParse(token).success).toBe(false)
     }
   })
+
+  // max-length — CustomIconTokenSchema allows at most 80 characters
+  it('rejects custom token exceeding 80 characters', () => {
+    // 'custom.' is 7 chars; pad with 'a' so total = 81
+    const token = 'custom.' + 'a'.repeat(74)
+    expect(token.length).toBe(81)
+    expect(OrganizationModelIconTokenSchema.safeParse(token).success).toBe(false)
+  })
+
+  it('accepts custom token at exactly 80 characters', () => {
+    // 'custom.' = 7 chars, fill rest with 'a' to reach exactly 80
+    const token = 'custom.' + 'a'.repeat(73)
+    expect(token.length).toBe(80)
+    expect(OrganizationModelIconTokenSchema.safeParse(token).success).toBe(true)
+  })
+
+  // invalid charset — custom token regex only allows [a-z0-9] with [-._] separators
+  it('rejects custom token with uppercase letters in the suffix', () => {
+    expect(OrganizationModelIconTokenSchema.safeParse('custom.MyIcon').success).toBe(false)
+  })
+
+  it('rejects custom token with spaces', () => {
+    expect(OrganizationModelIconTokenSchema.safeParse('custom.my icon').success).toBe(false)
+  })
+
+  it('rejects custom token with a leading separator (double-dot)', () => {
+    expect(OrganizationModelIconTokenSchema.safeParse('custom..icon').success).toBe(false)
+  })
+
+  it('rejects custom token with a trailing separator', () => {
+    expect(OrganizationModelIconTokenSchema.safeParse('custom.icon-').success).toBe(false)
+  })
+
+  // missing prefix — tokens without the 'custom.' prefix that are not built-ins
+  it('rejects token that looks like a custom slug but lacks the custom. prefix', () => {
+    expect(OrganizationModelIconTokenSchema.safeParse('my-icon').success).toBe(false)
+    expect(OrganizationModelIconTokenSchema.safeParse('org.my-icon').success).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// OrganizationModelBuiltinIconTokenSchema — only accepts built-ins
+// ---------------------------------------------------------------------------
+
+describe('OrganizationModelBuiltinIconTokenSchema', () => {
+  it('accepts every entry in ORGANIZATION_MODEL_ICON_TOKENS', () => {
+    for (const token of ORGANIZATION_MODEL_ICON_TOKENS) {
+      expect(OrganizationModelBuiltinIconTokenSchema.safeParse(token).success).toBe(true)
+    }
+  })
+
+  it('rejects custom.* tokens (only built-ins allowed)', () => {
+    expect(OrganizationModelBuiltinIconTokenSchema.safeParse('custom.my-icon').success).toBe(false)
+    expect(OrganizationModelBuiltinIconTokenSchema.safeParse('custom.partner-portal').success).toBe(false)
+  })
+
+  it('rejects arbitrary strings not in the enum', () => {
+    expect(OrganizationModelBuiltinIconTokenSchema.safeParse('book').success).toBe(false)
+    expect(OrganizationModelBuiltinIconTokenSchema.safeParse('').success).toBe(false)
+    expect(OrganizationModelBuiltinIconTokenSchema.safeParse('nav.unknown-item').success).toBe(false)
+  })
 })

package/src/organization-model/__tests__/knowledge.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it } from 'vitest'
-import { OrgKnowledgeNodeSchema, OrgKnowledgeKindSchema, KnowledgeDomainSchema } from '../domains/knowledge'
+import {
+  OrgKnowledgeNodeSchema,
+  OrgKnowledgeKindSchema,
+  KnowledgeDomainSchema,
+  KnowledgeLinkSchema
+} from '../domains/knowledge'
 import { OrganizationGraphEdgeKindSchema } from '../graph/schema'
 import { buildOrganizationGraph } from '../graph/build'
 import { DEFAULT_ORGANIZATION_MODEL, DEFAULT_ORGANIZATION_MODEL_KNOWLEDGE } from '../defaults'
@@ -212,3 +217,115 @@ describe('buildOrganizationGraph with knowledge', () => {
     expect(defaultKnowledgeNodes).toHaveLength(0)
   })
 })
+
+// ---------------------------------------------------------------------------
+// KnowledgeLinkSchema — nodeId format validation
+// ---------------------------------------------------------------------------
+
+describe('KnowledgeLinkSchema', () => {
+  it('accepts a valid kind:dotted-path nodeId', () => {
+    expect(() => KnowledgeLinkSchema.parse({ nodeId: 'feature:sales.crm' })).not.toThrow()
+    expect(() => KnowledgeLinkSchema.parse({ nodeId: 'feature:sales.lead-gen' })).not.toThrow()
+  })
+
+  it('accepts resource: and knowledge: prefixed node IDs', () => {
+    expect(() => KnowledgeLinkSchema.parse({ nodeId: 'resource:my-resource' })).not.toThrow()
+    expect(() => KnowledgeLinkSchema.parse({ nodeId: 'knowledge:knowledge.test-doc' })).not.toThrow()
+  })
+
+  it('rejects a bare dotted ID with no kind: prefix', () => {
+    // NodeIdStringSchema requires kind:dotted-path format
+    expect(KnowledgeLinkSchema.safeParse({ nodeId: 'sales.crm' }).success).toBe(false)
+  })
+
+  it('rejects an empty nodeId', () => {
+    expect(KnowledgeLinkSchema.safeParse({ nodeId: '' }).success).toBe(false)
+  })
+
+  it('rejects a nodeId with uppercase characters', () => {
+    // NodeIdStringSchema regex requires lowercase
+    expect(KnowledgeLinkSchema.safeParse({ nodeId: 'Feature:Sales.CRM' }).success).toBe(false)
+  })
+
+  it('rejects a link missing the nodeId field', () => {
+    expect(KnowledgeLinkSchema.safeParse({}).success).toBe(false)
+  })
+
+  it('rejects a plain number as nodeId', () => {
+    expect(KnowledgeLinkSchema.safeParse({ nodeId: 123 }).success).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// OrgKnowledgeNodeSchema — field length constraints
+// ---------------------------------------------------------------------------
+
+describe('OrgKnowledgeNodeSchema length constraints', () => {
+  const BASE = {
+    id: 'knowledge.test-node',
+    kind: 'playbook',
+    title: 'Test Node',
+    summary: 'A valid summary.',
+    body: 'Body content.',
+    links: [],
+    ownerIds: [],
+    updatedAt: '2026-05-01'
+  }
+
+  it('rejects title exceeding 200 characters', () => {
+    const result = OrgKnowledgeNodeSchema.safeParse({ ...BASE, title: 'x'.repeat(201) })
+    expect(result.success).toBe(false)
+  })
+
+  it('accepts title exactly at 200 characters', () => {
+    const result = OrgKnowledgeNodeSchema.safeParse({ ...BASE, title: 'x'.repeat(200) })
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects summary exceeding 1000 characters', () => {
+    const result = OrgKnowledgeNodeSchema.safeParse({ ...BASE, summary: 'x'.repeat(1001) })
+    expect(result.success).toBe(false)
+  })
+
+  it('accepts summary exactly at 1000 characters', () => {
+    const result = OrgKnowledgeNodeSchema.safeParse({ ...BASE, summary: 'x'.repeat(1000) })
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects empty title', () => {
+    const result = OrgKnowledgeNodeSchema.safeParse({ ...BASE, title: '' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects empty summary', () => {
+    const result = OrgKnowledgeNodeSchema.safeParse({ ...BASE, summary: '' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects empty body', () => {
+    const result = OrgKnowledgeNodeSchema.safeParse({ ...BASE, body: '' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects id with uppercase characters', () => {
+    // ModelIdSchema requires lowercase kebab/dot/underscore separated IDs
+    const result = OrgKnowledgeNodeSchema.safeParse({ ...BASE, id: 'Knowledge.Test' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects id exceeding 100 characters', () => {
+    const result = OrgKnowledgeNodeSchema.safeParse({ ...BASE, id: 'knowledge.' + 'a'.repeat(95) })
+    expect(result.success).toBe(false)
+  })
+
+  it('accepts a valid custom icon token on a node', () => {
+    const result = OrgKnowledgeNodeSchema.safeParse({ ...BASE, icon: 'custom.my-icon' })
+    expect(result.success).toBe(true)
+  })
+
+  it('trims whitespace from title and summary', () => {
+    const node = OrgKnowledgeNodeSchema.parse({ ...BASE, title: '  Trimmed  ', summary: '  Summary.  ' })
+    expect(node.title).toBe('Trimmed')
+    expect(node.summary).toBe('Summary.')
+  })
+})

package/src/organization-model/__tests__/prospecting-ssot.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest'
+import { LEAD_GEN_STAGE_CATALOG } from '../domains/sales'
+import { CAPABILITY_REGISTRY, DEFAULT_ORGANIZATION_MODEL_PROSPECTING, PROSPECTING_STEPS } from '../domains/prospecting'
+
+const EXPECTED_CAPABILITY_RESOURCE_BY_ID: Record<string, string> = {
+  'lead-gen.company.source': 'lgn-import-workflow',
+  'lead-gen.company.apollo-import': 'lgn-01c-apollo-import-workflow',
+  'lead-gen.contact.discover': 'lgn-04-email-discovery-workflow',
+  'lead-gen.contact.verify-email': 'lgn-05-email-verification-workflow',
+  'lead-gen.company.website-extract': 'lgn-02-website-extract-workflow',
+  'lead-gen.company.qualify': 'lgn-03-company-qualification-workflow',
+  'lead-gen.company.dtc-subscription-qualify': 'lgn-03b-dtc-subscription-score-workflow',
+  'lead-gen.contact.apollo-decision-maker-enrich': 'lgn-04b-apollo-decision-maker-enrich-workflow',
+  'lead-gen.contact.personalize': 'ist-personalization-workflow',
+  'lead-gen.review.outreach-ready': 'ist-upload-contacts-workflow',
+  'lead-gen.export.list': 'lgn-06-export-list-workflow',
+  'lead-gen.company.cleanup': 'lgn-company-cleanup-workflow'
+}
+
+describe('prospecting organization-model SSOT', () => {
+  it('catalogs the DTC decision-maker enrichment stage', () => {
+    expect(LEAD_GEN_STAGE_CATALOG['decision-makers-enriched']).toEqual({
+      key: 'decision-makers-enriched',
+      label: 'Decision-makers found',
+      description: 'Decision-maker contacts discovered and attached to a qualified company.',
+      order: 6,
+      entity: 'company'
+    })
+  })
+
+  it('scopes prospecting steps per build template', () => {
+    expect(PROSPECTING_STEPS.localServices.findContacts).toMatchObject({
+      id: 'find-contacts',
+      primaryEntity: 'contact',
+      stageKey: 'discovered'
+    })
+    expect(PROSPECTING_STEPS.dtcApolloClickup.enrichDecisionMakers).toMatchObject({
+      id: 'enrich-decision-makers',
+      primaryEntity: 'company',
+      stageKey: 'decision-makers-enriched'
+    })
+  })
+
+  it('uses catalog stage keys for every prospecting step', () => {
+    const catalogKeys = new Set(Object.keys(LEAD_GEN_STAGE_CATALOG))
+
+    for (const templateSteps of Object.values(PROSPECTING_STEPS)) {
+      for (const step of Object.values(templateSteps)) {
+        expect(catalogKeys.has(step.stageKey), step.id).toBe(true)
+      }
+    }
+  })
+
+  it('uses registered capabilities for every prospecting step', () => {
+    const capabilityKeys = new Set(CAPABILITY_REGISTRY.map((c) => c.id))
+
+    for (const templateSteps of Object.values(PROSPECTING_STEPS)) {
+      for (const step of Object.values(templateSteps)) {
+        expect(capabilityKeys.has(step.capabilityKey), step.id).toBe(true)
+      }
+    }
+  })
+
+  it('derives prospecting lifecycle stages from the stage catalog by entity', () => {
+    const expectedCompanyStages = Object.values(LEAD_GEN_STAGE_CATALOG)
+      .filter((stage) => stage.entity === 'company')
+      .sort((a, b) => a.order - b.order)
+      .map(({ key, label, order }) => ({ id: key, label, order }))
+
+    const expectedContactStages = Object.values(LEAD_GEN_STAGE_CATALOG)
+      .filter((stage) => stage.entity === 'contact')
+      .sort((a, b) => a.order - b.order)
+      .map(({ key, label, order }) => ({ id: key, label, order }))
+
+    expect(DEFAULT_ORGANIZATION_MODEL_PROSPECTING.companyStages).toEqual(expectedCompanyStages)
+    expect(DEFAULT_ORGANIZATION_MODEL_PROSPECTING.contactStages).toEqual(expectedContactStages)
+  })
+
+  it('build templates reference PROSPECTING_STEPS entries', () => {
+    const [localServices, dtcApolloClickup] = DEFAULT_ORGANIZATION_MODEL_PROSPECTING.buildTemplates
+
+    expect(localServices?.steps).toEqual(Object.values(PROSPECTING_STEPS.localServices))
+    expect(dtcApolloClickup?.steps).toEqual(Object.values(PROSPECTING_STEPS.dtcApolloClickup))
+  })
+
+  it('covers all known lead-gen capability registry entries', () => {
+    expect(CAPABILITY_REGISTRY).toHaveLength(12)
+    const actualResourceById = Object.fromEntries(CAPABILITY_REGISTRY.map((c) => [c.id, c.resourceId]))
+    expect(actualResourceById).toEqual(EXPECTED_CAPABILITY_RESOURCE_BY_ID)
+  })
+})

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

@@ -14,6 +14,20 @@ function makeFeature(id: string, path = `/${id.replaceAll('.', '/')}`) {
   }
 }
 
+function makeSurface(id: string, featureId?: string, featureIds: string[] = []) {
+  return {
+    id,
+    label: id,
+    path: `/${id.replaceAll('.', '/')}`,
+    surfaceType: 'page' as const,
+    featureId,
+    featureIds,
+    entityIds: [],
+    resourceIds: [],
+    capabilityIds: []
+  }
+}
+
 function makeMinimalModel(features: unknown[] = []) {
   return {
     version: 1 as const,
@@ -48,6 +62,22 @@ describe('flat feature tree validation', () => {
     expect(messages.some((message) => message.includes('Feature id "sales" must be unique'))).toBe(true)
   })
 
+  it('rejects duplicate effective feature paths when explicit and default paths collide', () => {
+    const messages = getIssueMessages(
+      makeMinimalModel([
+        { id: 'sales', label: 'Sales', enabled: true },
+        makeFeature('sales.crm', '/sales/lead-gen'),
+        { id: 'sales.lead-gen', label: 'Lead Gen', enabled: true }
+      ])
+    )
+
+    expect(
+      messages.some((message) =>
+        message.includes('Feature "sales.lead-gen" effective path "/sales/lead-gen" duplicates feature "sales.crm"')
+      )
+    ).toBe(true)
+  })
+
   it('rejects a dotted child when its immediate parent is missing', () => {
     const messages = getIssueMessages(makeMinimalModel([makeFeature('sales.crm.pipeline')]))
 
@@ -80,4 +110,96 @@ describe('flat feature tree validation', () => {
     expect(model.navigation.groups).toEqual([])
     expect('resourceMappings' in model).toBe(false)
   })
+
+  it('rejects an unknown navigation default surface when surfaces are explicitly empty', () => {
+    const messages = getIssueMessages({
+      ...makeMinimalModel([makeFeature('dashboard', '/')]),
+      navigation: {
+        defaultSurfaceId: 'missing.surface',
+        surfaces: [],
+        groups: []
+      }
+    })
+
+    expect(
+      messages.some((message) =>
+        message.includes('Navigation defaultSurfaceId references unknown surface "missing.surface"')
+      )
+    ).toBe(true)
+  })
+
+  it('rejects navigation group surfaceIds that reference missing surfaces', () => {
+    const messages = getIssueMessages({
+      ...makeMinimalModel([makeFeature('dashboard', '/')]),
+      navigation: {
+        surfaces: [makeSurface('dashboard.home', 'dashboard')],
+        groups: [
+          {
+            id: 'primary',
+            label: 'Primary',
+            placement: 'primary',
+            surfaceIds: ['missing.surface']
+          }
+        ]
+      }
+    })
+
+    expect(
+      messages.some((message) =>
+        message.includes('Navigation group "primary" references unknown surface "missing.surface"')
+      )
+    ).toBe(true)
+  })
+
+  it('rejects navigation surface featureId references to missing features', () => {
+    const messages = getIssueMessages({
+      ...makeMinimalModel([makeFeature('dashboard', '/')]),
+      navigation: {
+        surfaces: [makeSurface('dashboard.home', 'missing.feature')],
+        groups: []
+      }
+    })
+
+    expect(
+      messages.some((message) =>
+        message.includes('Navigation surface "dashboard.home" references unknown feature "missing.feature"')
+      )
+    ).toBe(true)
+  })
+
+  it('rejects navigation surface featureIds references to missing features', () => {
+    const messages = getIssueMessages({
+      ...makeMinimalModel([makeFeature('dashboard', '/')]),
+      navigation: {
+        surfaces: [makeSurface('dashboard.home', 'dashboard', ['dashboard', 'missing.feature'])],
+        groups: []
+      }
+    })
+
+    expect(
+      messages.some((message) =>
+        message.includes('Navigation surface "dashboard.home" references unknown feature "missing.feature"')
+      )
+    ).toBe(true)
+  })
+
+  it('allows legacy navigation feature aliases when canonical features exist', () => {
+    const result = OrganizationModelSchema.safeParse({
+      ...makeMinimalModel([
+        { id: 'sales', label: 'Sales', enabled: true },
+        makeFeature('sales.crm', '/sales/crm/pipeline'),
+        makeFeature('sales.lead-gen', '/lead-gen/lists')
+      ]),
+      navigation: {
+        defaultSurfaceId: 'crm.pipeline',
+        surfaces: [
+          makeSurface('crm.pipeline', 'crm', ['crm']),
+          makeSurface('lead-gen.lists', 'lead-gen', ['lead-gen'])
+        ],
+        groups: []
+      }
+    })
+
+    expect(result.success).toBe(true)
+  })
 })

package/src/organization-model/__tests__/surface-projection.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, it } from 'vitest'
+import { DEFAULT_ORGANIZATION_MODEL } from '../defaults'
+import {
+  projectOrganizationSurfaces,
+  validateOrganizationSurfaceProjection
+} from '../surface-projection'
+import type { OrganizationModel, OrganizationModelFeature, OrganizationModelSurface } from '../types'
+
+function makeFeature(
+  id: string,
+  overrides: Partial<OrganizationModelFeature> = {}
+): OrganizationModelFeature {
+  return {
+    id,
+    label: id,
+    enabled: true,
+    ...overrides
+  }
+}
+
+function makeSurface(
+  id: string,
+  overrides: Partial<OrganizationModelSurface> = {}
+): OrganizationModelSurface {
+  return {
+    id,
+    label: id,
+    path: `/${id.replaceAll('.', '/')}`,
+    surfaceType: 'page',
+    enabled: true,
+    featureIds: [],
+    entityIds: [],
+    resourceIds: [],
+    capabilityIds: [],
+    ...overrides
+  }
+}
+
+function makeModel(
+  features: OrganizationModelFeature[],
+  surfaces: OrganizationModelSurface[],
+  navigation: Partial<OrganizationModel['navigation']> = {}
+): OrganizationModel {
+  return {
+    ...DEFAULT_ORGANIZATION_MODEL,
+    features,
+    navigation: {
+      surfaces,
+      groups: [],
+      ...navigation
+    }
+  }
+}
+
+describe('projectOrganizationSurfaces', () => {
+  it('projects navigation surfaces into data-only DTOs with inherited flags', () => {
+    const model = makeModel(
+      [
+        makeFeature('sales', { requiresAdmin: true }),
+        makeFeature('sales.crm', { devOnly: true })
+      ],
+      [
+        makeSurface('crm.pipeline', {
+          label: 'Pipeline',
+          path: '/crm/pipeline',
+          surfaceType: 'graph',
+          featureId: 'sales.crm',
+          featureIds: ['sales.crm'],
+          entityIds: ['crm.deal'],
+          resourceIds: ['workflow.crm-sync'],
+          capabilityIds: ['crm.pipeline.manage']
+        })
+      ]
+    )
+
+    expect(projectOrganizationSurfaces(model)).toEqual([
+      {
+        id: 'crm.pipeline',
+        label: 'Pipeline',
+        path: '/crm/pipeline',
+        surfaceType: 'graph',
+        featureId: 'sales.crm',
+        featureIds: ['sales.crm'],
+        entityIds: ['crm.deal'],
+        resourceIds: ['workflow.crm-sync'],
+        capabilityIds: ['crm.pipeline.manage'],
+        enabled: true,
+        devOnly: true,
+        requiresAdmin: true
+      }
+    ])
+  })
+
+  it('canonicalizes legacy feature aliases', () => {
+    const model = makeModel(
+      [
+        makeFeature('sales'),
+        makeFeature('sales.crm'),
+        makeFeature('sales.lead-gen'),
+        makeFeature('monitoring'),
+        makeFeature('monitoring.submitted-requests')
+      ],
+      [
+        makeSurface('legacy.sales', {
+          featureId: 'crm',
+          featureIds: ['crm', 'lead-gen', 'submitted-requests']
+        })
+      ]
+    )
+
+    expect(projectOrganizationSurfaces(model)[0]).toMatchObject({
+      featureId: 'sales.crm',
+      featureIds: ['sales.crm', 'sales.lead-gen', 'monitoring.submitted-requests']
+    })
+  })
+
+  it('disables projected surfaces when feature lineage is disabled', () => {
+    const model = makeModel(
+      [
+        makeFeature('sales', { enabled: false }),
+        makeFeature('sales.crm')
+      ],
+      [
+        makeSurface('crm.pipeline', {
+          enabled: true,
+          featureId: 'sales.crm',
+          featureIds: ['sales.crm']
+        })
+      ]
+    )
+
+    expect(projectOrganizationSurfaces(model)[0].enabled).toBe(false)
+  })
+})
+
+describe('validateOrganizationSurfaceProjection', () => {
+  it('returns issue codes for duplicate and unknown surface references', () => {
+    const model = makeModel(
+      [makeFeature('sales'), makeFeature('sales.crm')],
+      [
+        makeSurface('crm.pipeline', {
+          path: '/crm/pipeline',
+          featureId: 'sales.crm',
+          featureIds: ['sales.crm']
+        }),
+        makeSurface('crm.pipeline', {
+          path: '/crm/pipeline/',
+          featureId: 'missing.primary',
+          featureIds: ['missing.related']
+        })
+      ],
+      {
+        defaultSurfaceId: 'missing.default',
+        groups: [
+          {
+            id: 'primary',
+            label: 'Primary',
+            placement: 'primary',
+            surfaceIds: ['missing.group']
+          }
+        ]
+      }
+    )
+
+    expect(validateOrganizationSurfaceProjection(model).map((issue) => issue.code)).toEqual([
+      'duplicate-surface-id',
+      'duplicate-surface-path',
+      'unknown-surface-feature',
+      'unknown-surface-feature-reference',
+      'unknown-default-surface',
+      'unknown-group-surface'
+    ])
+  })
+})

package/src/organization-model/defaults.ts

@@ -150,6 +150,14 @@ export const DEFAULT_ORGANIZATION_MODEL: OrganizationModel = {
       enabled: true,
       uiPosition: 'sidebar-primary'
     },
+    {
+      id: 'monitoring.calendar',
+      label: 'Calendar',
+      description: 'Google Calendar events and agenda views',
+      enabled: true,
+      path: '/monitoring/calendar',
+      icon: 'feature.calendar'
+    },
     {
       id: 'monitoring.activity-log',
       label: 'Activity Log',

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

@@ -12,6 +12,9 @@ export const KnowledgeLinkSchema = z.object({
   nodeId: NodeIdStringSchema
 })
 
+export const KnowledgeSkillBindingSchema = z.string().trim().min(1).max(120)
+export const KnowledgeDomainBindingSchema = z.string().trim().min(1).max(80)
+
 // ---------------------------------------------------------------------------
 // OrgKnowledgeNode — single schema, `kind` discriminator drives presentation.
 // Phase 1: body is raw MDX string (lossless migration from operations/ docs).
@@ -33,6 +36,10 @@ export const OrgKnowledgeNodeSchema = z.object({
    * Each link emits a `governs` edge: knowledge-node -> target node.
    */
   links: z.array(KnowledgeLinkSchema).default([]),
+  /** Operator skill or command bindings relevant to this node. */
+  skills: z.array(KnowledgeSkillBindingSchema).optional(),
+  /** Domain key used to derive fast graph->skill registries. */
+  domain: KnowledgeDomainBindingSchema.optional(),
   /** Identifiers of the roles or members who own this knowledge node. */
   ownerIds: z.array(ModelIdSchema).default([]),
   /** ISO date string (YYYY-MM-DD or full ISO 8601) of last meaningful update. */
@@ -50,4 +57,6 @@ export const KnowledgeDomainSchema = z.object({
 export type OrgKnowledgeNode = z.infer<typeof OrgKnowledgeNodeSchema>
 export type OrgKnowledgeKind = z.infer<typeof OrgKnowledgeKindSchema>
 export type KnowledgeLink = z.infer<typeof KnowledgeLinkSchema>
+export type KnowledgeSkillBinding = z.infer<typeof KnowledgeSkillBindingSchema>
+export type KnowledgeDomainBinding = z.infer<typeof KnowledgeDomainBindingSchema>
 export type KnowledgeDomain = z.infer<typeof KnowledgeDomainSchema>