@elevasis/sdk 1.8.2 → 1.8.3

package/reference/scaffold/recipes/customize-organization-model.md

@@ -1,400 +1,400 @@
----
-title: Customize organization-model.ts
-description: Annotated walkthrough for customizing the organization model in template-derived projects, covering the unified feature API, surfaces, domain config, and the resolve pipeline.
----
-
-# Customize organization-model.ts
-
-`foundations/config/organization-model.ts` is the semantic contract between your UI runtime
-and your platform operations. Every feature your users can access, every nav surface they can
-navigate to, and every resource backed by a workflow is declared here. The provider reads this
-contract at startup; everything downstream -- routing, gating, nav rendering -- derives from it.
-
-This recipe walks through the file section by section. For adding a net-new feature from scratch
-(manifest, routes, gating) see [add-a-feature.md](add-a-feature.md).
-
----
-
-## Anatomy
-
-### Import and setup
-
-```ts
-import {
-  defineOrganizationModel,
-  resolveOrganizationModel,
-  type OrganizationModel,
-  type OrganizationModelSurface
-} from '@elevasis/core/organization-model'
-```
-
-Two functions and two types are all you need:
-
-- `defineOrganizationModel` -- identity helper that gives TypeScript a typed override shape.
-  Pass your override object through it; you get type-checking against `DeepPartial<OrganizationModel>`
-  without having to fill every field.
-- `resolveOrganizationModel` -- merges your override with the platform defaults and validates the
-  result through `OrganizationModelSchema`. Call once at module init; export the result.
-- `OrganizationModel` -- the fully-resolved model type (after defaults are merged in).
-- `OrganizationModelSurface` -- the surface definition type; useful when building the foundation
-  navigation surface layer (see the export pattern below).
-
----
-
-### Features array
-
-The `features` array is the sole source of truth for which capabilities the organization has
-and whether they are on or off. Each entry is an `OrganizationModelFeature` (inferred from
-`FeatureSchema`).
-
-```ts
-const foundationOrganizationModelOverride = defineOrganizationModel({
-  features: [
-    {
-      id: 'crm',                                        // stable kebab-case ID; FeatureModule.featureId must match
-      label: 'CRM',                                     // display name for nav label resolution
-      description: 'Relationship pipeline and deal management',  // optional; shown in settings UI
-      enabled: true,                                    // org-wide default; false hides from nav and blocks routes
-      color: 'blue',                                    // Mantine color token; optional
-      entityIds: ['crm.deal'],                          // logical entity types this feature owns
-      surfaceIds: ['crm.pipeline'],                     // navigation surfaces that belong to this feature
-      resourceIds: [],                                  // workflow/agent resource IDs mapped through resourceMappings
-      capabilityIds: ['crm.pipeline.manage']            // fine-grained capability strings for gating
-    },
-    // ... other features
-  ]
-})
-```
-
-Field reference:
-
-- `id` -- lowercase, kebab-case, dot-separated segments allowed (`crm`, `lead-gen`, `operations`).
-  This value must exactly match the `featureId` on any `FeatureModule` manifest that gates against
-  this feature. The provider throws at startup if a manifest references an unknown feature ID.
-- `label` -- shown in nav when no manifest override is provided. Keep short.
-- `description` -- optional. Appears in membership/settings surfaces.
-- `enabled` -- `false` suppresses the nav entry and triggers `FeatureGuard` redirects. Default is
-  `true` per the schema. To ship a feature but keep it off by default, set this to `false` here
-  and enable it per-org through membership config.
-- `color` -- any Mantine color token string (`blue`, `cyan`, `violet`, `orange`). Optional.
-- `icon` -- icon name string. Optional. The foundation layer re-maps this via `FoundationSurfaceIcon`.
-- `entityIds` -- dot-namespaced entity type IDs (`crm.deal`, `leadgen.list`). Purely semantic; used
-  by the organization graph to classify nodes.
-- `surfaceIds` -- must reference IDs declared in `navigation.surfaces`. Bidirectional: the schema
-  validates that every surface listed here also lists this feature in its own `featureIds`.
-- `resourceIds` -- must reference `resourceId` values in `resourceMappings`. Bidirectional: the
-  schema validates the reverse link exists. Leave empty until you have actual resource mappings.
-- `capabilityIds` -- dot-namespaced strings (`crm.pipeline.manage`). Used by `FeatureGuard` and
-  surface-level access checks. No central registry; name them descriptively.
-
-The 7 platform defaults are: `crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`,
-`seo`. The template's `features` array replaces the defaults wholesale (arrays are not merged field
-by field -- see Resolve Behavior below).
-
----
-
-### Navigation surfaces
-
-Surfaces are the navigable pages of your application. Declare them under `navigation.surfaces`.
-
-```ts
-navigation: {
-  defaultSurfaceId: 'operations.organization-graph',   // surface shown on first load
-  surfaces: [
-    {
-      id: 'crm.pipeline',           // stable ID; referenced by feature.surfaceIds and group.surfaceIds
-      label: 'CRM',                 // nav label
-      path: '/crm',                 // TanStack Router path prefix
-      surfaceType: 'graph',         // 'page' | 'dashboard' | 'graph' | 'detail' | 'list' | 'settings'
-      featureId: 'crm',             // primary owning feature (optional but conventional)
-      featureIds: ['crm'],          // all features this surface belongs to (bidirectional with feature.surfaceIds)
-      entityIds: ['crm.deal'],      // entity types rendered on this surface
-      resourceIds: [],              // resource IDs rendered on this surface (from resourceMappings)
-      capabilityIds: ['crm.pipeline.manage']  // capabilities required to access this surface
-    }
-  ]
-}
-```
-
-Surface field notes:
-
-- `surfaceType` -- drives how the organization graph classifies and renders the surface node.
-  Use `graph` for pipeline/topology views, `list` for index pages, `settings` for settings pages.
-- `featureId` vs `featureIds` -- `featureId` is the single primary owner (optional). `featureIds`
-  is the bidirectional array that the schema validates against. In practice, set both to the same
-  single value for most surfaces.
-- `parentId` -- optional. Lets you declare a surface as a child of another (for nested nav or
-  detail surfaces). Must reference a declared surface ID.
-- Bidirectional constraint: if `crm.pipeline` is in `feature.surfaceIds`, then `crm.pipeline`'s
-  `featureIds` must include `crm`. The schema parse throws if either side is missing.
-
-The template adds a `FoundationNavigationSurface` extension type that augments the core surface
-with a typed `icon` field (`FoundationSurfaceIcon`). This is used by the foundation nav layer to
-render icon components in the sidebar.
-
----
-
-### Resources and resourceMappings
-
-Resource mappings connect platform workflows and agents to features and surfaces. They are optional
-until you have deployed resources to map.
-
-```ts
-resourceMappings: [
-  {
-    id: 'my-mapping',                      // unique within resourceMappings
-    resourceId: 'my-lead-scraper-workflow', // the deployed resource ID from operations/
-    resourceType: 'workflow',              // 'workflow' | 'agent' | 'trigger' | 'integration' | 'external' | 'human_checkpoint'
-    label: 'Lead Scraper',
-    featureIds: ['lead-gen'],              // bidirectional: feature.resourceIds must include resourceId
-    entityIds: ['leadgen.company'],
-    surfaceIds: ['lead-gen.lists'],        // bidirectional: surface.resourceIds must include resourceId
-    capabilityIds: []
-  }
-]
-```
-
-The schema enforces full bidirectionality. If you add a resource mapping with `featureIds: ['lead-gen']`
-then the `lead-gen` feature entry must include the `resourceId` in its own `resourceIds`. Both sides
-must be consistent or `resolveOrganizationModel` throws at startup. See [add-a-resource.md](add-a-resource.md)
-for the full resource authoring workflow.
-
----
-
-### Domain-specific config
-
-The `sales`, `prospecting`, and `projects` top-level keys configure pipeline stages, entity ID bindings,
-and status vocabularies for those domains. These are consumed by the platform adapters and UI
-components -- they are not just labels.
-
-```ts
-sales: {
-  entityId: 'crm.deal',
-  defaultPipelineId: 'default',
-  pipelines: [
-    {
-      id: 'default',
-      label: 'Default Pipeline',
-      entityId: 'crm.deal',
-      stages: [
-        { id: 'interested', label: 'Interested', color: 'blue', order: 1, semanticClass: 'open', surfaceIds: ['crm.pipeline'], resourceIds: [] },
-        { id: 'closed_won', label: 'Closed Won', color: 'green', order: 4, semanticClass: 'closed_won', surfaceIds: ['crm.pipeline'], resourceIds: [] }
-        // ... additional stages
-      ]
-    }
-  ]
-},
-prospecting: {
-  listEntityId: 'leadgen.list',
-  companyEntityId: 'leadgen.company',
-  contactEntityId: 'leadgen.contact',
-  companyStages: [
-    { id: 'populated', label: 'Populated', order: 1 },
-    { id: 'qualified', label: 'Qualified', order: 3 }
-  ],
-  contactStages: [
-    { id: 'discovered', label: 'Discovered', order: 1 },
-    { id: 'uploaded', label: 'Uploaded', order: 4 }
-  ]
-},
-projects: {
-  projectEntityId: 'delivery.project',
-  milestoneEntityId: 'delivery.milestone',
-  taskEntityId: 'delivery.task',
-  projectStatuses: [ /* ... */ ],
-  milestoneStatuses: [ /* ... */ ],
-  taskStatuses: [ /* ... */ ]
-}
-```
-
-`semanticClass` on sales pipeline stages is significant: the platform uses `closed_won`, `closed_lost`,
-`nurturing`, `open`, and `active` for funnel analytics and workflow triggers. Do not rename these
-to arbitrary strings.
-
----
-
-### Export pattern
-
-The template exports two models: `canonicalOrganizationModel` for the provider (machine-facing)
-and `organizationModel` for the foundation nav layer (UI-facing with the icon-augmented surface type).
-
-```ts
-const resolvedOrganizationModel = resolveOrganizationModel(foundationOrganizationModelOverride)
-
-// Passed to ElevasisFeaturesProvider in ui/src/routes/__root.tsx
-export const canonicalOrganizationModel: OrganizationModel = resolvedOrganizationModel
-
-// Used by foundation nav components that need the augmented FoundationNavigationSurface type
-export const organizationModel: FoundationOrganizationModel = {
-  ...canonicalOrganizationModel,
-  navigation: {
-    defaultSurfaceId: 'operations',
-    homeLabel,
-    quickAccessSurfaceIds: [...quickAccessSurfaceIds],
-    surfaces: navigationSurfaces   // FoundationNavigationSurface[] with icon field
-  }
-}
-```
-
-The `requireCoreSurface` helper (defined in the template file) throws at startup if a surface ID
-declared in the foundations layer is not present in the resolved model. Use it to catch mismatches
-early rather than seeing silent `undefined` in the nav at runtime.
-
----
-
-## Common Customizations
-
-### Adding a new feature
-
-Add a new entry to the `features` array:
-
-```ts
-{
-  id: 'analytics',
-  label: 'Analytics',
-  enabled: false,        // start disabled; enable per-org when ready
-  entityIds: [],
-  surfaceIds: [],
-  resourceIds: [],
-  capabilityIds: []
-}
-```
-
-Then proceed with the full manifest, route, and gating steps in [add-a-feature.md](add-a-feature.md).
-The org model change above is Step 2 of that recipe.
-
----
-
-### Disabling a default feature
-
-Set `enabled: false` on the feature entry. The nav item disappears and `FeatureGuard` blocks
-direct URL access:
-
-```ts
-{
-  id: 'seo',
-  label: 'SEO',
-  enabled: false,        // nav item hidden, routes redirect to home
-  entityIds: [],
-  surfaceIds: [],
-  resourceIds: [],
-  capabilityIds: []
-}
-```
-
-The `seo` feature ships disabled by default. If your project does not use `monitoring` either,
-set it to `enabled: false` as well.
-
----
-
-### Adding entities to a feature
-
-Entity IDs are dot-namespaced strings (`domain.type`). Add to both the feature and any surfaces
-that display those entities:
-
-```ts
-// In features array:
-{
-  id: 'crm',
-  entityIds: ['crm.deal', 'crm.contact'],   // added crm.contact
-  // ...
-}
-
-// In the surface that shows contacts:
-{
-  id: 'crm.pipeline',
-  entityIds: ['crm.deal', 'crm.contact'],   // mirror the addition
-  // ...
-}
-```
-
-Entity IDs inform the organization graph node taxonomy. They do not require registration anywhere
-else in the platform; just keep them consistent across feature and surface declarations.
-
----
-
-### Customizing feature labels and descriptions
-
-Edit `label` and `description` directly on the feature entry. These values propagate to nav
-label resolution and the settings UI:
-
-```ts
-{
-  id: 'lead-gen',
-  label: 'Prospecting',              // override the default 'Lead Gen' label
-  description: 'Find and qualify new opportunities',
-  // ...
-}
-```
-
-If the `FeatureModule` manifest also declares a `navEntry.label`, the manifest label wins in the
-nav sidebar. The feature `label` is the fallback when no manifest override exists.
-
----
-
-### Adding surfaces
-
-Declare the surface under `navigation.surfaces` and cross-reference it from the owning feature.
-Both sides must be consistent (schema validates bidirectionality):
-
-```ts
-// In navigation.surfaces:
-{
-  id: 'analytics.dashboard',
-  label: 'Analytics',
-  path: '/analytics',
-  surfaceType: 'dashboard',
-  featureId: 'analytics',
-  featureIds: ['analytics'],
-  entityIds: [],
-  resourceIds: [],
-  capabilityIds: ['analytics.view']
-}
-
-// In the analytics feature entry:
-{
-  id: 'analytics',
-  surfaceIds: ['analytics.dashboard'],   // must reference the surface ID above
-  capabilityIds: ['analytics.view'],
-  // ...
-}
-```
-
----
-
-## How It Connects
-
-The organization model flows through the runtime in one direction:
-
-1. `foundations/config/organization-model.ts` calls `resolveOrganizationModel` at module load.
-   The resolved `canonicalOrganizationModel` is exported.
-2. `ui/src/routes/__root.tsx` imports `canonicalOrganizationModel` and passes it to
-   `ElevasisFeaturesProvider` along with the `FEATURE_MANIFESTS` array.
-3. `ElevasisFeaturesProvider` validates each manifest's `featureId` against the model's `features`
-   array. Unknown `featureId` values throw at startup.
-4. At runtime, the provider uses `features[n].enabled` to decide which nav entries to show.
-   `FeatureGuard` reads the same value to allow or block route access.
-5. The organization graph reads `features`, `navigation.surfaces`, `entityIds`, and `resourceMappings`
-   to build the operational topology visualization.
-
-The contract flows one way: model defines, runtime reads. No part of the UI runtime writes back
-to the model.
-
----
-
-## Resolve Behavior
-
-`resolveOrganizationModel(override)` does the following:
-
-1. Deep-merges the override onto `DEFAULT_ORGANIZATION_MODEL`. Plain objects are merged key by key.
-   **Arrays are replaced wholesale** -- if you supply `features: [...]`, your array replaces the
-   defaults entirely, not appends to them.
-2. If you override `navigation.surfaces` without overriding `navigation.groups`, the resolver
-   automatically filters out any groups whose `surfaceIds` reference surfaces that no longer exist
-   in your override. This prevents dangling group references from causing a parse failure.
-3. Parses the merged result through `OrganizationModelSchema`. Any bidirectional reference
-   inconsistency (feature \<-\> surface, surface \<-\> resource mapping) throws a Zod validation
-   error with a specific path and message pointing to the offending reference.
-
-When you see a startup error from `resolveOrganizationModel`, read the Zod issue path carefully.
-It will identify which specific field and array index contains the broken reference.
+---
+title: Customize organization-model.ts
+description: Annotated walkthrough for customizing the organization model in template-derived projects, covering the unified feature API, surfaces, domain config, and the resolve pipeline.
+---
+
+# Customize organization-model.ts
+
+`foundations/config/organization-model.ts` is the semantic contract between your UI runtime
+and your platform operations. Every feature your users can access, every nav surface they can
+navigate to, and every resource backed by a workflow is declared here. The provider reads this
+contract at startup; everything downstream -- routing, gating, nav rendering -- derives from it.
+
+This recipe walks through the file section by section. For adding a net-new feature from scratch
+(manifest, routes, gating) see [add-a-feature.md](add-a-feature.md).
+
+---
+
+## Anatomy
+
+### Import and setup
+
+```ts
+import {
+  defineOrganizationModel,
+  resolveOrganizationModel,
+  type OrganizationModel,
+  type OrganizationModelSurface
+} from '@elevasis/core/organization-model'
+```
+
+Two functions and two types are all you need:
+
+- `defineOrganizationModel` -- identity helper that gives TypeScript a typed override shape.
+  Pass your override object through it; you get type-checking against `DeepPartial<OrganizationModel>`
+  without having to fill every field.
+- `resolveOrganizationModel` -- merges your override with the platform defaults and validates the
+  result through `OrganizationModelSchema`. Call once at module init; export the result.
+- `OrganizationModel` -- the fully-resolved model type (after defaults are merged in).
+- `OrganizationModelSurface` -- the surface definition type; useful when building the foundation
+  navigation surface layer (see the export pattern below).
+
+---
+
+### Features array
+
+The `features` array is the sole source of truth for which capabilities the organization has
+and whether they are on or off. Each entry is an `OrganizationModelFeature` (inferred from
+`FeatureSchema`).
+
+```ts
+const foundationOrganizationModelOverride = defineOrganizationModel({
+  features: [
+    {
+      id: 'crm',                                        // stable kebab-case ID; FeatureModule.featureId must match
+      label: 'CRM',                                     // display name for nav label resolution
+      description: 'Relationship pipeline and deal management',  // optional; shown in settings UI
+      enabled: true,                                    // org-wide default; false hides from nav and blocks routes
+      color: 'blue',                                    // Mantine color token; optional
+      entityIds: ['crm.deal'],                          // logical entity types this feature owns
+      surfaceIds: ['crm.pipeline'],                     // navigation surfaces that belong to this feature
+      resourceIds: [],                                  // workflow/agent resource IDs mapped through resourceMappings
+      capabilityIds: ['crm.pipeline.manage']            // fine-grained capability strings for gating
+    },
+    // ... other features
+  ]
+})
+```
+
+Field reference:
+
+- `id` -- lowercase, kebab-case, dot-separated segments allowed (`crm`, `lead-gen`, `operations`).
+  This value must exactly match the `featureId` on any `FeatureModule` manifest that gates against
+  this feature. The provider throws at startup if a manifest references an unknown feature ID.
+- `label` -- shown in nav when no manifest override is provided. Keep short.
+- `description` -- optional. Appears in membership/settings surfaces.
+- `enabled` -- `false` suppresses the nav entry and triggers `FeatureGuard` redirects. Default is
+  `true` per the schema. To ship a feature but keep it off by default, set this to `false` here
+  and enable it per-org through membership config.
+- `color` -- any Mantine color token string (`blue`, `cyan`, `violet`, `orange`). Optional.
+- `icon` -- icon name string. Optional. The foundation layer re-maps this via `FoundationSurfaceIcon`.
+- `entityIds` -- dot-namespaced entity type IDs (`crm.deal`, `leadgen.list`). Purely semantic; used
+  by the organization graph to classify nodes.
+- `surfaceIds` -- must reference IDs declared in `navigation.surfaces`. Bidirectional: the schema
+  validates that every surface listed here also lists this feature in its own `featureIds`.
+- `resourceIds` -- must reference `resourceId` values in `resourceMappings`. Bidirectional: the
+  schema validates the reverse link exists. Leave empty until you have actual resource mappings.
+- `capabilityIds` -- dot-namespaced strings (`crm.pipeline.manage`). Used by `FeatureGuard` and
+  surface-level access checks. No central registry; name them descriptively.
+
+The 7 platform defaults are: `crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`,
+`seo`. The template's `features` array replaces the defaults wholesale (arrays are not merged field
+by field -- see Resolve Behavior below).
+
+---
+
+### Navigation surfaces
+
+Surfaces are the navigable pages of your application. Declare them under `navigation.surfaces`.
+
+```ts
+navigation: {
+  defaultSurfaceId: 'operations.organization-graph',   // surface shown on first load
+  surfaces: [
+    {
+      id: 'crm.pipeline',           // stable ID; referenced by feature.surfaceIds and group.surfaceIds
+      label: 'CRM',                 // nav label
+      path: '/crm',                 // TanStack Router path prefix
+      surfaceType: 'graph',         // 'page' | 'dashboard' | 'graph' | 'detail' | 'list' | 'settings'
+      featureId: 'crm',             // primary owning feature (optional but conventional)
+      featureIds: ['crm'],          // all features this surface belongs to (bidirectional with feature.surfaceIds)
+      entityIds: ['crm.deal'],      // entity types rendered on this surface
+      resourceIds: [],              // resource IDs rendered on this surface (from resourceMappings)
+      capabilityIds: ['crm.pipeline.manage']  // capabilities required to access this surface
+    }
+  ]
+}
+```
+
+Surface field notes:
+
+- `surfaceType` -- drives how the organization graph classifies and renders the surface node.
+  Use `graph` for pipeline/topology views, `list` for index pages, `settings` for settings pages.
+- `featureId` vs `featureIds` -- `featureId` is the single primary owner (optional). `featureIds`
+  is the bidirectional array that the schema validates against. In practice, set both to the same
+  single value for most surfaces.
+- `parentId` -- optional. Lets you declare a surface as a child of another (for nested nav or
+  detail surfaces). Must reference a declared surface ID.
+- Bidirectional constraint: if `crm.pipeline` is in `feature.surfaceIds`, then `crm.pipeline`'s
+  `featureIds` must include `crm`. The schema parse throws if either side is missing.
+
+The template adds a `FoundationNavigationSurface` extension type that augments the core surface
+with a typed `icon` field (`FoundationSurfaceIcon`). This is used by the foundation nav layer to
+render icon components in the sidebar.
+
+---
+
+### Resources and resourceMappings
+
+Resource mappings connect platform workflows and agents to features and surfaces. They are optional
+until you have deployed resources to map.
+
+```ts
+resourceMappings: [
+  {
+    id: 'my-mapping',                      // unique within resourceMappings
+    resourceId: 'my-lead-scraper-workflow', // the deployed resource ID from operations/
+    resourceType: 'workflow',              // 'workflow' | 'agent' | 'trigger' | 'integration' | 'external' | 'human_checkpoint'
+    label: 'Lead Scraper',
+    featureIds: ['lead-gen'],              // bidirectional: feature.resourceIds must include resourceId
+    entityIds: ['leadgen.company'],
+    surfaceIds: ['lead-gen.lists'],        // bidirectional: surface.resourceIds must include resourceId
+    capabilityIds: []
+  }
+]
+```
+
+The schema enforces full bidirectionality. If you add a resource mapping with `featureIds: ['lead-gen']`
+then the `lead-gen` feature entry must include the `resourceId` in its own `resourceIds`. Both sides
+must be consistent or `resolveOrganizationModel` throws at startup. See [add-a-resource.md](add-a-resource.md)
+for the full resource authoring workflow.
+
+---
+
+### Domain-specific config
+
+The `sales`, `prospecting`, and `projects` top-level keys configure pipeline stages, entity ID bindings,
+and status vocabularies for those domains. These are consumed by the platform adapters and UI
+components -- they are not just labels.
+
+```ts
+sales: {
+  entityId: 'crm.deal',
+  defaultPipelineId: 'default',
+  pipelines: [
+    {
+      id: 'default',
+      label: 'Default Pipeline',
+      entityId: 'crm.deal',
+      stages: [
+        { id: 'interested', label: 'Interested', color: 'blue', order: 1, semanticClass: 'open', surfaceIds: ['crm.pipeline'], resourceIds: [] },
+        { id: 'closed_won', label: 'Closed Won', color: 'green', order: 4, semanticClass: 'closed_won', surfaceIds: ['crm.pipeline'], resourceIds: [] }
+        // ... additional stages
+      ]
+    }
+  ]
+},
+prospecting: {
+  listEntityId: 'leadgen.list',
+  companyEntityId: 'leadgen.company',
+  contactEntityId: 'leadgen.contact',
+  companyStages: [
+    { id: 'populated', label: 'Populated', order: 1 },
+    { id: 'qualified', label: 'Qualified', order: 3 }
+  ],
+  contactStages: [
+    { id: 'discovered', label: 'Discovered', order: 1 },
+    { id: 'uploaded', label: 'Uploaded', order: 4 }
+  ]
+},
+projects: {
+  projectEntityId: 'delivery.project',
+  milestoneEntityId: 'delivery.milestone',
+  taskEntityId: 'delivery.task',
+  projectStatuses: [ /* ... */ ],
+  milestoneStatuses: [ /* ... */ ],
+  taskStatuses: [ /* ... */ ]
+}
+```
+
+`semanticClass` on sales pipeline stages is significant: the platform uses `closed_won`, `closed_lost`,
+`nurturing`, `open`, and `active` for funnel analytics and workflow triggers. Do not rename these
+to arbitrary strings.
+
+---
+
+### Export pattern
+
+The template exports two models: `canonicalOrganizationModel` for the provider (machine-facing)
+and `organizationModel` for the foundation nav layer (UI-facing with the icon-augmented surface type).
+
+```ts
+const resolvedOrganizationModel = resolveOrganizationModel(foundationOrganizationModelOverride)
+
+// Passed to ElevasisFeaturesProvider in ui/src/routes/__root.tsx
+export const canonicalOrganizationModel: OrganizationModel = resolvedOrganizationModel
+
+// Used by foundation nav components that need the augmented FoundationNavigationSurface type
+export const organizationModel: FoundationOrganizationModel = {
+  ...canonicalOrganizationModel,
+  navigation: {
+    defaultSurfaceId: 'operations',
+    homeLabel,
+    quickAccessSurfaceIds: [...quickAccessSurfaceIds],
+    surfaces: navigationSurfaces   // FoundationNavigationSurface[] with icon field
+  }
+}
+```
+
+The `requireCoreSurface` helper (defined in the template file) throws at startup if a surface ID
+declared in the foundations layer is not present in the resolved model. Use it to catch mismatches
+early rather than seeing silent `undefined` in the nav at runtime.
+
+---
+
+## Common Customizations
+
+### Adding a new feature
+
+Add a new entry to the `features` array:
+
+```ts
+{
+  id: 'analytics',
+  label: 'Analytics',
+  enabled: false,        // start disabled; enable per-org when ready
+  entityIds: [],
+  surfaceIds: [],
+  resourceIds: [],
+  capabilityIds: []
+}
+```
+
+Then proceed with the full manifest, route, and gating steps in [add-a-feature.md](add-a-feature.md).
+The org model change above is Step 2 of that recipe.
+
+---
+
+### Disabling a default feature
+
+Set `enabled: false` on the feature entry. The nav item disappears and `FeatureGuard` blocks
+direct URL access:
+
+```ts
+{
+  id: 'seo',
+  label: 'SEO',
+  enabled: false,        // nav item hidden, routes redirect to home
+  entityIds: [],
+  surfaceIds: [],
+  resourceIds: [],
+  capabilityIds: []
+}
+```
+
+The `seo` feature ships disabled by default. If your project does not use `monitoring` either,
+set it to `enabled: false` as well.
+
+---
+
+### Adding entities to a feature
+
+Entity IDs are dot-namespaced strings (`domain.type`). Add to both the feature and any surfaces
+that display those entities:
+
+```ts
+// In features array:
+{
+  id: 'crm',
+  entityIds: ['crm.deal', 'crm.contact'],   // added crm.contact
+  // ...
+}
+
+// In the surface that shows contacts:
+{
+  id: 'crm.pipeline',
+  entityIds: ['crm.deal', 'crm.contact'],   // mirror the addition
+  // ...
+}
+```
+
+Entity IDs inform the organization graph node taxonomy. They do not require registration anywhere
+else in the platform; just keep them consistent across feature and surface declarations.
+
+---
+
+### Customizing feature labels and descriptions
+
+Edit `label` and `description` directly on the feature entry. These values propagate to nav
+label resolution and the settings UI:
+
+```ts
+{
+  id: 'lead-gen',
+  label: 'Prospecting',              // override the default 'Lead Gen' label
+  description: 'Find and qualify new opportunities',
+  // ...
+}
+```
+
+If the `FeatureModule` manifest also declares a `navEntry.label`, the manifest label wins in the
+nav sidebar. The feature `label` is the fallback when no manifest override exists.
+
+---
+
+### Adding surfaces
+
+Declare the surface under `navigation.surfaces` and cross-reference it from the owning feature.
+Both sides must be consistent (schema validates bidirectionality):
+
+```ts
+// In navigation.surfaces:
+{
+  id: 'analytics.dashboard',
+  label: 'Analytics',
+  path: '/analytics',
+  surfaceType: 'dashboard',
+  featureId: 'analytics',
+  featureIds: ['analytics'],
+  entityIds: [],
+  resourceIds: [],
+  capabilityIds: ['analytics.view']
+}
+
+// In the analytics feature entry:
+{
+  id: 'analytics',
+  surfaceIds: ['analytics.dashboard'],   // must reference the surface ID above
+  capabilityIds: ['analytics.view'],
+  // ...
+}
+```
+
+---
+
+## How It Connects
+
+The organization model flows through the runtime in one direction:
+
+1. `foundations/config/organization-model.ts` calls `resolveOrganizationModel` at module load.
+   The resolved `canonicalOrganizationModel` is exported.
+2. `ui/src/routes/__root.tsx` imports `canonicalOrganizationModel` and passes it to
+   `ElevasisFeaturesProvider` along with the `FEATURE_MANIFESTS` array.
+3. `ElevasisFeaturesProvider` validates each manifest's `featureId` against the model's `features`
+   array. Unknown `featureId` values throw at startup.
+4. At runtime, the provider uses `features[n].enabled` to decide which nav entries to show.
+   `FeatureGuard` reads the same value to allow or block route access.
+5. The organization graph reads `features`, `navigation.surfaces`, `entityIds`, and `resourceMappings`
+   to build the operational topology visualization.
+
+The contract flows one way: model defines, runtime reads. No part of the UI runtime writes back
+to the model.
+
+---
+
+## Resolve Behavior
+
+`resolveOrganizationModel(override)` does the following:
+
+1. Deep-merges the override onto `DEFAULT_ORGANIZATION_MODEL`. Plain objects are merged key by key.
+   **Arrays are replaced wholesale** -- if you supply `features: [...]`, your array replaces the
+   defaults entirely, not appends to them.
+2. If you override `navigation.surfaces` without overriding `navigation.groups`, the resolver
+   automatically filters out any groups whose `surfaceIds` reference surfaces that no longer exist
+   in your override. This prevents dangling group references from causing a parse failure.
+3. Parses the merged result through `OrganizationModelSchema`. Any bidirectional reference
+   inconsistency (feature \<-\> surface, surface \<-\> resource mapping) throws a Zod validation
+   error with a specific path and message pointing to the offending reference.
+
+When you see a startup error from `resolveOrganizationModel`, read the Zod issue path carefully.
+It will identify which specific field and array index contains the broken reference.