@elevasis/sdk 1.10.0 → 1.12.0

package/reference/scaffold/core/organization-model.mdx

@@ -1,320 +1,155 @@
----
-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.
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+## 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/reference/scaffold/index.mdx

@@ -2,6 +2,9 @@
 title: Scaffold Reference
 description: Universal scaffold documentation for Elevasis SDK projects -- recipes, patterns, architecture, and reference materials that apply to all workspaces.
 ---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
 
 ## Overview
 

package/reference/scaffold/operations/propagation-pipeline.md

@@ -2,6 +2,9 @@
 title: Propagation Pipeline
 description: Three-layer pipeline that keeps Organization OS artifacts current across the monorepo and all template-derived external projects -- source generation, registry-driven sync planning/apply, and verification.
 ---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
 
 # Propagation Pipeline
 
@@ -99,7 +102,7 @@ The external skill doc (`.claude/skills/external/SKILL.md`) remains the workflow
 | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `deps`         | `@elevasis/ui`, `@elevasis/sdk`, `@elevasis/core` versions match template                                                                                                                                                                                                                                                                                   |
 | `tier1`        | registry-backed replace surfaces match template where verification still models them as exact baselines                                                                                                                                                                                                                                                     |
-| `org-os`       | Organization model exists, exports canonical symbols, imports from `@elevasis/core/organization-model`, calls `defineOrganizationModel` + `resolveOrganizationModel`, app-config references org model, `__root.tsx` uses `ElevasisFeaturesProvider` + `canonicalOrganizationModel`, `main.tsx` uses `ElevasisUIProvider`, all 3 CSS subpath imports present |
+| `org-os`       | Organization model exists, exports canonical symbols, imports from `@elevasis/core/organization-model`, calls `createFoundationOrganizationModel`, app-config references org model, `__root.tsx` uses `ElevasisFeaturesProvider` + `canonicalOrganizationModel`, `main.tsx` uses `createElevasisApp`, all 3 CSS subpath imports present |
 | `placeholders` | No unresolved `__PROJECT_SLUG__`, `__PROJECT_NAME__`, `__PROJECT_DESCRIPTION__` in key config files                                                                                                                                                                                                                                                         |
 | `scripts`      | `ui` and `operations` `package.json` have required npm scripts                                                                                                                                                                                                                                                                                              |
 | `lib`          | `ui/src/lib/`, `lib/`, `test-utils/` exist with minimum file counts                                                                                                                                                                                                                                                                                         |

package/reference/scaffold/operations/scaffold-maintenance.md

@@ -2,6 +2,9 @@
 title: Scaffold Maintenance
 description: How scaffold documentation is organized, generated, and bundled into the SDK -- content placement map, auto-generation pipeline, and instructions for adding new scaffold docs.
 ---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
 
 # Scaffold Maintenance
 

package/reference/scaffold/operations/workflow-recipes.md

@@ -2,6 +2,9 @@
 title: Workflow Recipes
 description: Anatomy of a workflow, adapter usage, and trigger patterns -- runnable email-notification example replaces the trivial echo workflow. Resolves eval score 2/5 on workflow authoring.
 ---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
 
 # Workflow Recipes
 
@@ -32,7 +35,7 @@ config: {
 ### Contract
 
 ```typescript
-// foundations/types/index.ts -- shared with frontend
+// core/types/index.ts -- shared with frontend
 export const emailNotificationInputSchema = z.object({
   recipientEmail: z.string().email(),
   recipientName: z.string().min(1),
@@ -54,7 +57,7 @@ export type EmailNotificationOutput = z.infer<typeof emailNotificationOutputSche
 
 ```typescript
 // operations/src/email-notification/index.ts
-import { emailNotificationInputSchema, emailNotificationOutputSchema } from '@foundation/types'
+import { emailNotificationInputSchema, emailNotificationOutputSchema } from '@core/types'
 
 contract: {
   inputSchema: emailNotificationInputSchema,
@@ -64,16 +67,16 @@ contract: {
 
 **Rules:**
 
-- Define schemas in `foundations/types/index.ts` -- never inline Zod schemas in workflow files.
-- Both runtimes (frontend and platform) import from `@foundation/types`, keeping validation consistent.
-- `@foundation/types` resolves to `foundations/types/index.ts` via the tsconfig path alias.
+- Define schemas in `core/types/index.ts` -- never inline Zod schemas in workflow files.
+- Both runtimes (frontend and platform) import from `@core/types`, keeping validation consistent.
+- `@core/types` resolves to `core/types/index.ts` via the tsconfig path alias.
 
 **Entity-backed workflows:** for workflows that operate on a domain entity, reference the entity contract rather than redeclaring it.
 
 ```typescript
-// foundations/types/index.ts
+// core/types/index.ts
 import { BaseDealSchema } from '@elevasis/core/entities'
-import { DealSchema } from '@foundation/types/entities' // project-local extended version
+import { DealSchema } from '@core/types/entities' // project-local extended version
 
 export const closeDealInputSchema = z.object({
   deal: DealSchema,
@@ -83,7 +86,7 @@ export const closeDealInputSchema = z.object({
 export type CloseDealInput = z.infer<typeof closeDealInputSchema>
 ```
 
-`DealSchema` is defined in `foundations/types/entities.ts` by extending `BaseDealSchema` with project-specific metadata. See [../recipes/extend-a-base-entity.md](../recipes/extend-a-base-entity.md) for the pattern.
+`DealSchema` is defined in `core/types/entities.ts` by extending `BaseDealSchema` with project-specific metadata. See [../recipes/extend-a-base-entity.md](../recipes/extend-a-base-entity.md) for the pattern.
 
 ### Steps
 
@@ -291,7 +294,7 @@ Use this pattern in React components and hooks. `apiRequest` automatically attac
 // ui/src/features/notifications/hooks/useSendEmailNotification.ts
 import { useMutation } from '@tanstack/react-query'
 import { useApiClient } from '@/lib/hooks/useApiClient'
-import type { EmailNotificationInput, EmailNotificationOutput } from '@foundation/types'
+import type { EmailNotificationInput, EmailNotificationOutput } from '@core/types'
 
 export function useSendEmailNotification() {
   const { apiRequest } = useApiClient()
@@ -457,7 +460,7 @@ Use `runWorkflow` for project-owned workflows. This tests the workflow contract,
 import { describe, expect, it } from 'vitest'
 import { runWorkflow, mockNotifications } from '@elevasis/sdk/test-utils'
 import { emailNotification } from './index'
-import type { EmailNotificationOutput } from '@foundation/types'
+import type { EmailNotificationOutput } from '@core/types'
 
 describe('emailNotification workflow', () => {
   it('runs the notify step with a mocked notification adapter', async () => {