@elevasis/core 0.22.0 → 0.24.0

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

@@ -1,89 +1,110 @@
----
-title: Organization Graph
-description: Organization OS graph layer documentation for the organization graph derived from flat Organization Model features and resource metadata links.
----
-
-## Overview
-
-The organization graph treats the organization model as the top-level ontology and bridges in Command View runtime topology. Command View is a lens over the shared graph, not a separate semantic model.
-
-Graph contracts live in `@repo/core`; rendering lives in `@repo/ui`.
-
-## Source of Truth
-
-- `packages/core/src/organization-model/graph/types.ts`
-- `packages/core/src/organization-model/graph/schema.ts`
-- `packages/core/src/organization-model/graph/build.ts`
-- `packages/core/src/organization-model/graph/link.ts`
-- `packages/core/src/organization-model/__tests__/graph.test.ts`
-- `packages/ui/src/features/operations/OrganizationGraphPage.tsx`
-- `packages/ui/src/features/operations/organization-graph/`
-
-## Model
-
-Node kinds:
-
-- `organization`
-- `feature`
-- `surface`
-- `entity`
-- `capability`
-- `resource`
-
-Edge kinds:
-
-- `contains`
-- `references`
-- `exposes`
-- `maps_to`
-- `operates-on`
-- `uses`
-
-Feature nodes come from the flat `OrganizationModel.features` array. Their graph IDs use `feature:<id>`, such as `feature:sales.crm`.
-
-Resource edges come from resource metadata:
-
-```ts
-links: [
-  { nodeId: 'feature:sales.lead-gen', kind: 'operates-on' },
-  { nodeId: 'integration:instantly', kind: 'uses' }
-]
-```
-
-## Build Pipeline
-
-```ts
-interface BuildOrganizationGraphInput {
-  organizationModel: OrganizationModel
-  commandViewData?: CommandViewData
-}
-```
-
-`buildOrganizationGraph`:
-
-1. Reads flat Organization Model features and derives `feature:*` nodes.
-2. Reads Command View resources, including integration resources, as `resource` nodes with `resourceType` metadata.
-3. Emits authored graph links from resource/entity/capability metadata.
-4. Bridges Command View runtime topology into resource nodes and relationship edges.
-5. Returns a renderer-agnostic DTO.
-
-## Lenses
-
-UI lenses change presentation, not data:
-
-- `default` -- broad map view.
-- `command-view` -- operations-focused trace view.
-
-## Package Boundary
-
-- `@repo/core` owns graph DTOs, schemas, and build helpers.
-- `@repo/ui` owns Cytoscape conversion, filtering, path tracing, panels, and presentation.
-- `apps/command-center` owns route wiring.
-
-## Verification
-
-```bash
-pnpm --filter @repo/core test -- organization-model graph
-pnpm --filter @repo/ui test -- organizationGraph
-pnpm --filter command-center build
-```
+---
+title: Organization Graph
+description: Organization OS graph layer documentation for the organization graph derived from Organization Model Systems, resources, actions, entities, content nodes, and typed links.
+---
+
+## Overview
+
+The organization graph treats the organization model as the top-level ontology and bridges in Command View runtime topology. Command View is a lens over the shared graph, not a separate semantic model.
+
+Graph contracts live in `@repo/core`; rendering lives in `@repo/ui`.
+
+## Source of Truth
+
+- `packages/core/src/organization-model/graph/types.ts`
+- `packages/core/src/organization-model/graph/schema.ts`
+- `packages/core/src/organization-model/graph/build.ts`
+- `packages/core/src/organization-model/graph/link.ts`
+- `packages/core/src/organization-model/__tests__/graph.test.ts`
+- `packages/ui/src/features/operations/OrganizationGraphPage.tsx`
+- `packages/ui/src/features/operations/organization-graph/`
+
+## Model
+
+Node kinds:
+
+- `organization`
+- `system`
+- `role`
+- `action`
+- `entity`
+- `event`
+- `resource`
+- `knowledge`
+- `policy`
+- `stage`
+- `customer-segment`
+- `offering`
+- `goal`
+- `surface`
+- `navigation-group`
+- `content-node`
+
+Edge kinds:
+
+- `contains`
+- `references`
+- `maps_to`
+- `uses`
+- `governs`
+- `governed-by`
+- `links`
+- `affects`
+- `emits`
+- `originates_from`
+- `triggers`
+- `applies_to`
+- `effects`
+
+System nodes come from the id-keyed `OrganizationModel.systems` map. Their graph IDs use `system:<id>`, such as `system:sales.crm`.
+
+Resource, action, entity, policy, navigation, and content edges are derived from canonical OM maps:
+
+```ts
+// ResourceEntry.systemPath => system -> resource contains
+// SystemEntry.actions[] => system -> action uses
+// Action.resourceId => action -> resource maps_to
+// Action.affects[] => action -> entity affects
+// Entity.links[] => entity -> entity links
+// ResourceEntry.emits[] => resource -> event emits
+// System.content => system -> content-node contains
+// AgentResource.invocations[] => agent resource -> invocation target uses/references
+```
+
+## Build Pipeline
+
+```ts
+interface BuildOrganizationGraphInput {
+  organizationModel: OrganizationModel
+  commandViewData?: CommandViewData
+}
+```
+
+`buildOrganizationGraph`:
+
+1. Reads Organization Model Systems and derives `system:*` nodes.
+2. Reads OM resources, including workflow, agent, integration, and script resources, as `resource` nodes.
+3. Emits derived graph links from System, Resource, Action, Entity, Policy, Agent invocation, Knowledge, navigation, and System content contracts.
+4. Bridges Command View runtime topology into resource nodes and relationship edges.
+5. Returns a renderer-agnostic DTO.
+
+## Lenses
+
+UI lenses change presentation, not data:
+
+- `default` -- broad map view.
+- `command-view` -- operations-focused trace view.
+
+## Package Boundary
+
+- `@repo/core` owns graph DTOs, schemas, and build helpers.
+- `@repo/ui` owns Cytoscape conversion, filtering, path tracing, panels, and presentation.
+- `apps/command-center` owns route wiring.
+
+## Verification
+
+```bash
+pnpm --filter @repo/core test -- organization-model graph
+pnpm --filter @repo/ui test -- organizationGraph
+pnpm --filter command-center build
+```

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

@@ -1,171 +1,226 @@
----
-title: Organization Model
-description: Organization OS Model layer documentation for the flat feature hierarchy, semantic domains, resource descriptors, and curated @elevasis/core public API.
----
-
-## Overview
-
-The organization model is the semantic contract that maps an organization's product shape to flat feature hierarchy, business semantics, shell navigation, and graph binding. It is schema-first, versioned, and validated.
-
-The model is authored in `@repo/core` and published through the curated `@elevasis/core/organization-model` surface.
-
-## Source of Truth
-
-- `packages/core/src/organization-model/schema.ts`
-- `packages/core/src/organization-model/types.ts`
-- `packages/core/src/organization-model/defaults.ts`
-- `packages/core/src/organization-model/helpers.ts`
-- `packages/core/src/organization-model/graph/link.ts`
-- `packages/core/src/organization-model/published.ts`
-- `packages/core/src/__tests__/template-core-compatibility.test.ts`
-
-## Contract Shape
-
-Top-level fields on `OrganizationModel`:
-
-- `version`
-- `features`
-- `branding`
-- `navigation`
-- `sales`
-- `prospecting`
-- `projects`
-- `identity`
-- `customers`
-- `offerings`
-- `roles`
-- `goals`
-- `systems`
-- `resources`
-- `statuses`
-- `operations`
-- `knowledge`
-
-Resource identity is authored inside `OrganizationModel.resources.entries`. Runtime workflows, agents, and integrations import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
-
-## Feature Shape
-
-`OrganizationModel.features` is a flat array. Hierarchy is derived from dotted IDs:
-
-```ts
-features: [
-  { id: 'dashboard', label: 'Dashboard', enabled: true, path: '/', uiPosition: 'sidebar-primary' },
-  { id: 'sales', label: 'Sales', enabled: true, uiPosition: 'sidebar-primary' },
-  { id: 'sales.crm', label: 'CRM', enabled: true, path: '/crm' },
-  { id: 'operations.resources', label: 'Resources', enabled: true, path: '/operations/resources' }
-]
-```
-
-Authored fields:
-
-- `id`
-- `label`
-- `description`
-- `enabled`
-- `path`
-- `icon`
-- `color`
-- `uiPosition`
-- `requiresAdmin`
-- `devOnly`
-
-Containers omit `path`; leaves provide `path`. `uiPosition`, `requiresAdmin`, and `devOnly` inherit from ancestors.
-Development-only features remain defined and enabled with `devOnly: true`; shell consumers hide those entries and route paths outside development mode while preserving the semantic contract.
-
-Navigation surfaces may also carry `devOnly` for compatibility with the legacy/domain navigation model. `knowledge.command-view` is intentionally development-only while its graph visualization modes continue to mature.
-
-## Graph IDs and Resource Descriptors
-
-Cross-collection links use kind-prefixed graph IDs:
-
-- `feature:sales.crm`
-- `integration:instantly`
-- `resource:lead-import`
-- `capability:operations.queue.review`
-
-Resource identity is authored in the OM Resources domain. Operations imports descriptors from `organizationModel.resources.entries` and derives runtime `resourceId` / `type` while attaching executable behavior.
-
-```ts
-import { defineResources } from '@elevasis/core/organization-model'
-
-export const resourceDescriptors = defineResources({
-  leadImport: {
-    id: 'lead-import',
-    kind: 'workflow',
-    systemId: 'sys.prospecting',
-    ownerRoleId: 'role-ops-lead',
-    status: 'active',
-    capabilityKey: 'prospecting.lead-import'
-  }
-})
-
-export const resourceGovernanceModel = {
-  systems: {
-    systems
-  },
-  resources: {
-    entries: Object.values(resourceDescriptors)
-  }
-} as const
-```
-
-## Domain Semantics
-
-The model keeps business semantics in named domains:
-
-- `sales` -- pipeline stages and stage semantics
-- `prospecting` -- company/contact lifecycle stages
-- `projects` -- project, milestone, and task statuses
-- `identity`, `customers`, `offerings`, `roles`, `goals` -- organizational reality
-- `systems` -- bounded contexts that group governed operational resources
-- `resources` -- governance-only workflow, agent, and integration descriptors
-- `statuses` and `operations` -- runtime/vibe-layer semantic registries
-- `knowledge` -- playbooks, strategies, references, and graph-governing links
-
-## Authoring and Resolution
-
-- `defineOrganizationModel()` is a typed authoring helper.
-- `resolveOrganizationModel(partial)` deep-merges a partial override into `DEFAULT_ORGANIZATION_MODEL` and validates the result.
-- `createFoundationOrganizationModel(partial)` resolves the canonical model and returns template-facing helpers.
-- Plain objects merge recursively.
-- Arrays replace defaults.
-
-## Referential Integrity
-
-`OrganizationModelSchema` validates:
-
-- unique feature IDs
-- ancestor existence for dotted feature IDs
-- container/leaf path rules
-- valid sidebar positions
-- reality-domain cross references such as offering target segments and role reporting lines
-- system, resource, role, knowledge, and goal cross references used by resource governance
-
-`DeploymentSpec` remains the runtime/deploy assembly around these descriptors. It is not the source of resource identity.
-
-## Provider Integration
-
-`ElevasisFeaturesProvider` uses the organization model to:
-
-1. validate each manifest's `featureId`
-2. resolve effective feature access
-3. derive sidebar entries from `features`
-4. expose shell helpers such as `childrenOf`, `ancestorsOf`, and `findByPath`
-5. bridge the operations graph into shared UI
-
-## Published Package
-
-`@elevasis/core` exposes a curated browser-safe surface:
-
-- root barrel
-- `./organization-model`
-
-The organization graph builder remains monorepo-internal until there is a concrete external contract need.
-
-## Verification
-
-```bash
-pnpm --filter @repo/core test -- organization-model
-pnpm --filter @repo/core build:publish
-pnpm -C external/_template/core test
-```
+---
+title: Organization Model
+description: Organization OS Model layer documentation for the System hierarchy, semantic domains, resource descriptors, and curated @elevasis/core public API.
+---
+
+## Overview
+
+The organization model is the semantic contract that maps an organization's System hierarchy, business semantics, shell navigation, resource governance, action/entity vocabulary, and graph binding. It is schema-first, versioned, and validated.
+
+The model is authored in `@repo/core` and published through the curated `@elevasis/core/organization-model` surface.
+
+## Source of Truth
+
+- `packages/core/src/organization-model/schema.ts`
+- `packages/core/src/organization-model/types.ts`
+- `packages/core/src/organization-model/defaults.ts`
+- `packages/core/src/organization-model/helpers.ts`
+- `packages/core/src/organization-model/graph/link.ts`
+- `packages/core/src/organization-model/published.ts`
+- `packages/core/src/__tests__/template-core-compatibility.test.ts`
+
+## Contract Shape
+
+Top-level fields on `OrganizationModel`:
+
+- `version`
+- `domainMetadata`
+- `branding`
+- `navigation`
+- `identity`
+- `customers`
+- `offerings`
+- `roles`
+- `goals`
+- `systems`
+- `resources`
+- `actions`
+- `entities`
+- `policies`
+- `knowledge`
+
+The pure collection domains are id-keyed maps: `systems`, `roles`, `goals`, `customers`, `offerings`, `resources`, `actions`, `entities`, `policies`, and `knowledge`. The map key must match the entry `id`. Entries carry `order` for deterministic ordered views; use `listDomain(record)` when order matters.
+
+Resource identity is authored inside `OrganizationModel.resources`. Runtime workflows, agents, integrations, and scripts import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
+
+## System Shape
+
+`OrganizationModel.systems` is the canonical semantic domain map. Hierarchy is authored with recursive `subsystems`; dotted paths such as `sales.crm` are derived from position in that tree. `parentSystemId` and `id` remain accepted compatibility fields during the migration.
+
+```ts
+systems: {
+  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
+  sales: { id: 'sales', order: 20, label: 'Sales', lifecycle: 'active' },
+  clients: { id: 'clients', order: 30, label: 'Clients', lifecycle: 'active' },
+  projects: { id: 'projects', order: 40, label: 'Projects', lifecycle: 'active' }
+}
+```
+
+Authored fields:
+
+- `id`
+- `label`
+- `description`
+- `kind`
+- `parentSystemId`
+- `ui`
+- `lifecycle`
+- `requiresAdmin`
+- `actions`
+- `policies`
+- `content`
+- `subsystems`
+- `order`
+
+Systems describe ownership, hierarchy, lifecycle, access, and governance. Sidebar presentation lives in `navigation.sidebar`, not on System entries. UI-backed Systems may still provide `ui.path` for route matching during the migration, but `ui.surfaces` is not an authored contract. `lifecycle` replaces the old feature enabled/dev-only split.
+
+## Navigation Shape
+
+`OrganizationModel.navigation.sidebar` is the authored shell tree. It has `primary` and `bottom` sections whose records contain recursive group nodes and routeable surface nodes:
+
+```ts
+navigation: {
+  sidebar: {
+    primary: {
+      dashboard: {
+        type: 'surface',
+        order: 10,
+        label: 'Dashboard',
+        path: '/',
+        surfaceType: 'dashboard',
+        targets: { systems: ['dashboard'] }
+      },
+      business: {
+        type: 'group',
+        order: 20,
+        label: 'Business',
+        children: {
+          sales: {
+            type: 'surface',
+            order: 10,
+            label: 'Sales',
+            path: '/sales',
+            surfaceType: 'page',
+            targets: { systems: ['sales'] }
+          },
+          clients: {
+            type: 'surface',
+            order: 20,
+            label: 'Clients',
+            path: '/clients',
+            surfaceType: 'list',
+            targets: { systems: ['clients'] }
+          }
+        }
+      }
+    },
+    bottom: {}
+  }
+}
+```
+
+Dashboard is ordered before Business in the primary sidebar. Business is a navigation group only; it is not a System and it is not a URL namespace. Routeable leaves are projected into flat surface DTOs by `projectOrganizationSurfaces(model)`.
+
+## Graph IDs and Resource Descriptors
+
+Cross-collection links use kind-prefixed graph IDs:
+
+- `system:sales.crm`
+- `integration:instantly`
+- `resource:lead-import`
+- `action:operations.queue.review`
+
+Resource identity is authored in the OM Resources domain. Operations imports descriptors from `organizationModel.resources` and derives runtime `resourceId` / `type` while attaching executable behavior.
+
+```ts
+import { defineResources } from '@elevasis/core/organization-model'
+
+export const resourceDescriptors = defineResources({
+  leadImport: {
+    id: 'lgn-01c-apollo-import-workflow',
+    kind: 'workflow',
+    systemPath: 'sales.lead-gen',
+    ownerRoleId: 'role-ops-lead',
+    status: 'active',
+    actionKey: 'lead-gen.company.apollo-import',
+    codeRefs: [
+      {
+        path: 'packages/elevasis-operations/src/sales/prospecting/scrape/apollo-import.ts',
+        role: 'entrypoint',
+        symbol: 'lgnApolloImportWorkflow'
+      }
+    ]
+  }
+})
+
+export const resourceGovernanceModel = {
+  systems,
+  resources: resourceDescriptors
+} as const
+```
+
+Legacy `sys.*` paths may still appear in older examples and external compatibility mirrors.
+For new Organization OS examples, prefer the current semantic System path.
+
+## Domain Semantics
+
+The model keeps business semantics in named domains:
+
+- `identity`, `customers`, `offerings`, `roles`, `goals` -- organizational reality
+- `systems` -- bounded contexts that group governed operational resources and system-local content
+- `actions` -- stable business verbs exposed or consumed by systems
+- `entities` -- durable business nouns and their semantic links
+- `resources` -- governance-only workflow, agent, integration, and script descriptors
+- `policies` -- operational governance rules over systems, actions, resources, and roles
+- `knowledge` -- playbooks, strategies, references, and graph-governing links
+
+System-local operational catalogs now live under `System.content`, including pipeline, stage, template, template-step, status-flow, status, and config nodes. The legacy compound and status domains should not be used for new authoring.
+
+## Authoring and Resolution
+
+- `defineOrganizationModel()` is a typed authoring helper.
+- `resolveOrganizationModel(partial)` deep-merges a partial override into `DEFAULT_ORGANIZATION_MODEL` and validates the result.
+- `createFoundationOrganizationModel(partial)` resolves the canonical model and returns template-facing helpers.
+- Plain objects merge recursively.
+- Id-keyed domain maps merge additively by key.
+- Arrays replace defaults.
+
+## Referential Integrity
+
+`OrganizationModelSchema` validates:
+
+- unique System IDs
+- ancestor existence for dotted System IDs and `parentSystemId`
+- UI path rules for Systems with UI presence
+- valid sidebar positions
+- reality-domain cross references such as offering target segments and role reporting lines
+- system, resource, role, knowledge, and goal cross references used by resource governance
+
+`DeploymentSpec` remains the runtime/deploy assembly around these descriptors. It is not the source of resource identity.
+
+## Provider Integration
+
+`ElevasisSystemsProvider` uses the organization model to:
+
+1. validate each manifest's `systemId`
+2. resolve effective system access
+3. derive sidebar entries from `navigation.sidebar`
+4. expose shell helpers such as `childrenOf`, `ancestorsOf`, and `findByPath`
+5. bridge the operations graph into shared UI
+
+## Published Package
+
+`@elevasis/core` exposes a curated browser-safe surface:
+
+- root barrel
+- `./organization-model`
+
+The organization graph builder remains monorepo-internal until there is a concrete external contract need.
+
+## Verification
+
+```bash
+pnpm --filter @repo/core test -- organization-model
+pnpm --filter @repo/core build:publish
+pnpm -C external/_template/core test
+```