@elevasis/core 0.10.0 → 0.11.1

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

@@ -1,320 +1,152 @@
----
-title: Organization Model
-description: Organization OS Model layer documentation for the semantic organization contract, covering domains, features, navigation surfaces, resource mappings, and the curated @elevasis/core public API.
----
-
-## Overview
-
-Within Organization OS, the organization model is the **Model** layer and part of the cross-cutting **Public API** layer. It is the semantic contract that maps an organization's full organizational reality to domains, features, navigation surfaces and groups, domain-specific semantics (sales pipeline, prospecting lifecycle, projects status), and resource mappings. It is schema-first, versioned, and validated.
-
-The model is authored in `@repo/core` and published as a curated external package `@elevasis/core`. It is consumed by:
-
-- `@repo/ui`'s feature-shell provider to resolve nav labels, surface paths, and feature state at runtime
-- command-center's root shell as its canonical organization model
-- `external/_template/foundations` and downstream derivatives as the adapter-backed source of organization truth
-
-The model does **not** replace the shared feature-provider system. It enriches and constrains it.
-
-## Source of Truth
-
-- `packages/core/src/organization-model/schema.ts` -- `OrganizationModelSchema`
-- `packages/core/src/organization-model/types.ts` -- exported TypeScript types
-- `packages/core/src/organization-model/defaults.ts` -- `DEFAULT_ORGANIZATION_MODEL`
-- `packages/core/src/organization-model/resolve.ts` -- `defineOrganizationModel`, `resolveOrganizationModel`
-- `packages/core/src/organization-model/domains/*.ts` -- feature schema, navigation surfaces, sales/prospecting/projects semantics, and the 8 reality domains (identity, customers, offerings, roles, goals, statuses, operations, shared/techStack)
-- `packages/core/src/published.ts` -- curated root barrel for the published package
-- `packages/core/src/organization-model/published.ts` -- curated organization-model barrel
-- `packages/core/src/__tests__/template-foundations-compatibility.test.ts` -- adapter-baseline guard
-
-## Contract Shape
-
-Top-level fields on `OrganizationModel`:
-
-- `version`
-- `features` -- unified feature array (`OrganizationModelFeature[]`); each entry combines access gating, semantic grouping, and display metadata
-- `branding` -- display identity (org name, product name, logos)
-- `navigation` -- surfaces, groups, `defaultSurfaceId`
-- `sales` -- pipeline stages and stage semantics (formerly `crm`)
-- `prospecting` -- company/contact lifecycle stages (formerly `leadGen`)
-- `projects` -- project/milestone/task statuses (formerly `delivery`)
-- `identity` -- legal identity, mission/vision, industry, geography, and temporal anchors
-- `customers` -- customer segments with jobs-to-be-done, firmographics, and value propositions
-- `offerings` -- products and services with pricing model and segment/feature references
-- `roles` -- role chart with responsibilities, reporting lines, and role holders
-- `goals` -- organizational goals with period and measurable outcomes
-- `statuses` -- flat registry of all status entries across delivery, queue, execution, schedule, and request semantic classes
-- `operations` -- catalog of stateful runtime entities (HITL queue, executions, sessions, notifications, schedules)
-- `resourceMappings` -- deployable resource links, each optionally extended with `techStack` metadata
-
-### Domain Rename Wave
-
-Three legacy domain names were renamed in the 2026-04-20 expansion to align developer-facing code with user-visible labels:
-
-| Old name   | New name      | Notes                                                                                |
-| ---------- | ------------- | ------------------------------------------------------------------------------------ |
-| `crm`      | `sales`       | Domain files, feature IDs, surface IDs, imports, and sidebar labels all updated      |
-| `leadGen`  | `prospecting` | Same scope as above                                                                  |
-| `delivery` | `projects`    | Aligns with the "Projects" sidebar label; `projects` feature ID was already in place |
-
-Any reference to `crm`, `leadGen`, or `delivery` in domain files, imports, or surface IDs should be treated as a historical artifact unless explicitly annotated otherwise.
-
-### Branding Shape
-
-`OrganizationModelBranding` holds display identity for the organization:
-
-- `organizationName` -- the human-readable org name (required)
-- `productName` -- the product label shown in the shell (required)
-- `shortName` -- abbreviated name, max 40 chars (required)
-- `description` -- optional long-form description
-- `logos` -- optional object with `light` and `dark` URL strings (each max 2048 chars); defaults to `{}`
-
-### ModelId Format Rules
-
-All `id` fields, `parentId`, `defaultSurfaceId`, and reference ID arrays use `ModelIdSchema`:
-
-- Regex: `/^[a-z0-9]+(?:[-._][a-z0-9]+)*$/`
-- Max length: 100 chars
-- Allowed separators: `-`, `_`, `.`
-- Examples: `sales.pipeline`, `prospecting.lists`, `operations.organization-graph`
-
-This applies to domain IDs, surface IDs, navigation group IDs, and resource mapping IDs.
-
-### Default Features
-
-Eight features ship by default in `DEFAULT_ORGANIZATION_MODEL.features`:
-
-- `crm` -- enabled; sales pipeline and deal management (feature ID unchanged; domain renamed to `sales`)
-- `lead-gen` -- enabled; prospecting, qualification, and outreach (feature ID unchanged; domain renamed to `prospecting`)
-- `projects` -- enabled; projects, milestones, and client work execution
-- `operations` -- enabled; organizational topology and orchestration visibility
-- `monitoring` -- enabled; execution monitoring
-- `settings` -- enabled; organization settings
-- `submitted-requests` -- enabled; submitted-request lifecycle surface
-- `seo` -- disabled by default; SEO surface
-
-Note: the feature IDs (`crm`, `lead-gen`) are consumer-facing identifiers that have not changed. The underlying domain key on `OrganizationModel` was renamed (`crm` → `sales`, `leadGen` → `prospecting`). Adapters that already use the feature ID constants (`CRM_FEATURE_ID`, `LEAD_GEN_FEATURE_ID`) require no change.
-
-Each feature entry (`OrganizationModelFeature`) combines what were previously three separate concepts: an access/gating key (the former `OrganizationModelFeatureKey`), a semantic domain (the former `SemanticDomainSchema` entry), and display metadata. The `features` field is now `z.array(FeatureSchema)` -- there is no separate `domains` array and no separate `enabled`/`labels` map.
-
-`FeatureModule.featureId` on the UI side maps directly to one of these IDs. No alias layer is needed. See [Feature Shell](../ui/feature-shell.mdx) for how the provider resolves feature access from this array.
-
-### ResourceMapping Shape
-
-`OrganizationModelResourceMapping` links a deployable resource into the semantic model:
-
-- `id` -- unique mapping ID (ModelId format)
-- `resourceId` -- the actual resource identifier (string, max 255 chars)
-- `resourceType` -- one of `'workflow' | 'agent' | 'trigger' | 'integration' | 'external' | 'human_checkpoint'`
-- `label`, `description`, `color`, `icon` -- display metadata (from `DisplayMetadataSchema`)
-- `featureIds` -- features this resource belongs to (replaces the former `domainIds`)
-- `entityIds` -- entities this resource operates on
-- `surfaceIds` -- surfaces this resource is exposed in
-- `capabilityIds` -- capabilities this resource fulfills
-- `techStack` (optional) -- external-SaaS integration metadata; see TechStack Extension below
-
-All four ID arrays are bidirectionally validated against their counterparts (see Referential Integrity).
-
-### TechStack Extension
-
-`techStack` is an optional nested object on `ResourceMappingSchema` defined in `domains/shared.ts`. It captures external-SaaS integration metadata without introducing a tenth top-level domain. Fields:
-
-- `platform` -- name of the external platform (e.g. "HubSpot", "Stripe", "Notion")
-- `purpose` -- free-form description of what this integration does
-- `credentialStatus` -- one of `'configured' | 'pending' | 'expired' | 'missing'`
-- `isSystemOfRecord` -- boolean; whether this integration is the primary source of truth for its domain (defaults to `false`)
-
-Backward-compatible: existing resource mappings without `techStack` parse cleanly. The extension flows through `ResourceMappingSchema` automatically with no changes to `schema.ts` composition.
-
-### Default Navigation
-
-Surfaces such as `sales.pipeline`, `prospecting.lists`, `projects.index`, `operations.organization-graph`, and `operations.command-view`. Groups include `primary-workspace` and `primary-operations`. The model can shape shell meaning even when route files stay app-local.
-
-### SurfaceDefinition Shape
-
-`OrganizationModelSurface` (inferred from `SurfaceDefinitionSchema`) defines a navigable view:
-
-- `id` -- ModelId (e.g. `sales.pipeline`)
-- `label` -- display name
-- `path` -- route path, must start with `/`, max 300 chars
-- `surfaceType` -- `'page' | 'dashboard' | 'graph' | 'detail' | 'list' | 'settings'`
-- `description` -- optional
-- `icon` -- optional icon name token (max 80 chars)
-- `featureId` -- optional feature ID that gates this surface (replaces the former `featureKey` field); must match a feature `id` in the features array
-- `parentId` -- optional ModelId referencing a parent surface; validated to exist
-- `featureIds` -- features this surface belongs to (bidirectionally validated; replaces the former `domainIds`)
-- `entityIds` -- entity IDs relevant to this surface
-- `resourceIds` -- resources exposed on this surface (bidirectionally validated against resource mappings)
-- `capabilityIds` -- capabilities this surface fulfills
-
-### NavigationGroup Placement
-
-`NavigationGroupSchema` has a `placement` field with three allowed values:
-
-- `'primary'` -- main workspace or operations nav rail
-- `'secondary'` -- secondary grouping (below primary)
-- `'bottom'` -- pinned to the bottom of the nav rail
-
-The default groups (`primary-workspace`, `primary-operations`) both use `placement: 'primary'`.
-
-### Feature-Specific Semantics
-
-Three renamed top-level domain fields carry feature-specific semantic shapes (pipeline stages, lifecycle stages, project statuses). These are named fields on `OrganizationModel`, not embedded in per-feature config:
-
-- `sales` -- pipeline stages and stage semantics (formerly `crm`)
-- `prospecting` -- company and contact lifecycle stages (formerly `leadGen`)
-- `projects` -- project, milestone, and task statuses (formerly `delivery`)
-
-This is why the organization model is semantic, not just nav config -- it owns product meaning for the business objects the shell surfaces expose.
-
-### Reality Domains (New in 2026-04-20 Expansion)
-
-Five new domains capture organizational reality that was absent from the original model. They sit alongside the existing platform-configuration domains and follow the same `domains/*.ts` pattern:
-
-**`identity`** -- legal identity distinct from `branding` (which is display identity). Fields: `mission`, `vision`, `legalName`, `entityType`, `jurisdiction`, `industryCategory`, `geographicFocus`, `timeZone`, `businessHours`. All fields default to empty strings; `timeZone` defaults to `'UTC'`; `businessHours` defaults to `{}`.
-
-**`customers`** -- customer segments. Each `CustomerSegment` entry has: `id`, `name`, `description`, `jobsToBeDone`, `pains`, `gains`, `valueProp` (all plain-language strings), and `firmographics` (optional object with `companySize`, `industry`, `revenue`, `geography`). Domain defaults to `{ segments: [] }`.
-
-**`offerings`** -- products and services. Each `Product` entry has: `id`, `name`, `description`, `pricingModel` (enum: `'one-time' | 'subscription' | 'usage-based' | 'custom'`), `price` (optional number), `currency` (optional string), `targetSegmentIds` (cross-ref validated against `customers.segments[].id`), `deliveryFeatureId` (optional cross-ref validated against `features[].id`). Domain defaults to `{ products: [] }`.
-
-**`roles`** -- role chart. Each `Role` entry has: `id`, `title`, `responsibilities` (string array, default `[]`), `reportsToId` (optional, cross-ref validated within the same collection), `heldBy` (optional name or email string). All field names are plain-language; no EOS jargon (`seats`, `accountabilities`) survives. Domain defaults to `{ roles: [] }`.
-
-**`goals`** -- organizational goals. Each `Objective` entry has: `id`, `description`, `periodStart` (ISO 8601 date), `periodEnd` (ISO 8601 date, must be strictly after `periodStart`), `keyResults` (array of `{ id, description, targetValue?, currentValue?, unit? }`). User-facing text uses "goals" and "measurable outcomes" -- never "OKR" or "key results". Domain defaults to `{ objectives: [] }`.
-
-### Statuses and Operations Domains (Vibe Layer)
-
-Two domains support the ambient vibe layer's plain-language rendering:
-
-**`statuses`** -- flat registry of `StatusEntry` objects. Each entry: `id`, `label`, `semanticClass` (one of `'delivery.task' | 'delivery.project' | 'delivery.milestone' | 'queue' | 'execution' | 'schedule' | 'schedule.run' | 'request'`), optional `category`. Labels are vibe-readable: the ambient classifier narrates state using `label` from the model, never hardcoded strings. `QueueTaskStatus` in the queue domain routes through this registry. Defaults to a seed set covering all semantic classes.
-
-**`operations`** -- catalog of stateful runtime entities. Each `OperationEntry`: `id`, `label`, `semanticClass` (one of `'queue' | 'executions' | 'sessions' | 'notifications' | 'schedules'`), optional `featureId`, optional `supportedStatusSemanticClass` (ties an operation entry back to which status semantic classes apply). Default entries: `operations.queue` (HITL queue), `operations.executions`, `operations.sessions`, `operations.notifications`, `operations.schedules`.
-
-## Authoring & Resolution
-
-- `defineOrganizationModel()` -- typed authoring helper; returns the input unchanged but constrains the type.
-- `resolveOrganizationModel(partial)` -- deep-merges a partial override into `DEFAULT_ORGANIZATION_MODEL` and validates the result against `OrganizationModelSchema`.
-
-Merge semantics:
-
-- plain objects merge recursively
-- arrays **replace** defaults (no element-by-element merge)
-- if `navigation.surfaces` is replaced without also supplying `navigation.groups`, inherited groups are normalized so they only keep still-valid surface IDs and any now-empty groups are dropped
-- missing fields fall back to defaults
-
-### Referential Integrity
-
-`OrganizationModelSchema` validates more than top-level shape. The `superRefine` pass enforces:
-
-**Uniqueness checks** -- IDs must be unique within their respective collections:
-
-- `features[].id`
-- `navigation.surfaces[].id`
-- `navigation.groups[].id`
-- `resourceMappings[].id`
-- `resourceMappings[].resourceId` (separate uniqueness check -- two mappings cannot share a `resourceId`)
-
-**Dangling reference detection** -- every cross-reference must resolve:
-
-- `navigation.defaultSurfaceId` must point at a declared surface
-- every `surfaceId` in a navigation group must resolve to a declared surface
-- every `surfaceId` in a feature must resolve to a declared surface
-- every `resourceId` in a feature must resolve to a declared resource mapping (by `resourceId`)
-- surface `parentId` must reference an existing surface
-- every `featureId` on a surface must resolve to a declared feature
-- every `resourceId` on a surface must resolve to a declared resource mapping
-- every `featureId` on a resource mapping must resolve to a declared feature
-- every `surfaceId` on a resource mapping must resolve to a declared surface
-
-**Bidirectional reference enforcement** -- cross-references must be mutual, not one-sided:
-
-- a feature listing `surfaceId` S requires surface S to list that feature's ID in its `featureIds`
-- a surface listing `featureId` F requires feature F to list that surface's ID in its `surfaceIds`
-- a feature listing `resourceId` R requires resource mapping R to list that feature's ID in its `featureIds`
-- a resource mapping listing `featureId` F requires feature F to list that resource's `resourceId` in its `resourceIds`
-- a surface listing `resourceId` R requires resource mapping R to list that surface's ID in its `surfaceIds`
-- a resource mapping listing `surfaceId` S requires surface S to list that resource's `resourceId` in its `resourceIds`
-
-This bidirectional enforcement is what keeps the organization model semantically consistent rather than loosely structured config.
-
-**Reality domain cross-refs** (validated in the same `superRefine` pass):
-
-- each `offerings.products[].targetSegmentIds[]` must resolve to a `customers.segments[].id`
-- each `offerings.products[].deliveryFeatureId` (when present) must resolve to a `features[].id`
-- each `roles.roles[].reportsToId` (when present) must resolve to another `roles.roles[].id` in the same collection
-- each `goals.objectives[].periodEnd` must be strictly after `periodStart` (ISO 8601 string comparison)
-
-## Provider Integration
-
-`ElevasisFeaturesProvider` uses the organization model in three ways:
-
-1. **Feature resolution** -- the provider looks up each manifest's `featureId` in `organizationModel.features` to determine `access.enabled`. If no matching feature entry is found, `access.enabled` defaults to `false`.
-2. **Nav label and path resolution** -- when `organizationModel` is present, feature labels resolve from the matching feature entry's `label` field, and surface labels and paths resolve from `organizationModel.navigation.surfaces`. Semantic customization without changing manifest code.
-3. **Organization-graph bridge** -- the `operationsManifest` declares `organizationGraph.surfaceId = 'operations.organization-graph'`. The provider resolves that against organization-model surfaces and exposes the result as `organizationGraph` in context. See [Organization Graph](./organization-graph.mdx).
-
-## Published Package: `@elevasis/core`
-
-`@elevasis/core` is a curated publish wrapper around `packages/core`, released through `$sdk release-core`. It exists so external foundations (`_template/foundations`, `nirvana-marketing/foundations`, `ZentaraHQ/foundations`) can depend on a stable, browser-safe organization-model contract without reaching into monorepo-only `@repo/core`.
-
-### Published surface
-
-Intentionally narrow:
-
-- `.` -- curated root barrel (`packages/core/src/published.ts`)
-- `./organization-model` -- curated organization-model barrel (`packages/core/src/organization-model/published.ts`)
-
-Exports on the first published surface:
-
-- `OrganizationModelSchema`
-- top-level organization-model types
-- `DEFAULT_ORGANIZATION_MODEL`
-- `defineOrganizationModel`
-- `resolveOrganizationModel`
-
-### Intentionally excluded
-
-- wider `@repo/core` browser barrel
-- organization-graph types/builder (`buildOrganizationGraph`, DTO types) -- graph work remains monorepo-first; external consumers should not assume graph contracts are published
-
-### Build
-
-- `pnpm --filter @repo/core build:publish` emits `dist/index.{js,d.ts}` and `dist/organization-model/index.{js,d.ts}` via tsup + `rollup-plugin-dts`.
-- Shipped types are browser-safe and verified to contain no `@repo/*` imports.
-
-### Release
-
-- `.claude/sub-commands/sdk/release-core.md` -- dedicated publish flow
-- `$sdk verify` -- covers publish metadata, bundled declarations, and the first template-foundation compatibility guard
-
-## Downstream Adoption
-
-External foundations consume `@elevasis/core/organization-model` via an **adapter**, not a fork. The adapter pattern in `external/_template/foundations/config/organization-model.ts`:
-
-1. Define a canonical override with `defineOrganizationModel(...)`.
-2. Resolve it with `resolveOrganizationModel(...)`.
-3. Adapt the result into a template-local helper shape that adds consumer-only fields (`homeLabel`, `quickAccessSurfaceIds`, icon aliases, `getOrganizationSurface()`).
-
-Exports the foundations module provides to consumers:
-
-- `canonicalOrganizationModel` -- passed to `ElevasisFeaturesProvider`
-- `organizationModel` -- widened adapter shape for template-local helpers
-- `FoundationFeatureKey`, `FoundationSurfaceIcon`, `FoundationNavigationSurface`, `FoundationOrganizationModel`
-- `homeLabel`, `quickAccessSurfaceIds`, `getOrganizationSurface(surfaceId)`
-
-Downstream template shells pass `canonicalOrganizationModel` into `ElevasisFeaturesProvider`, preserving host-local dashboard/nav customizations alongside the shared runtime. Feature IDs are direct matches -- `crm`, `lead-gen`, `projects` in the org model correspond directly to the same IDs on `FeatureModule.featureId`. No alias layer is needed. The domain rename wave (crm→sales, leadGen→prospecting, delivery→projects) affects the schema field names, not the feature ID constants; adapters using `CRM_FEATURE_ID`, `LEAD_GEN_FEATURE_ID`, etc. require no changes.
-
-Adapters that override the new reality domains (`identity`, `customers`, `offerings`, `roles`, `goals`) or add `techStack` metadata to resource mappings should use `/configure` as the structured entry point for those edits in external projects. `/configure` runs a layered QA flow, proposes changes, and gates the write through `resolveOrganizationModel()` + `OrganizationModelSchema.parse()` before committing.
-
-Derivative projects (`external/nirvana-marketing`, `external/ZentaraHQ`) follow the same adapter + provider-wiring baseline with their own project-local customizations.
-
-## Verification
-
-- `pnpm --filter @repo/core build:publish` -- published bundle
-- `pnpm --filter @repo/core test -- publish template-foundations-compatibility` -- published surface + adapter guard
-- `pnpm -C external/_template/foundations test` -- foundations adapter and import-boundary guard
-- `pnpm -C external/_template/ui test -- src/routes/__tests__/__root.test.tsx` -- provider-level `organizationModel` wiring in the template shell
-
-## Design Constraints
-
-- `@elevasis/core` must stay browser-safe. Build output inlines or eliminates `@repo/*` references from shipped types.
-- The published surface stays curated -- do not reflexively re-export new `@repo/core` internals. Widening the surface is a deliberate decision, not a default.
-- Organization-graph helpers remain internal until a concrete external consumer needs them.
-- Foundations adapters preserve the semantic contract; they do not fork it. If a template needs a concept the canonical model can't express, extend the canonical model first.
+---
+title: Organization Model
+description: Organization OS Model layer documentation for the flat feature hierarchy, semantic domains, resource graph links, 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`
+- `statuses`
+- `operations`
+
+Resources are not authored inside `OrganizationModel`. Deployable workflows, agents, triggers, integrations, external resources, and human checkpoints declare graph links on their resource metadata.
+
+## 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. `operations.command-view` is intentionally development-only while its graph visualization modes continue to mature.
+
+## Graph IDs and Resource Links
+
+Cross-collection links use kind-prefixed graph IDs:
+
+- `feature:sales.crm`
+- `integration:instantly`
+- `resource:lead-import`
+- `capability:operations.queue.review`
+
+Example resource metadata:
+
+```ts
+config: {
+  resourceId: 'lead-import',
+  name: 'Lead Import',
+  type: 'workflow',
+  version: '1.0.0',
+  status: 'prod',
+  links: [{ nodeId: 'feature:sales.lead-gen', kind: 'operates-on' }],
+  category: 'production'
+}
+```
+
+## 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
+- `statuses` and `operations` -- runtime/vibe-layer semantic registries
+
+## 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
+
+Resource graph links are validated during resource registry registration because resources live in deployment specs.
+
+## 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
+```

package/src/organization-model/published.ts

@@ -1,5 +1,6 @@
 export { OrganizationModelSchema } from './schema'
-export { FeatureSchema } from './domains/features'
+export { FeatureSchema, NodeIdPathSchema, NodeIdStringSchema, UiPositionSchema } from './domains/features'
+export { LinkSchema } from './graph/link'
 export { TechStackEntrySchema } from './domains/shared'
 export {
   PROJECTS_FEATURE_ID,
@@ -11,10 +12,11 @@ export {
   MONITORING_FEATURE_ID,
   SETTINGS_FEATURE_ID,
   SEO_FEATURE_ID,
-  SALES_PIPELINE_SURFACE_ID,
-  PROSPECTING_LISTS_SURFACE_ID,
-  OPERATIONS_ORGANIZATION_GRAPH_SURFACE_ID
-} from './contracts'
+  SALES_PIPELINE_SURFACE_ID,
+  PROSPECTING_LISTS_SURFACE_ID,
+  OPERATIONS_ORGANIZATION_GRAPH_SURFACE_ID,
+  OPERATIONS_COMMAND_VIEW_SURFACE_ID
+} from './contracts'
 export { DEFAULT_ORGANIZATION_MODEL } from './defaults'
 export {
   DEFAULT_ORGANIZATION_MODEL_STATUSES,
@@ -55,26 +57,25 @@ export type {
   OrganizationModelCustomerFirmographics,
   OrganizationModelCustomers,
   OrganizationModelCustomerSegment,
-  OrganizationModelFeature,
-  OrganizationModelGoals,
-  OrganizationModelKeyResult,
-  OrganizationModelNavigation,
-  OrganizationModelObjective,
+  OrganizationModelFeature,
+  OrganizationModelGoals,
+  OrganizationModelKeyResult,
+  OrganizationModelObjective,
   OrganizationModelOfferings,
   OrganizationModelOperationEntry,
   OrganizationModelOperationSemanticClass,
   OrganizationModelOperations,
-  OrganizationModelPricingModel,
-  OrganizationModelProduct,
-  OrganizationModelResourceMapping,
-  OrganizationModelRole,
+  OrganizationModelPricingModel,
+  OrganizationModelProduct,
+  OrganizationModelRole,
   OrganizationModelTechStackEntry,
   OrganizationModelRoles,
-  OrganizationModelStatuses,
-  OrganizationModelStatusEntry,
-  OrganizationModelStatusSemanticClass,
-  OrganizationModelSurface
-} from './types'
+  OrganizationModelStatuses,
+  OrganizationModelStatusEntry,
+  OrganizationModelStatusSemanticClass,
+  NodeIdPath,
+  NodeIdString
+} from './types'
 
 export type {
   FoundationBranding,

package/src/organization-model/resolve.ts

@@ -31,36 +31,11 @@ function deepMerge<T>(base: T, override: DeepPartial<T> | undefined): T {
   return result as T
 }
 
-function normalizeInheritedNavigationGroups(
-  model: OrganizationModel,
-  override?: DeepPartial<OrganizationModel>
-): OrganizationModel {
-  if (override?.navigation?.surfaces === undefined || override.navigation.groups !== undefined) {
-    return model
-  }
-
-  const validSurfaceIds = new Set(model.navigation.surfaces.map((surface) => surface.id))
-  const groups = model.navigation.groups
-    .map((group) => ({
-      ...group,
-      surfaceIds: group.surfaceIds.filter((surfaceId) => validSurfaceIds.has(surfaceId))
-    }))
-    .filter((group) => group.surfaceIds.length > 0)
-
-  return {
-    ...model,
-    navigation: {
-      ...model.navigation,
-      groups
-    }
-  }
-}
-
-export function defineOrganizationModel<T extends DeepPartial<OrganizationModel>>(model: T): T {
-  return model
-}
-
-export function resolveOrganizationModel(override?: DeepPartial<OrganizationModel>): OrganizationModel {
-  const merged = normalizeInheritedNavigationGroups(deepMerge(DEFAULT_ORGANIZATION_MODEL, override), override)
-  return OrganizationModelSchema.parse(merged)
-}
+export function defineOrganizationModel<T extends DeepPartial<OrganizationModel>>(model: T): T {
+  return model
+}
+
+export function resolveOrganizationModel(override?: DeepPartial<OrganizationModel>): OrganizationModel {
+  const merged = deepMerge(DEFAULT_ORGANIZATION_MODEL, override)
+  return OrganizationModelSchema.parse(merged)
+}