@elevasis/sdk 1.5.3 → 1.5.5

package/reference/scaffold/reference/contracts.md

@@ -1,3 +1,4 @@
+<!-- Auto-generated on 2026-04-19T10:47:49.477Z by scripts/monorepo/generate-scaffold-contracts.js -->
 ---
 title: Reference Contracts
 description: Auto-generated TypeScript contracts for SDK consumers. Do not edit manually.
@@ -37,16 +38,10 @@ export type OrganizationModelLeadGen = z.infer<typeof OrganizationModelLeadGenSc
 export type OrganizationModelDelivery = z.infer<typeof OrganizationModelDeliverySchema>
 ```
 
-### `OrganizationModelFeatures`
+### `OrganizationModelFeature`
 
 ```typescript
-export type OrganizationModelFeatures = z.infer<typeof OrganizationModelFeaturesSchema>
-```
-
-### `OrganizationModelFeatureKey`
-
-```typescript
-export type OrganizationModelFeatureKey = z.infer<typeof FeatureKeySchema>
+export type OrganizationModelFeature = z.infer<typeof FeatureSchema>
 ```
 
 ### `OrganizationModelNavigation`
@@ -61,12 +56,6 @@ export type OrganizationModelNavigation = z.infer<typeof OrganizationModelNaviga
 export type OrganizationModelSurface = z.infer<typeof SurfaceDefinitionSchema>
 ```
 
-### `OrganizationModelSemanticDomain`
-
-```typescript
-export type OrganizationModelSemanticDomain = z.infer<typeof SemanticDomainSchema>
-```
-
 ### `OrganizationModelResourceMapping`
 
 ```typescript
@@ -76,11 +65,7 @@ export type OrganizationModelResourceMapping = z.infer<typeof ResourceMappingSch
 ### `DeepPartial`
 
 ```typescript
-export type DeepPartial<T> = T extends Array<infer U>
-  ? Array<DeepPartial<U>>
-  : T extends object
-    ? { [K in keyof T]?: DeepPartial<T[K]> }
-    : T
+export type DeepPartial<T> = T extends Array<infer U> ? Array<DeepPartial<U>> : T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
 ```
 
 ## Feature System
@@ -121,15 +106,10 @@ export type FeatureSidebarComponent = ComponentType
 
 ```typescript
 export interface FeatureModule {
-  /** Unique stable identifier for this feature (e.g. `'crm'`, `'delivery'`). */
+  /** Unique stable identifier for this feature (e.g. `'crm'`, `'projects'`). */
   key: string
-  /** Feature key used for access-flag gating in the organization model. */
-  accessFeatureKey: OrganizationModelFeatureKey
-  /**
-   * Semantic domain identifiers contributed by this feature.
-   * Merged with surface-derived domain IDs during resolution.
-   */
-  domainIds?: OrganizationModelSemanticDomain['id'][]
+  /** Feature ID used for access-flag gating — must match the `id` of a feature in the organization model. */
+  featureId: string
   /**
    * Capability identifiers contributed by this feature.
    * Merged into `ResolvedFeatureSemantics.capabilityIds` at resolution time.
@@ -156,7 +136,7 @@ export interface FeatureModule {
 
 ```typescript
 export interface ResolvedFeatureAccess {
-  featureKey: string
+  featureId: string
   enabled: boolean
 }
 ```
@@ -165,7 +145,6 @@ export interface ResolvedFeatureAccess {
 
 ```typescript
 export interface ResolvedFeatureSemantics {
-  domainIds: OrganizationModelSemanticDomain['id'][]
   capabilityIds: string[]
   surfaceIds: string[]
   surfaces: OrganizationModelSurface[]
@@ -199,7 +178,7 @@ export type ShellNavSource = 'app' | 'feature'
 export interface ResolvedShellNavItem extends FeatureNavEntry {
   placement: ShellNavPlacement
   source: ShellNavSource
-  accessFeatureKey?: string
+  featureId?: string
 }
 ```
 
@@ -262,7 +241,7 @@ export interface OrganizationGraphContextValue {
   surfaceId?: string
   surfacePath?: string
   surfaceType?: OrganizationModelSurface['surfaceType']
-  featureKey?: OrganizationModelFeatureKey
+  featureId?: string
 }
 ```
 
@@ -500,7 +479,7 @@ export interface ResourceList {
 
 ```typescript
 /** Webhook provider identifiers */
-export type WebhookProviderType = 'cal-com' | 'stripe' | 'signature-api' | 'instantly' | 'apify'
+export type WebhookProviderType = 'cal-com' | 'stripe' | 'signature-api' | 'instantly' | 'apify' | 'test'
 
 /** Webhook trigger configuration */
 ```

package/reference/scaffold/reference/feature-registry.md

@@ -7,24 +7,25 @@ description: Auto-generated catalog of registered feature manifests. Do not edit
 
 ## Registered Feature Manifests
 
-| Feature Key | Access Key | Nav Label | Domains | Routes |
+| Feature Key | Feature ID | Nav Label | Domains | Routes |
 | --- | --- | --- | --- | --- |
-| `crm` | `acquisition` | CRM | crm | /crm |
-| `delivery` | `delivery` | Projects | delivery | /projects |
-| `lead-gen` | `acquisition` | Lead Gen | lead-gen | /lead-gen |
+| `crm` | `crm` | CRM | — | /crm |
+| `delivery` | `—` | Projects | — | /projects |
+| `lead-gen` | `lead-gen` | Lead Gen | — | /lead-gen |
 | `monitoring` | `monitoring` | Monitoring | — | — |
-| `operations` | `operations` | Operations | operations | /operations |
+| `operations` | `operations` | Operations | — | /operations |
 | `seo` | `seo` | — | — | /seo |
 | `settings` | `settings` | Settings | — | — |
 
 > **Note:** `auth` and `dashboard` are not in the registry — they are app-shell concerns, not gated features.
 
-## OrganizationModelFeatureKey Values
+## Default Feature IDs
 
-Values defined in `FeatureKeySchema` (`packages/core/src/organization-model/domains/features.ts`):
+Feature IDs defined in `DEFAULT_ORGANIZATION_MODEL.features` (`packages/core/src/organization-model/defaults.ts`):
 
 ```typescript
-type OrganizationModelFeatureKey = 'acquisition' | 'delivery' | 'operations' | 'monitoring' | 'settings' | 'seo' | 'calibration'
+// FeatureSchema: { id, label, enabled, color?, icon?, entityIds, surfaceIds, resourceIds, capabilityIds }
+type DefaultFeatureId = 
 ```
 
-These are the valid values for `accessFeatureKey` in a `FeatureModule` manifest and for feature-flag gating in the organization model.
+These are the built-in feature IDs. The `featureId` field on a `FeatureModule` manifest must match the `id` of a feature in the organization model to enable access-flag gating.

package/reference/scaffold/reference/glossary.md

@@ -13,7 +13,7 @@ This condensed version covers every ambiguity-prone term a template consumer or
 
 ## Terms
 
-**accessFeatureKey** -- the `OrganizationModelFeatureKey` a `FeatureModule` declares so the provider knows which org-level gate to check. Required field on every `FeatureModule`. Distinct from the nav-item `featureKey` (see below). Shell keys like `crm` and `lead-gen` map to grouped org-model keys (`acquisition`) via `FEATURE_KEY_ALIASES` -- this aliasing is automatic; callers do not need to translate manually.
+**featureId** (on FeatureModule) -- the `id` string a `FeatureModule` declares so the provider knows which entry in `OrganizationModel.features` to check for access gating. Required field on every `FeatureModule`. Must match the `id` of an entry in the features array (e.g. `'crm'`, `'projects'`). Distinct from the nav-item `featureKey` (see below). No aliasing layer -- IDs are direct matches.
 
 **AdminGuard** -- route-level admin wrapper from `@elevasis/ui/features/auth`. Wraps routes restricted to admin members. Must nest inside `ProtectedRoute`. Does not replace `requiresAdmin` on nav entries -- use both when both route access and nav visibility need admin enforcement.
 
@@ -21,45 +21,41 @@ This condensed version covers every ambiguity-prone term a template consumer or
 
 **DeploymentSpec** -- the complete resource collection for one organization (`workflows`, `agents`, `triggers`, `integrations`, `relationships`, `externalResources`, `humanCheckpoints`). Defined in `@repo/core`. The `operations/src/index.ts` file in each external project exports one `DeploymentSpec`.
 
-**Domain** -- a semantic business area in `OrganizationModel.domains`. Four defaults: `crm`, `lead-gen`, `delivery`, `operations`. Domains group entity IDs, surface IDs, resource IDs, and capability IDs into a coherent business area. Semantic, not navigational -- describes what business area a thing belongs to, not which access key gates it. Distinct from "feature": a domain describes business meaning; a feature key describes access and enablement.
+**Domain** -- removed concept. What was previously a `SemanticDomain` entry in `OrganizationModel.domains` is now expressed directly as a **Feature** in the `features` array. The `domains` field no longer exists on `OrganizationModel`. Semantic grouping (entity IDs, surface IDs, resource IDs, capability IDs) now lives on each `OrganizationModelFeature` object.
 
-**FEATURE_KEY_ALIASES** -- the alias map in `@elevasis/ui` that bridges shell feature-module keys to org-model grouped keys: `crm -> acquisition`, `lead-gen -> acquisition`, `projects -> delivery`. Used internally by `createFeatureAccessHook` so `isFeatureEnabled('crm')` resolves correctly against `MembershipFeatureConfig.features.acquisition`.
-
-**FoundationLegacyFeatureKey** -- template-local union for feature keys defined in `foundations/config/organization-model.ts`. Distinct from the published `OrganizationModelFeatureKey` (seven-key union from `@elevasis/core`). Extension point for template-specific feature identity without modifying the published core union. `FoundationFeatureKey` combines both (`OrganizationModelFeatureKey | FoundationLegacyFeatureKey`). `FEATURE_KEY_ALIASES` maps between shell keys and org-model grouped keys at runtime.
-
-**Feature** -- an overloaded term. Always qualify which layer is in scope:
+**Feature** -- the unified concept replacing the former three-layer system (feature keys, semantic domains, feature modules). Always qualify which layer is in scope:
 
 - **Platform capability** -- a product area (Execution Engine, Workflows, Agents, etc.). Not one-to-one with shell features.
-- **Shell FeatureModule** -- a manifest-backed UI feature registered with `ElevasisFeaturesProvider`. Seven manifest-backed: `lead-gen`, `crm`, `delivery`, `operations`, `monitoring`, `settings`, `seo`. Two utility (no manifest): `auth`, `dashboard`.
-- **Organization-model feature key** (`OrganizationModelFeatureKey`) -- grouped access key. Seven values: `acquisition`, `delivery`, `operations`, `monitoring`, `settings`, `seo`, `calibration`. Controls org-level gating and membership overrides.
+- **Organization-model feature** (`OrganizationModelFeature`) -- a single entry in `OrganizationModel.features`. Combines access gating (`enabled`), semantic grouping (`entityIds`, `surfaceIds`, `resourceIds`, `capabilityIds`), and display metadata (`label`, `description`, `color`, `icon`). Seven defaults: `crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, `seo`.
+- **Shell FeatureModule** -- a manifest-backed UI feature registered with `ElevasisFeaturesProvider`. Declares `featureId` matching an org-model feature ID. Seven manifest-backed: `lead-gen`, `crm`, `projects`, `operations`, `monitoring`, `settings`, `seo`. Two utility (no manifest): `auth`, `dashboard`.
 
-**featureKey** (nav-item) -- optional field on `FeatureNavEntry` and `FeatureNavLink` that gates a specific nav item's visibility independently of the module's `accessFeatureKey`. Resolved through `FEATURE_KEY_ALIASES`. May be more specific than the module's access key when a nested link needs a narrower gate.
+**featureKey** (nav-item) -- optional field on `FeatureNavEntry` and `FeatureNavLink` that gates a specific nav item's visibility independently of the module's `featureId`. Must match a feature ID in the org model. May be more specific than the module's `featureId` when a nested link needs a narrower gate.
 
 **FeatureGuard** -- route-level feature gate from `@elevasis/ui/features/auth`. Blocks access to a route when the resolved org model has the relevant feature key disabled. Must nest inside `ProtectedRoute`. Distinct from `AdminGuard` (admin membership) and `ProtectedRoute` (authentication).
 
-**FeatureModule** -- the manifest contract each shell feature provides to `ElevasisFeaturesProvider`. Defined in `@repo/ui`, NOT `@repo/core`. Fields: `key`, `accessFeatureKey` (required), `domainIds`, `capabilityIds`, `navEntry`, `sidebar`, `subshellRoutes`, `organizationGraph` (Operations-only). Template consumers build a local manifest array and pass it to `ElevasisFeaturesProvider` in `__root.tsx`.
+**FeatureModule** -- the manifest contract each shell feature provides to `ElevasisFeaturesProvider`. Defined in `@repo/ui`, NOT `@repo/core`. Fields: `key`, `featureId` (required -- replaces the former `accessFeatureKey`), `capabilityIds`, `navEntry`, `sidebar`, `subshellRoutes`, `organizationGraph` (Operations-only). Template consumers build a local manifest array and pass it to `ElevasisFeaturesProvider` in `__root.tsx`.
 
 **Foundations** -- the adapter layer in `foundations/` (two modules: `config/organization-model.ts` and `types/index.ts`). Source package with no build step. Depends only on `@elevasis/core` (npm) and `zod`. Never import `@repo/core` from foundations -- that would break standalone deployment.
 
 **Manifest** -- a `FeatureModule` instance that declares what one shell feature contributes at runtime (nav, sidebar, subshell routes, access key, semantic references). The provider registers an array of manifests at startup and validates them against the resolved org model.
 
-**MembershipFeatureConfig** -- per-member-per-org feature overrides stored in `org_memberships.config`. Six keys: `operations`, `monitoring`, `acquisition`, `delivery`, `calibration`, `seo`. Note: `settings` is absent -- see **Settings asymmetry** below.
+**MembershipFeatureConfig** -- per-member-per-org feature overrides stored in `org_memberships.config`. The `features` field is now `Record<string, boolean>` -- any feature ID can be overridden per member. Previously hardcoded to five keys (`operations`, `monitoring`, `acquisition`, `delivery`, `seo`); now open to any feature ID in the org model.
 
 **OrganizationModel** -- the top-level semantic contract for an organization. Published from `@elevasis/core/organization-model`. In the template, authored in `foundations/config/organization-model.ts` and exported as `canonicalOrganizationModel` (passed to `ElevasisFeaturesProvider`) and `organizationModel` (enriched shape for app-local use).
 
-**OrganizationModelFeatureKey** -- seven values: `acquisition`, `delivery`, `operations`, `monitoring`, `settings`, `seo`, `calibration`. These appear in `OrganizationModel.features.enabled` and as `accessFeatureKey` on `FeatureModule` instances. `MembershipFeatureConfig` overrides six of them per member (no `settings` slot -- see **Settings asymmetry**).
+**OrganizationModelFeature** -- the TypeScript type (`z.infer<typeof FeatureSchema>`) for a single entry in `OrganizationModel.features`. Replaces the former `OrganizationModelFeatureKey` (closed enum) and `OrganizationModelSemanticDomain`. Each feature has `id`, `label`, `enabled`, and semantic grouping arrays (`entityIds`, `surfaceIds`, `resourceIds`, `capabilityIds`). Exported from `@elevasis/core/organization-model`.
 
 **Provider / ElevasisFeaturesProvider** -- the runtime that registers manifests, resolves feature access against the org model, dispatches subshell routing via `FeatureShell`, and exposes resolved state through `useElevasisFeatures()`. Mounted in `__root.tsx`. Accepts `features`, optional `organizationModel`, and optional `appShellOverrides`.
 
-**Resolved types (ResolvedFeatureModule, ResolvedShellNavItem)** -- provider output. `ResolvedFeatureModule` extends `FeatureModule` with `access` (enabled state) and `semantics` (merged domain, capability, and surface IDs). `ResolvedShellNavItem` extends `FeatureNavEntry` with `placement`, `source`, and `accessFeatureKey`. Both from `@elevasis/ui`.
+**Resolved types (ResolvedFeatureModule, ResolvedShellNavItem)** -- provider output. `ResolvedFeatureModule` extends `FeatureModule` with `access` (enabled state and `featureId`) and `semantics` (merged capability and surface IDs). `ResolvedShellNavItem` extends `FeatureNavEntry` with `placement`, `source`, and `featureId`. Both from `@elevasis/ui`.
 
 **Resource** -- an entry in `OrganizationModel.resourceMappings` linking a deployable automation resource into the semantic model. At the registry layer, resources are `WorkflowDefinition` or `AgentDefinition` instances in a `DeploymentSpec`.
 
-**Settings asymmetry** -- `settings` is a valid `OrganizationModelFeatureKey` (org-level, present in `OrganizationModel.features.enabled`). It is absent from `MembershipFeatureConfig` (six keys, no `settings`). The org can disable settings entirely, but per-member disabling is not supported. Settings visibility for individual members is controlled via `requiresAdmin` on the nav entry and `AdminGuard` on routes.
+**Settings asymmetry** -- `settings` is a valid feature ID (org-level, present in `OrganizationModel.features` with `enabled: true` by default). `MembershipFeatureConfig.features` is now `Record<string, boolean>`, so `settings` can technically be overridden per member, but the convention is still to gate settings visibility via `requiresAdmin` on the nav entry and `AdminGuard` on routes rather than per-member feature overrides.
 
 **Subshell / Sidebar** -- the feature-scoped UI region rendered when the current route matches a manifest's `subshellRoutes`. Each `FeatureModule.sidebar` is a `ComponentType`. Consumers customize by composing the feature's published sidebar primitives (`CrmSidebar`, `CrmSidebarMiddle`, etc.) and assigning their component to `manifest.sidebar`.
 
-**Surface** -- a navigable view in `OrganizationModel.navigation.surfaces`. Identified by a dotted `id` (e.g., `crm.pipeline`). Has `path`, `surfaceType`, optional `featureKey` gate, and cross-reference arrays. Distinct from "page": a surface is the org-model declaration; a page is the React component rendered at the route.
+**Surface** -- a navigable view in `OrganizationModel.navigation.surfaces`. Identified by a dotted `id` (e.g., `crm.pipeline`). Has `path`, `surfaceType`, optional `featureId` gate (replaces the former `featureKey` field), and cross-reference arrays (`featureIds`, `entityIds`, `resourceIds`, `capabilityIds`). Distinct from "page": a surface is the org-model declaration; a page is the React component rendered at the route.
 
 **Topology** -- resource relationships (`triggers`, `uses`, `approval`) declared in `DeploymentSpec.relationships` and `HumanCheckpointDefinition.routesTo`. Used for Command View graph edges.
 
@@ -69,7 +65,7 @@ This condensed version covers every ambiguity-prone term a template consumer or
 
 **`@elevasis/core`** (published npm)
 
-- `OrganizationModel`, `OrganizationModelFeatureKey`, `OrganizationModelSurface`, `OrganizationModelResourceMapping`
+- `OrganizationModel`, `OrganizationModelFeature`, `OrganizationModelSurface`, `OrganizationModelResourceMapping`
 - `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
 - `MembershipFeatureConfig`
 
@@ -79,7 +75,7 @@ This condensed version covers every ambiguity-prone term a template consumer or
 - `ResolvedFeatureModule`, `ResolvedShellNavItem`
 - `FeatureGuard`, `AdminGuard`, `ProtectedRoute`
 - `ElevasisFeaturesProvider`, `ElevasisCoreProvider`, `useElevasisFeatures`
-- `FEATURE_KEY_ALIASES`, `createFeatureAccessHook`
+- `createFeatureAccessHook`
 
 **`foundations/`** (local source package -- not published)
 

package/reference/scaffold/ui/customization.md

@@ -113,7 +113,7 @@ const MyCrmSidebar = () => (
 const customCrmManifest = { ...crmManifest, sidebar: MyCrmSidebar }
 ```
 
-`PipelineHealthWidget` is a component you define in `ui/src/features/crm/` or `ui/src/shared/components/`. Keep route files and `__root.tsx` thin -- push component logic into feature modules.
+`PipelineHealthWidget` is a component you define in `ui/src/features/crm/` or `ui/src/lib/components/`. Keep route files and `__root.tsx` thin -- push component logic into feature modules.
 
 ## Worked Example 3: Page Wrapping
 
@@ -127,7 +127,7 @@ The exported CRM page components are `DealsListPage` and `DealDetailPage`:
 import { createFileRoute } from '@tanstack/react-router'
 import { DealsListPage } from '@elevasis/ui/features/crm'
 import { ProtectedRoute } from '@/features/auth'
-import { ProjectAnnouncementBanner } from '@/shared/components/ProjectAnnouncementBanner'
+import { ProjectAnnouncementBanner } from '@/lib/components/ProjectAnnouncementBanner'
 import { Stack } from '@mantine/core'
 
 export const Route = createFileRoute('/crm/deals/')({

package/reference/scaffold/ui/feature-flags-and-gating.md

@@ -8,8 +8,8 @@ description: End-to-end recipe for the three gating concepts -- featureKey nav v
 **Status: 🟢 Stable**
 
 This doc resolves the three-concept confusion that trips up most agents building new features. Read
-the overview table first, then follow the end-to-end chain for the template's actual grouped-key
-plus alias flow.
+the overview table first, then follow the end-to-end chain for the template's unified feature ID
+flow.
 
 ---
 
@@ -29,47 +29,32 @@ The three concepts work together but are independent. Hiding a nav item does not
 
 ## End-to-End Chain
 
-This section walks through the template's existing acquisition flow. In this scaffold, `crm` and
-`lead-gen` are route-level aliases that map to the grouped org-model key `acquisition`.
+This section walks through the template's feature gating flow. Features are declared as objects in
+the org model with a direct `id` field. `FeatureModule.featureId` matches that `id` exactly -- no
+alias layer exists.
 
-If you need a brand-new shell feature key such as `analytics`, that is not a template-only change.
-It requires updating the published `@elevasis/core` organization-model contract and any shared
-`@elevasis/ui` feature manifests that should consume it.
+If you need a brand-new feature such as `analytics`, add a feature object to the `features[]`
+defaults array in the org model and author a matching manifest. See [add-a-feature.md](../recipes/add-a-feature.md).
 
-### Step 1: Declare the grouped org-model gate in `organization-model.ts`
+### Step 1: Declare the feature in `organization-model.ts`
 
 File: `foundations/config/organization-model.ts`
 
 ```ts
 const foundationOrganizationModelOverride = defineOrganizationModel({
-  features: {
-    enabled: {
-      acquisition: true
-    },
-    labels: {
-      acquisition: 'Acquisition'
-    }
-  },
+  features: [
+    { id: 'crm',      label: 'CRM',       enabled: true,  entityIds: [...], surfaceIds: [...] },
+    { id: 'lead-gen', label: 'Lead Gen',  enabled: true,  entityIds: [...], surfaceIds: [...] },
+    { id: 'projects', label: 'Projects',  enabled: true,  entityIds: [...], surfaceIds: [...] },
+    // ... other features
+  ],
   // ... rest of model
 })
 ```
 
-The `features.enabled` record is the source of truth for the published org-model gates. In the
-current template, those keys are the grouped platform keys:
-`acquisition`, `delivery`, `operations`, `monitoring`, `settings`, `seo`, and `calibration`.
-
-Further down in the same file, the template adapts that canonical model into shell-friendly aliases:
-
-```ts
-const featuresEnabled: Record<FoundationFeatureKey, boolean> = {
-  acquisition: resolvedOrganizationModel.features.enabled.acquisition,
-  crm: resolvedOrganizationModel.features.enabled.acquisition,
-  'lead-gen': resolvedOrganizationModel.features.enabled.acquisition
-}
-```
-
-That alias layer is why route guards can ask for `crm` or `lead-gen` even though the published
-organization-model contract only knows about `acquisition`.
+The `features[]` array is the source of truth for org-model gates. The 7 default feature IDs are
+`crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, and `seo`. Each feature
+object's `enabled` field controls whether that feature is on by default for the org.
 
 ### Step 2: Wire `featureKey` on a nav item
 
@@ -85,10 +70,11 @@ import { crmManifest } from '@elevasis/ui/features/crm'
 const manifest: FeatureModule = crmManifest
 ```
 
-`accessFeatureKey` on the `FeatureModule` is what drives whether the entire shared feature
-(including its nav entry) is visible. In the published manifests, `crm` and `lead-gen` both use
-`accessFeatureKey: 'acquisition'`; `delivery` uses `accessFeatureKey: 'delivery'`. The shell hides
-the nav entry when org or membership access disables that grouped key.
+`featureId` on the `FeatureModule` is what drives whether the entire shared feature (including its
+nav entry) is visible. Each manifest sets `featureId` to the matching `feature.id` value from the
+org model (e.g., `crmManifest.featureId = 'crm'`, `leadGenManifest.featureId = 'lead-gen'`,
+`projectsManifest.featureId = 'projects'`). The shell hides the nav entry when org or membership
+access disables that feature ID.
 
 **Local nav-items.ts** (for one-off items not part of a registered feature):
 
@@ -101,8 +87,8 @@ export const navItems: ExtendedLinksGroupProps[] = [
 ```
 
 When `featureKey` is set on a nav item in `nav-items.ts`, the shell hides that item if
-`isFeatureEnabled(featureKey)` returns false. Template-local aliases like `crm`, `lead-gen`, and
-`projects` work here because the adapted `organizationModel` exposed by foundations includes them.
+`isFeatureEnabled(featureKey)` returns false. The key must match a `feature.id` value in the org
+model -- no alias mapping is applied.
 
 ### Step 3: Wrap the route in `FeatureGuard`
 
@@ -141,7 +127,7 @@ All existing feature routes in the template follow this exact pattern: `operatio
 For conditional UI within a component (showing or hiding a button, panel, or section based on a feature flag), use the `useFeatureAccess` hook directly.
 
 ```tsx
-import { useFeatureAccess } from '@/shared/hooks/useFeatureAccess'
+import { useFeatureAccess } from '@/lib/hooks/useFeatureAccess'
 
 function Dashboard() {
   const { hasFeature } = useFeatureAccess()
@@ -157,9 +143,9 @@ function Dashboard() {
 
 `hasFeature` returns a boolean. Use it for render-conditional logic only. Do not use it as a substitute for `FeatureGuard` on a route -- hiding a component does not prevent direct URL access.
 
-The hook is defined in `ui/src/shared/hooks/useFeatureAccess.ts`. It wraps
-`createFeatureAccessHook` from `@elevasis/ui/hooks` and extends it with template-specific key
-aliases (`crm` and `lead-gen` alias to `acquisition`; `projects` aliases to `delivery`).
+The hook is defined in `ui/src/lib/hooks/useFeatureAccess.ts`. It wraps
+`createFeatureAccessHook` from `@elevasis/ui/hooks` and resolves feature IDs directly against the
+org model's `features[]` array -- no alias mapping is applied.
 
 ---
 
@@ -235,24 +221,24 @@ Use this pattern when only a section of a page is admin-only, not the entire rou
 
 ## Import Paths
 
-| Symbol                    | Import path                              | Notes                                                                                  |
-| ------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------- |
-| `FeatureGuard`            | `@/features/auth/guards/FeatureGuard`    | Template-local wrapper; uses `useFeatureAccess` from `@/shared/hooks/useFeatureAccess` |
-| `AdminGuard`              | `@elevasis/ui/auth`                      | Published from `@elevasis/ui`                                                          |
-| `useFeatureAccess`        | `@/shared/hooks/useFeatureAccess`        | Template-local wrapper around `createFeatureAccessHook` from `@elevasis/ui/hooks`      |
-| `createFeatureAccessHook` | `@elevasis/ui/hooks`                     | Factory for building a feature-access hook; already consumed by the template wrapper   |
-| `ProtectedRoute`          | `@elevasis/ui/auth` or `@/features/auth` | Ensures user is authenticated before any guard runs                                    |
+| Symbol                    | Import path                              | Notes                                                                                |
+| ------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------ |
+| `FeatureGuard`            | `@/features/auth/guards/FeatureGuard`    | Template-local wrapper; uses `useFeatureAccess` from `@/lib/hooks/useFeatureAccess`  |
+| `AdminGuard`              | `@elevasis/ui/auth`                      | Published from `@elevasis/ui`                                                        |
+| `useFeatureAccess`        | `@/lib/hooks/useFeatureAccess`           | Template-local wrapper around `createFeatureAccessHook` from `@elevasis/ui/hooks`    |
+| `createFeatureAccessHook` | `@elevasis/ui/hooks`                     | Factory for building a feature-access hook; already consumed by the template wrapper |
+| `ProtectedRoute`          | `@elevasis/ui/auth` or `@/features/auth` | Ensures user is authenticated before any guard runs                                  |
 
-The template's `FeatureGuard` (`@/features/auth/guards/FeatureGuard`) is not the same as the published `FeatureGuard` from `@elevasis/ui/features`. The template version closes over the local `useFeatureAccess` hook and the local organization model labels, so it knows your feature key aliases. Use the template-local version.
+The template's `FeatureGuard` (`@/features/auth/guards/FeatureGuard`) is not the same as the published `FeatureGuard` from `@elevasis/ui/features`. The template version closes over the local `useFeatureAccess` hook and the resolved org model, so it checks feature IDs against your project's feature array. Use the template-local version.
 
 ---
 
 ## Common Mistakes
 
-- **Inventing a new org-model key in the template only.** The published
-  `OrganizationModelFeatureKey` union is fixed in `@elevasis/core`. Template-local aliases like
-  `crm`, `lead-gen`, and `projects` work because foundations maps them onto grouped keys; a brand
-  new shell key such as `analytics` requires a core/package contract change, not just a doc tweak.
+- **Using a feature ID that does not exist in the org model.** `FeatureModule.featureId` and
+  `featureKey` on nav entries must match a `feature.id` value in the org model's `features[]`
+  array. The provider throws at startup if an unknown ID is declared. To add a brand-new feature
+  such as `analytics`, first add it to the `features[]` array in `foundations/config/organization-model.ts`.
 
 - **Using `FeatureGuard` on a nav item instead of a route.** `FeatureGuard` is a React component that redirects on mount. Placing it inside a nav item or link will fire a redirect whenever the sidebar renders. Gate nav visibility with `featureKey` on the nav entry or `accessFeatureKey` on the manifest; gate route access with `FeatureGuard` in the route layout.
 

package/reference/scaffold/ui/feature-shell.mdx

@@ -10,10 +10,10 @@ Within Organization OS, the feature shell spans two layers: the **UI Shell Runti
 Three layers participate, and the word "feature" means something different in each:
 
 - **Platform capabilities** -- product-facing areas documented under `technical/features/` (Execution Engine, Workflows, Agents, Operations, etc.). These are not one-to-one with shell features.
-- **Shell features** -- features in `packages/ui/src/features/*`. Seven are manifest-backed (`lead-gen`, `crm`, `delivery`, `operations`, `monitoring`, `settings`, `seo`); two are utility features without manifests (`auth`, `dashboard`).
-- **Organization-model features** -- grouped semantic/access keys in `@repo/core/organization-model` (`acquisition`, `delivery`, `operations`, `monitoring`, `settings`, `seo`, `calibration`). See [Organization Model](../core/organization-model.mdx).
+- **Shell features** -- features in `packages/ui/src/features/*`. Seven are manifest-backed (`crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, `seo`); two are utility features without manifests (`auth`, `dashboard`).
+- **Organization-model features** -- feature objects in `@repo/core/organization-model` with shape `{ id, label, enabled, entityIds, surfaceIds, resourceIds, capabilityIds }`. The 7 defaults are `crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, `seo`. See [Organization Model](../core/organization-model.mdx).
 
-One shell feature can contain several platform capabilities; shell and organization-model keys are different concepts.
+One shell feature can contain several platform capabilities; a manifest's `featureId` directly matches `feature.id` in the org model with no alias layer.
 
 ## Source of Truth
 
@@ -30,24 +30,24 @@ One shell feature can contain several platform capabilities; shell and organizat
 
 A `FeatureModule` describes one shell feature's contribution. Fields:
 
-- `key` -- unique stable identifier (e.g., `'crm'`, `'delivery'`)
-- `accessFeatureKey` -- **required**; the key `useFeatureAccess()` checks for gating
-- `domainIds`, `capabilityIds` -- semantic references into the organization model
+- `key` -- unique stable identifier (e.g., `'crm'`, `'projects'`)
+- `featureId` -- **required**; the `feature.id` value from the org model that this module maps to; used by `useFeatureAccess()` for gating
+- `capabilityIds` -- semantic references into the organization model
 - `navEntry` -- top-level nav contribution (label, icon, optional `link`, optional nested `links`, optional `requiresAdmin`, optional onboarding-tour ID, optional `featureKey` override when nav identity must diverge from access identity)
 - `sidebar` -- optional `ComponentType` for the feature's subshell sidebar
 - `subshellRoutes` -- routes the feature owns under its subshell
 - `organizationGraph` -- **Operations-only**; bridges a manifest to an organization-model surface (ignored by other features)
 
-`FeatureModule.label` has been removed; nav labels resolve from `navEntry.label` or from organization-model feature labels.
+`FeatureModule.label` has been removed; nav labels resolve from `navEntry.label` or from the matching organization-model feature's `label` field.
 
-Manifests are validated at provider registration via `validateManifests()`. Unknown `accessFeatureKey`, `domainIds`, or `capabilityIds` (measured against the resolved organization model) throw with all violations collected into one error.
+Manifests are validated at provider registration via `validateManifests()`. Unknown `featureId` or `capabilityIds` (measured against the resolved organization model) throw with all violations collected into one error.
 
 ### ResolvedFeatureModule
 
 `ResolvedFeatureModule` extends `FeatureModule` with two additional fields added during provider resolution:
 
-- `access: ResolvedFeatureAccess` -- `{ featureKey: string, enabled: boolean }` -- the resolved access state for this feature
-- `semantics: ResolvedFeatureSemantics` -- `{ domainIds, capabilityIds, surfaceIds, surfaces }` -- merged semantic identifiers derived from both manifest declarations and organization-model surface data
+- `access: ResolvedFeatureAccess` -- `{ featureId: string, enabled: boolean }` -- the resolved access state for this feature
+- `semantics: ResolvedFeatureSemantics` -- `{ capabilityIds, surfaceIds, surfaces }` -- merged semantic identifiers derived from both manifest declarations and organization-model surface data
 
 `ResolvedFeatureSemantics.surfaces` carries the full `OrganizationModelSurface[]` objects (not just IDs), so consumers can inspect surface metadata without a separate lookup.
 
@@ -108,8 +108,8 @@ Consumers keep thin local route wrappers and app-local nav where needed.
 
 1. The app defines a manifest list (often by spreading `FEATURE_MANIFESTS` and overriding entries).
 2. The app optionally resolves an organization model and passes it to the provider.
-3. The provider combines `useFeatureAccess()` with organization-model feature state to compute enabled features.
-4. Nav labels and nav paths resolve from `organizationModel.features.labels` and `organizationModel.navigation.surfaces` when present.
+3. The provider combines `useFeatureAccess()` with the org model's `features[]` array to compute enabled features.
+4. Nav labels and nav paths resolve from the matching `feature.label` in `organizationModel.features` and from `organizationModel.navigation.surfaces` when present.
 5. The provider exposes `shellModel`, `shellRuntime`, resolved feature access, `organizationGraph`, and shared runtime inputs via `useElevasisFeatures()`.
 6. `FeatureShell` calls `shellRuntime.resolveRoute(currentPath)`:
    - `matched` -- render the feature's sidebar subshell
@@ -144,7 +144,7 @@ Consumer nav derivation runs locally from `shellModel.navItems`; the provider no
 
 - `placement: 'primary' | 'bottom'` -- where the item appears in the shell nav; feature manifests always produce `'primary'`; `appShellOverrides.bottomNavItems` produce `'bottom'`
 - `source: 'app' | 'feature'` -- whether the item came from a manifest (`'feature'`) or from `appShellOverrides` (`'app'`)
-- `accessFeatureKey?: string` -- the feature key associated with this nav item for gating checks
+- `featureId?: string` -- the feature ID associated with this nav item for gating checks
 
 `shellModel.navItems` contains the merged and filtered list of all `ResolvedShellNavItem`s from both manifest features and `appShellOverrides`.
 
@@ -152,14 +152,14 @@ Consumer nav derivation runs locally from `shellModel.navItems`; the provider no
 
 `filterNavLinks()` in `ElevasisFeaturesProvider.tsx` recursively removes gated and disabled-subsection links from a `FeatureNavLink[]` array. A link is removed if its `featureKey` fails `isFeatureEnabled()` or if its path matches any entry in `disabledSubsectionPaths`. The function recurses into nested `links` arrays before deciding whether a parent with now-empty children should be retained or dropped.
 
-## Access Resolution & Key Aliasing
+## Access Resolution
 
-Shell feature-module keys (`crm`, `lead-gen`, `delivery`) differ from the organization-model grouped keys used by published membership config (`acquisition`, `delivery`). The published `@elevasis/ui` line preserves grouped-key compatibility:
+Shell feature-module keys map directly to feature IDs in the organization model. There is no alias layer:
 
 - `createFeatureAccessHook` is the factory that produces `useFeatureAccess`. (Old name `createUseFeatureAccess` is re-exported as `@deprecated`.)
-- `FEATURE_KEY_ALIASES` in `packages/ui/src/hooks/feature-access/aliases.ts` is the single authoritative alias map. `crm -> acquisition`, `lead-gen -> acquisition`, `projects -> delivery`.
-- Shared manifests declare grouped `accessFeatureKey` (e.g., `crmManifest.accessFeatureKey = 'acquisition'`) so the published contract gates against `MembershipFeatureConfig` as written.
-- The provider fallback for missing feature access identity is retired -- explicit `accessFeatureKey` is required.
+- `FeatureModule.featureId` must match a `feature.id` value in the org model's `features[]` array. The provider throws at startup if the ID is not found.
+- `MembershipFeatureConfig.features` is `Record<string, boolean>` -- a dynamic map keyed by feature ID. Any feature can be overridden per member without schema changes.
+- The provider fallback for missing feature access identity is retired -- explicit `featureId` is required.
 
 ## Published Surface
 
@@ -170,8 +170,8 @@ All nine features are published as individual subpath exports from `@elevasis/ui
 - `@elevasis/ui/features/auth` -- `ProtectedRoute`, `AdminGuard`, `FeatureGuard`, `useUserProfile` (utility feature; no manifest)
 - `@elevasis/ui/features/dashboard` -- `Dashboard`, `ResourceOverview`, `RecentExecutionsByResource`, `UnresolvedErrorsTeaser` (utility feature; no manifest)
 - `@elevasis/ui/features/crm`
-- `@elevasis/ui/features/delivery`
 - `@elevasis/ui/features/lead-gen`
+- `@elevasis/ui/features/projects`
 - `@elevasis/ui/features/monitoring`
 - `@elevasis/ui/features/operations`
 - `@elevasis/ui/features/seo`
@@ -201,7 +201,7 @@ The `auth` and `dashboard` features are not in `FEATURE_MANIFESTS` and are not r
 
 Both arrays go through the same `isFeatureEnabled()` and `disabledSubsectionPaths` filtering as manifest-derived items. Items whose `featureKey` is disabled, or that have only disabled nested links and no direct `link`, are dropped entirely.
 
-Nine feature modules are published (see **Published Surface** above). Six are currently mounted in command-center: `leadGenManifest`, `crmManifest`, `deliveryManifest`, `operationsManifest`, `monitoringManifest`, `settingsManifest`. The remaining three (`seoManifest`, `auth`, `dashboard`) are published but not mounted through `ElevasisFeaturesProvider` in command-center -- `auth` and `dashboard` are utility features consumed directly, while `seoManifest` is available for composition but not wired into the current command-center shell.
+Nine feature modules are published (see **Published Surface** above). Six are currently mounted in command-center: `leadGenManifest`, `crmManifest`, `projectsManifest`, `operationsManifest`, `monitoringManifest`, `settingsManifest`. The remaining three (`seoManifest`, `auth`, `dashboard`) are published but not mounted through `ElevasisFeaturesProvider` in command-center -- `auth` and `dashboard` are utility features consumed directly, while `seoManifest` is available for composition but not wired into the current command-center shell.
 
 ### External-consumer composition
 
@@ -221,7 +221,6 @@ The CRM sidebar (`packages/ui/src/features/crm/sidebar/`) exports `CrmSidebar`,
 
 - Returns `null` for sessions (`/operations/sessions`) and command-view (`/operations/command-view`) routes -- these sections own their own top-area UI
 - Shows a "Resource Overview" navigation button for the resources section (`/operations/resources`)
-- Shows a "Calibration Projects" navigation button for the calibration section (`/operations/calibration`)
 - Returns `null` for all other paths (e.g., the operations index)
 
 This pattern avoids hardcoding sidebar top content in the parent and lets each operations sub-section declare its own top panel entry point.
@@ -236,6 +235,6 @@ This pattern avoids hardcoding sidebar top content in the parent and lets each o
 ## Key Conceptual Distinctions
 
 - **Platform capability vs. shell feature** -- capabilities are the product map; shell features are manifest-backed UI surfaces.
-- **Shell feature key vs. organization-model feature key** -- `crm` (shell) vs. `acquisition` (published access identity).
-- **Semantic domain vs. feature key** -- `domain = crm` describes the business area; `feature key = acquisition` gates access.
+- **Shell feature key vs. org-model feature id** -- both are the same value (e.g., `crm`). `FeatureModule.featureId` directly matches `feature.id` in the org model; there is no alias layer.
+- **Feature vs. capability** -- a feature object in the org model carries `entityIds`, `surfaceIds`, `resourceIds`, and `capabilityIds`; capabilities are one kind of semantic reference a feature can hold.
 - **Provider-owned vs. consumer-owned** -- provider owns shared manifests, nav contribution, sidebar dispatch, shared runtime context; consumers own route files, branding, topbar behavior, admin entries.