@elevasis/sdk 1.9.0 → 1.11.0

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

@@ -1,400 +1,141 @@
----
-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 flat Organization Model in template-derived projects.
+---
+
+# Customize organization-model.ts
+
+`core/config/organization-model.ts` is the semantic contract between the UI shell and platform operations. The shell reads one flat feature list, derives hierarchy from dotted IDs, and binds resources through graph links declared on resource metadata.
+
+## Imports
+
+```ts
+import {
+  createFoundationOrganizationModel,
+  defineOrganizationModel,
+  type OrganizationModel
+} from '@elevasis/core/organization-model'
+```
+
+- `defineOrganizationModel` gives a typed override shape.
+- `createFoundationOrganizationModel` resolves defaults and returns the canonical model plus UI-facing helpers.
+- `OrganizationModel` is the fully resolved model type.
+
+## Features
+
+The `features` array is the source of truth for navigation, labels, enabled state, admin visibility, and development-only visibility.
+
+```ts
+const override = defineOrganizationModel({
+  features: [
+    {
+      id: 'dashboard',
+      label: 'Dashboard',
+      enabled: true,
+      path: '/',
+      icon: 'dashboard',
+      uiPosition: 'sidebar-primary'
+    },
+    {
+      id: 'sales',
+      label: 'Sales',
+      enabled: true,
+      icon: 'briefcase',
+      uiPosition: 'sidebar-primary'
+    },
+    {
+      id: 'sales.crm',
+      label: 'CRM',
+      enabled: true,
+      path: '/crm'
+    },
+    {
+      id: 'admin',
+      label: 'Admin',
+      enabled: true,
+      path: '/admin',
+      uiPosition: 'sidebar-bottom',
+      requiresAdmin: true
+    }
+  ]
+})
+```
+
+Feature field reference:
+
+- `id` -- lowercase dotted path. Parent features are inferred from prefix segments.
+- `label` -- sidebar and breadcrumb label.
+- `description` -- optional settings/help text.
+- `enabled` -- organization default.
+- `path` -- route path for leaf nodes. Containers omit it.
+- `icon` and `color` -- optional display metadata.
+- `uiPosition` -- `sidebar-primary` or `sidebar-bottom`; descendants inherit it.
+- `requiresAdmin` -- hides the node for non-admin members; descendants inherit it.
+- `devOnly` -- hides the node outside development contexts; descendants inherit it.
+
+## Resource Binding
+
+Resources do not live in `OrganizationModel`. Workflows, agents, triggers, integrations, and external resources declare semantic graph links in their 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'
+}
+```
+
+Use kind-prefixed graph IDs for cross-collection links:
+
+- `feature:sales.crm`
+- `integration:instantly`
+- `resource:lead-import`
+- `capability:operations.queue.review`
+
+`category` is one of `production`, `diagnostic`, `internal`, or `testing`.
+
+## Domain Config
+
+The `sales`, `prospecting`, and `projects` top-level keys configure business semantics such as pipeline stages, entity IDs, and status vocabularies. They are not shell navigation.
+
+```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' },
+        { id: 'closed_won', label: 'Closed Won', color: 'green', order: 4, semanticClass: 'closed_won' }
+      ]
+    }
+  ]
+}
+```
+
+Keep `semanticClass` values stable; platform analytics and triggers depend on them.
+
+## Export Pattern
+
+```ts
+const foundation = createFoundationOrganizationModel(override)
+
+export const canonicalOrganizationModel: OrganizationModel = foundation.canonical
+export const organizationModel = foundation.model
+export const { getOrganizationSurface } = foundation
+```
+
+Pass `canonicalOrganizationModel` to `ElevasisFeaturesProvider` in `ui/src/routes/__root.tsx`.
+
+## Resolve Behavior
+
+`createFoundationOrganizationModel(override)` resolves defaults, validates feature hierarchy, and exposes helper functions used by the shell. Arrays are replaced wholesale, so if you provide `features`, include every feature the app should expose.
+
+Validation catches duplicate feature IDs, missing parent containers, invalid graph IDs, and invalid sidebar positions.