@elevasis/core 0.45.0 → 0.46.0

package/dist/knowledge/index.d.ts

@@ -1597,22 +1597,24 @@ declare function listAllResources(model: OrganizationModel): NonNullable<Organiz
  */
 declare function listAllRoles(model: OrganizationModel): NonNullable<OrganizationModel['roles']>[string][];
 /** The recognized mount axes for Knowledge Map paths. */
-type KnowledgeMount = 'by-system' | 'by-ontology' | 'by-kind' | 'by-owner' | 'graph' | 'node' | 'all-systems' | 'all-resources' | 'all-roles';
+type KnowledgeMount = 'by-system' | 'by-ontology' | 'by-kind' | 'by-owner' | 'graph' | 'node' | 'all-systems' | 'all-resources' | 'all-roles' | 'by-domain' | 'by-item';
 /**
  * The result of parsing a Knowledge Map path string.
  *
  * Shape: `{ mount: KnowledgeMount, args: string[] }`
  *
  * Per-mount arg arrays:
- * - `by-system`:    `[systemId]`   (e.g. `['sales.crm']`)
- * - `by-ontology`:  `[ontologyId]` (e.g. `['sales.crm:object/deal']`)
- * - `by-kind`:      `[kind]`       (e.g. `['playbook']`)
- * - `by-owner`:     `[ownerId]`    (e.g. `['role.ops-lead']`)
- * - `graph`:        `[nodeId, verb]` where verb is `'governs'` or `'governed-by'`
- * - `node`:         `[nodeId]`     (single node lookup, no sub-path)
- * - `all-systems`:  `[]`           (no args — returns all systems flattened)
- * - `all-resources`:`[]`           (no args — returns all resources)
- * - `all-roles`:    `[]`           (no args — returns all roles)
+ * - `by-system`:    `[systemId]`      (e.g. `['sales.crm']`)
+ * - `by-ontology`:  `[ontologyId]`    (e.g. `['sales.crm:object/deal']`)
+ * - `by-kind`:      `[kind]`          (e.g. `['playbook']`)
+ * - `by-owner`:     `[ownerId]`       (e.g. `['role.ops-lead']`)
+ * - `graph`:        `[nodeId, verb]`  where verb is `'governs'` or `'governed-by'`
+ * - `node`:         `[nodeId]`        (single node lookup, no sub-path)
+ * - `all-systems`:  `[]`              (no args — returns all systems flattened)
+ * - `all-resources`:`[]`              (no args — returns all resources)
+ * - `all-roles`:    `[]`              (no args — returns all roles)
+ * - `by-domain`:    `[domain]`        (e.g. `['clients']`) — enumerate all items in domain
+ * - `by-item`:      `[domain, itemId]` (e.g. `['clients', '<uuid>']`) — single domain-item
  */
 interface ParsedKnowledgePath {
     mount: KnowledgeMount;
@@ -1632,6 +1634,8 @@ interface ParsedKnowledgePath {
  *   `/all-systems`                    -> `{ mount: ‘all-systems’,  args: [] }`
  *   `/all-resources`                  -> `{ mount: ‘all-resources’,args: [] }`
  *   `/all-roles`                      -> `{ mount: ‘all-roles’,    args: [] }`
+ *   `/by-domain/<domain>`             -> `{ mount: ‘by-domain’,    args: [‘<domain>’] }`
+ *   `/by-item/<domain>/<itemId>`      -> `{ mount: ‘by-item’,      args: [‘<domain>’, ‘<itemId>’] }`
  *
  * The path MUST start with `/`.  Trailing slashes are stripped before parsing.
  *

package/dist/knowledge/index.js

@@ -101,6 +101,7 @@ function getSystem(model, path) {
 }
 
 // src/knowledge/queries.ts
+var DOMAIN_ITEM_KINDS = ["clients", "roles", "policies", "customers", "offerings", "goals"];
 function toGraphNodeId(omNodeId) {
   return `knowledge:${omNodeId}`;
 }
@@ -224,11 +225,32 @@ function parsePath(pathString) {
   if (first === "all-roles" && rest.length === 0) {
     return { mount: "all-roles", args: [] };
   }
+  if (first === "by-domain") {
+    if (rest.length === 0) {
+      throw new Error(`parsePath: /by-domain requires a domain argument, got: "${pathString}"`);
+    }
+    const domain = rest[0];
+    if (!DOMAIN_ITEM_KINDS.includes(domain)) {
+      throw new Error(`parsePath: /by-domain unknown domain "${domain}". Supported: ${DOMAIN_ITEM_KINDS.join(", ")}`);
+    }
+    return { mount: "by-domain", args: [domain] };
+  }
+  if (first === "by-item") {
+    if (rest.length < 2) {
+      throw new Error(`parsePath: /by-item requires <domain>/<itemId>, got: "${pathString}"`);
+    }
+    const domain = rest[0];
+    if (!DOMAIN_ITEM_KINDS.includes(domain)) {
+      throw new Error(`parsePath: /by-item unknown domain "${domain}". Supported: ${DOMAIN_ITEM_KINDS.join(", ")}`);
+    }
+    const itemId = rest.slice(1).join("/");
+    return { mount: "by-item", args: [domain, itemId] };
+  }
   if (segments.length === 1) {
     return { mount: "node", args: [first] };
   }
   throw new Error(
-    `parsePath: unrecognized path pattern "${pathString}". Supported: /by-system/<id>, /by-kind/<kind>, /by-owner/<id>, /graph/<nodeId>/governs, /graph/<nodeId>/governed-by, /<nodeId>, /all-systems, /all-resources, /all-roles`
+    `parsePath: unrecognized path pattern "${pathString}". Supported: /by-system/<id>, /by-kind/<kind>, /by-owner/<id>, /by-domain/<domain>, /by-item/<domain>/<itemId>, /graph/<nodeId>/governs, /graph/<nodeId>/governed-by, /<nodeId>, /all-systems, /all-resources, /all-roles`
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/core",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "license": "MIT",
   "description": "Minimal shared constants across Elevasis monorepo",
   "sideEffects": false,

package/src/knowledge/__tests__/queries.test.ts

@@ -1097,3 +1097,177 @@ describe('formatOmDescribe', () => {
     expect(output).toContain('System: sales.lead-gen')
   })
 })
+
+// ---------------------------------------------------------------------------
+// Domain-item resolution (item:<domain>:<id> + bare-id back-compat)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fixture exercising all six graph-projected domain-item kinds.
+ * `knowledge.brand-guide` governs the client via a `client:client-1` link.
+ */
+const DOMAIN_ITEM_MODEL = {
+  knowledge: {
+    'knowledge.brand-guide': {
+      id: 'knowledge.brand-guide',
+      kind: 'reference',
+      title: 'Brand Guide',
+      summary: 'Branding rules for the client.',
+      body: '## Brand Guide\n\nVoice and palette.',
+      links: [{ nodeId: 'client:client-1' }],
+      ownerIds: [],
+      updatedAt: '2026-01-01'
+    }
+  },
+  clients: {
+    'client-1': {
+      id: 'client-1',
+      name: 'Byron for Irvine',
+      organizationName: 'Byron for Irvine Campaign',
+      shortName: 'Byron',
+      clientBrief: 'Local city-council campaign.',
+      candidateName: 'Byron'
+    }
+  },
+  roles: {
+    'role.ops-lead': {
+      id: 'role.ops-lead',
+      order: 10,
+      title: 'Ops Lead',
+      responsibilities: ['Run operations.'],
+      responsibleFor: []
+    }
+  },
+  policies: {
+    'policy.review-spend': {
+      id: 'policy.review-spend',
+      order: 10,
+      label: 'Review Spend',
+      description: 'Review spend over threshold.'
+    }
+  },
+  customers: {
+    'cust-1': {
+      id: 'cust-1',
+      name: 'SMB Automation Segment',
+      description: 'Small businesses adopting automation.'
+    }
+  },
+  offerings: {
+    'off-1': {
+      id: 'off-1',
+      name: 'Automation Starter Package',
+      description: 'Entry automation engagement.'
+    }
+  },
+  goals: {
+    'goal-1': {
+      id: 'goal-1',
+      description: 'Double recurring revenue this year.'
+    }
+  }
+} as unknown as OrganizationModel
+
+describe('omDescribe — domain items', () => {
+  it('resolves item:clients:<id> to the full client profile + location + governing knowledge', () => {
+    const result = omDescribe(DOMAIN_ITEM_MODEL, 'item:clients:client-1')
+    expect(result).toBeDefined()
+    if (!result || result.kind !== 'domain-item') throw new Error('expected domain-item result')
+    expect(result.domain).toBe('clients')
+    expect(result.id).toBe('item:clients:client-1')
+    expect(result.name).toBe('Byron for Irvine')
+    // Full ClientProfile payload is carried in `record`.
+    expect(result.record).toMatchObject({
+      organizationName: 'Byron for Irvine Campaign',
+      candidateName: 'Byron'
+    })
+    // Location.
+    expect(result.location.domainLabel).toBe('Clients')
+    expect(result.location.graphNodeId).toBe('client:client-1')
+    expect(result.location.containsParentIds).toContain('organization-model')
+    // Governing knowledge.
+    expect(result.governingKnowledge.map((g) => g.id)).toContain('knowledge.brand-guide')
+  })
+
+  it('resolves bare client:<id> identically to the item: form (back-compat)', () => {
+    const bare = omDescribe(DOMAIN_ITEM_MODEL, 'client:client-1')
+    const canonical = omDescribe(DOMAIN_ITEM_MODEL, 'item:clients:client-1')
+    expect(bare).toEqual(canonical)
+  })
+
+  it('resolves the other five domain kinds via item: and bare ids', () => {
+    const cases: Array<{ item: string; bare: string; domain: string; name: string }> = [
+      { item: 'item:roles:role.ops-lead', bare: 'role:role.ops-lead', domain: 'roles', name: 'Ops Lead' },
+      {
+        item: 'item:policies:policy.review-spend',
+        bare: 'policy:policy.review-spend',
+        domain: 'policies',
+        name: 'Review Spend'
+      },
+      { item: 'item:customers:cust-1', bare: 'customer:cust-1', domain: 'customers', name: 'SMB Automation Segment' },
+      { item: 'item:offerings:off-1', bare: 'offering:off-1', domain: 'offerings', name: 'Automation Starter Package' },
+      { item: 'item:goals:goal-1', bare: 'goal:goal-1', domain: 'goals', name: 'Double recurring revenue this year.' }
+    ]
+    for (const c of cases) {
+      const viaItem = omDescribe(DOMAIN_ITEM_MODEL, c.item)
+      expect(viaItem, `item form ${c.item}`).toBeDefined()
+      if (!viaItem || viaItem.kind !== 'domain-item') throw new Error(`expected domain-item for ${c.item}`)
+      expect(viaItem.domain).toBe(c.domain)
+      expect(viaItem.name).toBe(c.name)
+      // Bare form resolves to the same result.
+      expect(omDescribe(DOMAIN_ITEM_MODEL, c.bare)).toEqual(viaItem)
+    }
+  })
+
+  it('returns undefined for an unknown item id', () => {
+    expect(omDescribe(DOMAIN_ITEM_MODEL, 'item:clients:does-not-exist')).toBeUndefined()
+    expect(omDescribe(DOMAIN_ITEM_MODEL, 'client:does-not-exist')).toBeUndefined()
+  })
+
+  it('returns undefined for an item ref with an unknown domain', () => {
+    expect(omDescribe(DOMAIN_ITEM_MODEL, 'item:widgets:thing-1')).toBeUndefined()
+  })
+})
+
+describe('parsePath — domain-item mounts', () => {
+  it('parses /by-domain/<domain> into a by-domain mount', () => {
+    expect(parsePath('/by-domain/clients')).toEqual({ mount: 'by-domain', args: ['clients'] })
+  })
+
+  it('parses /by-item/<domain>/<itemId> into a by-item mount', () => {
+    expect(parsePath('/by-item/clients/client-1')).toEqual({ mount: 'by-item', args: ['clients', 'client-1'] })
+  })
+
+  it('throws on an unknown domain for /by-domain', () => {
+    expect(() => parsePath('/by-domain/widgets')).toThrow(/unknown domain/i)
+  })
+
+  it('throws on an unknown domain for /by-item', () => {
+    expect(() => parsePath('/by-item/widgets/thing-1')).toThrow(/unknown domain/i)
+  })
+
+  it('throws when /by-item is missing the itemId', () => {
+    expect(() => parsePath('/by-item/clients')).toThrow(/by-item/i)
+  })
+})
+
+describe('formatOmDescribe — domain items', () => {
+  it('renders a domain-item header, location, record, and governing knowledge', () => {
+    const result = omDescribe(DOMAIN_ITEM_MODEL, 'item:clients:client-1')
+    const output = formatOmDescribe(result)
+    expect(output).toContain('Domain Item: item:clients:client-1')
+    expect(output).toContain('Domain: Clients')
+    expect(output).toContain('Name: Byron for Irvine')
+    expect(output).toContain('Graph node: client:client-1')
+    expect(output).toContain('Governing knowledge:')
+    expect(output).toContain('knowledge.brand-guide')
+  })
+
+  it('serializes the domain-item result directly via JSON.stringify', () => {
+    const result = omDescribe(DOMAIN_ITEM_MODEL, 'item:clients:client-1')
+    const json = JSON.parse(JSON.stringify(result))
+    expect(json.kind).toBe('domain-item')
+    expect(json.domain).toBe('clients')
+    expect(json.id).toBe('item:clients:client-1')
+  })
+})

package/src/knowledge/format.ts

@@ -1,6 +1,7 @@
 import type { OrgKnowledgeNode } from '../organization-model/domains/knowledge'
 import type {
   KnowledgeMount,
+  OmDescribeDomainItem,
   OmDescribeKnowledge,
   OmDescribeOntology,
   OmDescribePolicy,
@@ -170,6 +171,8 @@ export function formatOmDescribe(result: OmDescribeResult | undefined): string {
       return formatRoleDescribe(result)
     case 'policy':
       return formatPolicyDescribe(result)
+    case 'domain-item':
+      return formatDomainItemDescribe(result)
   }
 }
 
@@ -320,3 +323,39 @@ function formatPolicyDescribe(r: OmDescribePolicy): string {
 
   return join([header, effectSection, appliesSection])
 }
+
+function formatDomainItemDescribe(r: OmDescribeDomainItem): string {
+  const header = join([
+    `Domain Item: ${r.id}`,
+    [
+      field('Domain', r.location.domainLabel),
+      field('Name', r.name),
+      field('Graph node', r.location.graphNodeId),
+      field('Parent nodes', r.location.containsParentIds.join(', '))
+    ]
+      .filter((s) => s.length > 0)
+      .join('\n')
+  ])
+
+  // Key record fields — emit a compact subset of the record payload.
+  const recordLines: string[] = []
+  for (const [k, v] of Object.entries(r.record)) {
+    if (v === undefined || v === null) continue
+    if (typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 0) continue
+    const display = Array.isArray(v)
+      ? v.length === 0
+        ? null
+        : `[${(v as unknown[]).slice(0, 5).join(', ')}${v.length > 5 ? `, ...+${v.length - 5}` : ''}]`
+      : typeof v === 'object'
+        ? JSON.stringify(v).slice(0, 120)
+        : String(v)
+    if (display === null) continue
+    recordLines.push(`  ${k}: ${display}`)
+  }
+  const recordSection = recordLines.length ? `Record:\n${recordLines.join('\n')}` : ''
+
+  const govLines = r.governingKnowledge.map((g) => `  - ${g.id} [${g.knowledgeKind}] ${g.title}`)
+  const govSection = govLines.length ? `Governing knowledge:\n${govLines.join('\n')}` : 'Governing knowledge:\n  (none)'
+
+  return join([header, recordSection, govSection])
+}

package/src/knowledge/index.ts

@@ -10,7 +10,8 @@ export {
   omDescribe,
   listAllSystemsFlat,
   listAllResources,
-  listAllRoles
+  listAllRoles,
+  DOMAIN_ITEM_KINDS
 } from './queries'
 export type {
   KnowledgeMount,
@@ -24,7 +25,11 @@ export type {
   OmDescribeKnowledge,
   OmDescribeOntology,
   OmDescribeRole,
-  OmDescribePolicy
+  OmDescribePolicy,
+  OmDescribeDomainItem,
+  OmDescribeDomainItemLocation,
+  OmDescribeDomainItemKnowledgeRef,
+  DomainItemKind
 } from './queries'
 
 export { formatText, formatJson, formatIdsOnly, formatOmSearchHits, formatOmDescribe } from './format'

package/src/knowledge/queries.ts

@@ -4,6 +4,30 @@ import { OntologyIdSchema, ontologyGraphNodeId } from '../organization-model/ont
 import type { OrganizationModel } from '../organization-model/types'
 import { listAllSystems } from '../organization-model/helpers'
 
+// ---------------------------------------------------------------------------
+// Domain-item constants
+// ---------------------------------------------------------------------------
+
+/**
+ * The six graph-projected domain-item kinds supported by `omDescribe`.
+ * Each maps to a collection on `OrganizationModel` and a graph node kind.
+ */
+export const DOMAIN_ITEM_KINDS = ['clients', 'roles', 'policies', 'customers', 'offerings', 'goals'] as const
+export type DomainItemKind = (typeof DOMAIN_ITEM_KINDS)[number]
+
+/**
+ * Bare-id prefix to domain map used for back-compat resolution.
+ * e.g. `client:<uuid>` → `clients`
+ */
+const BARE_PREFIX_TO_DOMAIN: Record<string, DomainItemKind> = {
+  client: 'clients',
+  role: 'roles',
+  policy: 'policies',
+  customer: 'customers',
+  offering: 'offerings',
+  goal: 'goals'
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -265,6 +289,8 @@ export type KnowledgeMount =
   | 'all-systems'
   | 'all-resources'
   | 'all-roles'
+  | 'by-domain'
+  | 'by-item'
 
 /**
  * The result of parsing a Knowledge Map path string.
@@ -272,15 +298,17 @@ export type KnowledgeMount =
  * Shape: `{ mount: KnowledgeMount, args: string[] }`
  *
  * Per-mount arg arrays:
- * - `by-system`:    `[systemId]`   (e.g. `['sales.crm']`)
- * - `by-ontology`:  `[ontologyId]` (e.g. `['sales.crm:object/deal']`)
- * - `by-kind`:      `[kind]`       (e.g. `['playbook']`)
- * - `by-owner`:     `[ownerId]`    (e.g. `['role.ops-lead']`)
- * - `graph`:        `[nodeId, verb]` where verb is `'governs'` or `'governed-by'`
- * - `node`:         `[nodeId]`     (single node lookup, no sub-path)
- * - `all-systems`:  `[]`           (no args — returns all systems flattened)
- * - `all-resources`:`[]`           (no args — returns all resources)
- * - `all-roles`:    `[]`           (no args — returns all roles)
+ * - `by-system`:    `[systemId]`      (e.g. `['sales.crm']`)
+ * - `by-ontology`:  `[ontologyId]`    (e.g. `['sales.crm:object/deal']`)
+ * - `by-kind`:      `[kind]`          (e.g. `['playbook']`)
+ * - `by-owner`:     `[ownerId]`       (e.g. `['role.ops-lead']`)
+ * - `graph`:        `[nodeId, verb]`  where verb is `'governs'` or `'governed-by'`
+ * - `node`:         `[nodeId]`        (single node lookup, no sub-path)
+ * - `all-systems`:  `[]`              (no args — returns all systems flattened)
+ * - `all-resources`:`[]`              (no args — returns all resources)
+ * - `all-roles`:    `[]`              (no args — returns all roles)
+ * - `by-domain`:    `[domain]`        (e.g. `['clients']`) — enumerate all items in domain
+ * - `by-item`:      `[domain, itemId]` (e.g. `['clients', '<uuid>']`) — single domain-item
  */
 export interface ParsedKnowledgePath {
   mount: KnowledgeMount
@@ -301,6 +329,8 @@ export interface ParsedKnowledgePath {
  *   `/all-systems`                    -> `{ mount: ‘all-systems’,  args: [] }`
  *   `/all-resources`                  -> `{ mount: ‘all-resources’,args: [] }`
  *   `/all-roles`                      -> `{ mount: ‘all-roles’,    args: [] }`
+ *   `/by-domain/<domain>`             -> `{ mount: ‘by-domain’,    args: [‘<domain>’] }`
+ *   `/by-item/<domain>/<itemId>`      -> `{ mount: ‘by-item’,      args: [‘<domain>’, ‘<itemId>’] }`
  *
  * The path MUST start with `/`.  Trailing slashes are stripped before parsing.
  *
@@ -384,6 +414,31 @@ export function parsePath(pathString: string): ParsedKnowledgePath {
     return { mount: 'all-roles', args: [] }
   }
 
+  // /by-domain/<domain>  — enumerate all items in a domain
+  if (first === 'by-domain') {
+    if (rest.length === 0) {
+      throw new Error(`parsePath: /by-domain requires a domain argument, got: "${pathString}"`)
+    }
+    const domain = rest[0]
+    if (!(DOMAIN_ITEM_KINDS as readonly string[]).includes(domain)) {
+      throw new Error(`parsePath: /by-domain unknown domain "${domain}". Supported: ${DOMAIN_ITEM_KINDS.join(', ')}`)
+    }
+    return { mount: 'by-domain', args: [domain] }
+  }
+
+  // /by-item/<domain>/<itemId>  — single domain-item resolution
+  if (first === 'by-item') {
+    if (rest.length < 2) {
+      throw new Error(`parsePath: /by-item requires <domain>/<itemId>, got: "${pathString}"`)
+    }
+    const domain = rest[0]
+    if (!(DOMAIN_ITEM_KINDS as readonly string[]).includes(domain)) {
+      throw new Error(`parsePath: /by-item unknown domain "${domain}". Supported: ${DOMAIN_ITEM_KINDS.join(', ')}`)
+    }
+    const itemId = rest.slice(1).join('/')
+    return { mount: 'by-item', args: [domain, itemId] }
+  }
+
   // /<nodeId>  (single node)
   // first must not be a recognized mount prefix
   if (segments.length === 1) {
@@ -391,7 +446,7 @@ export function parsePath(pathString: string): ParsedKnowledgePath {
   }
 
   throw new Error(
-    `parsePath: unrecognized path pattern "${pathString}". Supported: /by-system/<id>, /by-kind/<kind>, /by-owner/<id>, /graph/<nodeId>/governs, /graph/<nodeId>/governed-by, /<nodeId>, /all-systems, /all-resources, /all-roles`
+    `parsePath: unrecognized path pattern "${pathString}". Supported: /by-system/<id>, /by-kind/<kind>, /by-owner/<id>, /by-domain/<domain>, /by-item/<domain>/<itemId>, /graph/<nodeId>/governs, /graph/<nodeId>/governed-by, /<nodeId>, /all-systems, /all-resources, /all-roles`
   )
 }
 
@@ -763,6 +818,58 @@ function collectOntologyEntries(scope: {
 // omDescribe — neighborhood view for any OM node ID
 // ---------------------------------------------------------------------------
 
+/**
+ * Location context for a domain-item node in the organization graph.
+ */
+export interface OmDescribeDomainItemLocation {
+  /** Human-readable label for the domain (e.g. "Clients"). */
+  domainLabel: string
+  /** Graph node id for this item (e.g. `client:<uuid>`). */
+  graphNodeId: string
+  /** Parent graph node ids reachable via `contains` edges (e.g. `['organization-model']`). */
+  containsParentIds: string[]
+}
+
+/**
+ * A single governing knowledge node reference returned by domain-item describe.
+ */
+export interface OmDescribeDomainItemKnowledgeRef {
+  id: string
+  title: string
+  knowledgeKind: string
+}
+
+/**
+ * Structured neighborhood view of a domain-item node.
+ *
+ * Returned by `omDescribe` for `item:<domain>:<id>` and bare-id forms
+ * (e.g. `client:<uuid>`). Carries the full domain record payload, graph
+ * location, and any governing knowledge nodes.
+ */
+export interface OmDescribeDomainItem {
+  kind: 'domain-item'
+  /** The `item:<domain>:<id>` canonical reference string. */
+  id: string
+  /** The domain collection this item belongs to (e.g. `'clients'`). */
+  domain: DomainItemKind
+  /** Human-readable name or label for this item. */
+  name: string
+  /** Graph node location: graph id, domain label, and parentage. */
+  location: OmDescribeDomainItemLocation
+  /**
+   * Full domain record payload. Shape varies by domain:
+   * - `clients`: full `ClientProfile` (identity, branding, links, prompts, config, etc.)
+   * - `roles`: id, title, responsibilities, responsibleFor, reportsToId
+   * - `policies`: id, label, description, trigger, appliesTo, actions
+   * - `customers`: id, name, description, jobsToBeDone, pains, gains, firmographics
+   * - `offerings`: id, name, description, pricingModel, price, targetSegmentIds
+   * - `goals`: id, description, periodStart, periodEnd, keyResults
+   */
+  record: Record<string, unknown>
+  /** Knowledge nodes that govern this domain item via `governs` edges. */
+  governingKnowledge: OmDescribeDomainItemKnowledgeRef[]
+}
+
 /**
  * Structured neighborhood view of a single OM node.
  *
@@ -778,6 +885,7 @@ export type OmDescribeResult =
   | OmDescribeOntology
   | OmDescribeRole
   | OmDescribePolicy
+  | OmDescribeDomainItem
 
 export interface OmDescribeSystem {
   kind: 'system'
@@ -868,18 +976,40 @@ export interface OmDescribePolicy {
  * Detection rules (highest priority first):
  * - Contains `:<ontology-kind>/<local-id>` → ontology
  * - Starts with `knowledge.` → knowledge
- * - Starts with `role.` → role
- * - Starts with `policy.` → policy
+ * - Starts with `role.` (dotted) → role (OM role, NOT domain-item bare form)
+ * - Starts with `policy.` (dotted) → policy (OM policy, NOT domain-item bare form)
+ * - Starts with `item:<domain>:` → domain-item (canonical form)
+ * - Starts with a bare domain prefix followed by `:` → domain-item (back-compat)
  * - Resolves via `getSystem()` → system
  * - Matches a key in `model.resources` → resource
  */
-function detectKind(model: OrganizationModel, id: string): OmSearchHitKind | undefined {
+function detectKind(model: OrganizationModel, id: string): OmSearchHitKind | 'domain-item' | undefined {
   if (/:(object|action|event|catalog|link|interface|value-type|property|group|endpoint)\//.test(id)) {
     return 'ontology'
   }
   if (id.startsWith('knowledge.')) return 'knowledge'
+  // Dotted role/policy forms (e.g. role.ops-lead, policy.approve-large-deals) — OM search kinds.
+  // These must be checked BEFORE the bare colon forms so 'role.' does not collide with 'role:'.
   if (id.startsWith('role.')) return 'role'
   if (id.startsWith('policy.')) return 'policy'
+  // Canonical domain-item form: item:<domain>:<id>
+  if (id.startsWith('item:')) {
+    const afterItem = id.slice('item:'.length)
+    const colonIdx = afterItem.indexOf(':')
+    if (colonIdx > 0) {
+      const domain = afterItem.slice(0, colonIdx)
+      if ((DOMAIN_ITEM_KINDS as readonly string[]).includes(domain)) return 'domain-item'
+    }
+    return undefined
+  }
+  // Bare domain-item prefix forms: client:<id>, role:<id>, policy:<id>,
+  // customer:<id>, offering:<id>, goal:<id>.
+  // These use a colon separator (NOT a dot), so 'role:' is distinct from 'role.'.
+  const firstColon = id.indexOf(':')
+  if (firstColon > 0) {
+    const prefix = id.slice(0, firstColon)
+    if (prefix in BARE_PREFIX_TO_DOMAIN) return 'domain-item'
+  }
   if (model.systems && getSystemByPath(model.systems, id)) return 'system'
   if (model.resources?.[id]) return 'resource'
   return undefined
@@ -929,6 +1059,8 @@ export function omDescribe(model: OrganizationModel, id: string): OmDescribeResu
       return describeRole(model, id)
     case 'policy':
       return describePolicy(model, id)
+    case 'domain-item':
+      return describeDomainItem(model, id)
   }
 }
 
@@ -1129,3 +1261,127 @@ function describePolicy(model: OrganizationModel, id: string): OmDescribePolicy
     effectKinds: (policy.actions ?? []).map((a) => a.kind)
   }
 }
+
+// ---------------------------------------------------------------------------
+// Domain-item describe helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Human-readable labels for each domain kind.
+ */
+const DOMAIN_LABEL: Record<DomainItemKind, string> = {
+  clients: 'Clients',
+  roles: 'Roles',
+  policies: 'Policies',
+  customers: 'Customers',
+  offerings: 'Offerings',
+  goals: 'Goals'
+}
+
+/**
+ * Graph node id prefix for each domain kind. Mirrors the convention used by
+ * `buildOrganizationGraph` in `organization-model/graph/build.ts`:
+ *   client:<id>, role:<id>, policy:<id>, customer-segment:<id>, offering:<id>, goal:<id>
+ */
+const DOMAIN_GRAPH_PREFIX: Record<DomainItemKind, string> = {
+  clients: 'client',
+  roles: 'role',
+  policies: 'policy',
+  customers: 'customer-segment',
+  offerings: 'offering',
+  goals: 'goal'
+}
+
+/**
+ * Parse a domain-item ref (canonical `item:<domain>:<id>` or bare `<prefix>:<id>`)
+ * into `{ domain, itemId }`. Returns `undefined` when the ref cannot be parsed.
+ */
+function parseDomainItemRef(id: string): { domain: DomainItemKind; itemId: string } | undefined {
+  // Canonical: item:<domain>:<id>
+  if (id.startsWith('item:')) {
+    const afterItem = id.slice('item:'.length)
+    const colonIdx = afterItem.indexOf(':')
+    if (colonIdx <= 0) return undefined
+    const domain = afterItem.slice(0, colonIdx) as DomainItemKind
+    const itemId = afterItem.slice(colonIdx + 1)
+    if (!(DOMAIN_ITEM_KINDS as readonly string[]).includes(domain) || !itemId) return undefined
+    return { domain, itemId }
+  }
+  // Bare prefix: client:<id>, role:<id>, etc.
+  const firstColon = id.indexOf(':')
+  if (firstColon <= 0) return undefined
+  const prefix = id.slice(0, firstColon)
+  const domain = BARE_PREFIX_TO_DOMAIN[prefix]
+  if (!domain) return undefined
+  const itemId = id.slice(firstColon + 1)
+  if (!itemId) return undefined
+  return { domain, itemId }
+}
+
+/**
+ * Build a structured neighborhood view of a domain-item node.
+ *
+ * Accepts canonical `item:<domain>:<id>` or bare back-compat forms
+ * (`client:<uuid>`, `role:<id>`, etc.).
+ */
+function describeDomainItem(model: OrganizationModel, id: string): OmDescribeDomainItem | undefined {
+  const parsed = parseDomainItemRef(id)
+  if (!parsed) return undefined
+
+  const { domain, itemId } = parsed
+
+  // Look up the record in the appropriate domain collection.
+  const collection = model[domain] as Record<string, Record<string, unknown>> | undefined
+  const record = collection?.[itemId]
+  if (!record) return undefined
+
+  // Derive the item's name. Each domain uses a different field for the display name.
+  const name =
+    domain === 'clients'
+      ? String((record['name'] as string | undefined) ?? itemId)
+      : domain === 'roles'
+        ? String((record['title'] as string | undefined) ?? itemId)
+        : domain === 'policies'
+          ? String((record['label'] as string | undefined) ?? itemId)
+          : domain === 'goals'
+            ? String((record['description'] as string | undefined) ?? itemId)
+            : String((record['name'] as string | undefined) ?? itemId)
+
+  // Graph node id follows the build.ts convention.
+  const graphNodeId = `${DOMAIN_GRAPH_PREFIX[domain]}:${itemId}`
+
+  // Contains parentage — all domain items have a single `contains` edge from
+  // `organization-model`. We derive this from the known convention without
+  // building the full graph (avoids heavy dependency).
+  const containsParentIds = ['organization-model']
+
+  // Governing knowledge: knowledge nodes whose links target this item's graph node.
+  const governingKnowledge: OmDescribeDomainItemKnowledgeRef[] = []
+  for (const node of Object.values(model.knowledge ?? {})) {
+    const governs = (node.links ?? []).some((link) => link.nodeId === graphNodeId)
+    if (governs) {
+      governingKnowledge.push({
+        id: node.id,
+        title: node.title,
+        knowledgeKind: node.kind
+      })
+    }
+  }
+
+  // Canonical id is always the `item:<domain>:<id>` form.
+  const canonicalId = `item:${domain}:${itemId}`
+
+  return {
+    kind: 'domain-item',
+    id: canonicalId,
+    domain,
+    name,
+    location: {
+      domainLabel: DOMAIN_LABEL[domain],
+      graphNodeId,
+      containsParentIds
+    },
+    record: record as Record<string, unknown>,
+    governingKnowledge
+  }
+}