@elevasis/core 0.7.0 → 0.8.0

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

@@ -1,320 +1,320 @@
----
-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 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.