@elevasis/sdk 1.3.0 → 1.5.0

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

@@ -0,0 +1,265 @@
+---
+title: Feature Flags & Gating
+description: End-to-end recipe for the three gating concepts -- featureKey nav visibility, FeatureGuard route gate, AdminGuard / requiresAdmin. One doc resolves confusion that scored 2/5 in scaffold eval.
+---
+
+# Feature Flags & Gating
+
+**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.
+
+---
+
+## Overview
+
+Three distinct mechanisms control access in the template. They operate at different layers and are not interchangeable.
+
+| Concept                        | What it gates                                | Where it applies                                   | How it works                                                                          |
+| ------------------------------ | -------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `featureKey` on a nav entry    | Whether a nav item is visible in the sidebar | `navEntry` in a feature manifest or `nav-items.ts` | The shell reads the organization model and hides items whose `featureKey` is disabled |
+| `FeatureGuard` component       | Whether a route subtree is accessible        | Route layout files (`ui/src/routes/*.tsx`)         | Reads org + membership access and redirects with a notification if the feature is off |
+| `AdminGuard` / `requiresAdmin` | Whether an admin-only surface is accessible  | Route layout files and manifest nav entries        | Reads `profile.is_platform_admin`; redirects non-admins to `/`                        |
+
+The three concepts work together but are independent. Hiding a nav item does not protect a route -- you must also wrap the route in `FeatureGuard`. Showing a nav item does not grant access.
+
+---
+
+## 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`.
+
+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.
+
+### Step 1: Declare the grouped org-model gate in `organization-model.ts`
+
+File: `foundations/config/organization-model.ts`
+
+```ts
+const foundationOrganizationModelOverride = defineOrganizationModel({
+  features: {
+    enabled: {
+      acquisition: true
+    },
+    labels: {
+      acquisition: 'Acquisition'
+    }
+  },
+  // ... 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`.
+
+### Step 2: Wire `featureKey` on a nav item
+
+Nav items come from one of two places: the manifest `navEntry` (for features registered through `ElevasisFeaturesProvider`) or the local `nav-items.ts` config (for app-local nav).
+
+**Manifest nav entry** (preferred for platform features):
+
+```ts
+// Published shared manifest
+import type { FeatureModule } from '@elevasis/ui/provider'
+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.
+
+**Local nav-items.ts** (for one-off items not part of a registered feature):
+
+```ts
+// ui/src/config/nav-items.ts
+export const navItems: ExtendedLinksGroupProps[] = [
+  { label: 'Dashboard', icon: IconDashboard, link: '/' },
+  { label: 'CRM', icon: IconBriefcase, link: '/crm', featureKey: 'crm' }
+]
+```
+
+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.
+
+### Step 3: Wrap the route in `FeatureGuard`
+
+File: `ui/src/routes/crm.tsx` (TanStack Router layout file for the `/crm` subtree)
+
+```tsx
+import { ProtectedRoute } from '@/features/auth'
+import { FeatureGuard } from '@/features/auth/guards/FeatureGuard'
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/crm')({
+  component: RouteComponent
+})
+
+function RouteComponent() {
+  return (
+    <ProtectedRoute>
+      <FeatureGuard featureKey="crm">
+        <Outlet />
+      </FeatureGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+`FeatureGuard` must always be nested inside `ProtectedRoute`. It reads from `useFeatureAccess()`
+(the template's wrapper around `createFeatureAccessHook`), checks the effective org-plus-membership
+access, and redirects to `/` with a Mantine notification if the feature is off. The layout pattern
+means every child route under `/crm` is automatically protected without repeating the guard.
+
+All existing feature routes in the template follow this exact pattern: `operations.tsx`,
+`projects.tsx`, `lead-gen.tsx`, `crm.tsx`, and `monitoring.tsx`.
+
+### Step 4: Check in a component via `useFeatureAccess`
+
+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'
+
+function Dashboard() {
+  const { hasFeature } = useFeatureAccess()
+
+  return (
+    <div>
+      <CoreMetrics />
+      {hasFeature('crm') && <CrmSummaryPanel />}
+    </div>
+  )
+}
+```
+
+`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`).
+
+---
+
+## Admin Gating
+
+Admin gating is separate from feature gating. It restricts surfaces to users with `profile.is_platform_admin === true`.
+
+### `requiresAdmin` on a manifest nav entry
+
+```ts
+// In a FeatureNavEntry
+navEntry: {
+  label: 'Admin',
+  icon: IconShield,
+  link: '/admin',
+  requiresAdmin: true
+}
+```
+
+Setting `requiresAdmin: true` on a `FeatureNavEntry` causes the shell to hide that nav item for non-admin users. This is purely a visibility concern -- the route is still accessible by URL. Always combine with a route-level `AdminGuard`.
+
+### `AdminGuard` in a route
+
+```tsx
+// ui/src/routes/admin.tsx
+import { ProtectedRoute } from '@/features/auth'
+import { AdminGuard } from '@elevasis/ui/auth'
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/admin')({
+  component: RouteComponent
+})
+
+function RouteComponent() {
+  return (
+    <ProtectedRoute>
+      <AdminGuard fallback={<AppShellLoader />}>
+        <Outlet />
+      </AdminGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+`AdminGuard` reads `profile.is_platform_admin` from the initialization context. Non-admins are redirected to `redirectTo` (default `/`). Always nest inside `ProtectedRoute` so that the user profile is loaded before the guard runs.
+
+### `AdminGuard` in a component
+
+```tsx
+import { AdminGuard } from '@elevasis/ui/auth'
+
+function SettingsPage() {
+  return (
+    <>
+      <GeneralSettings />
+      <AdminGuard>
+        <DangerZone />
+      </AdminGuard>
+    </>
+  )
+}
+```
+
+Use this pattern when only a section of a page is admin-only, not the entire route. The rest of the page renders normally for all authenticated users.
+
+### When to use each
+
+- `requiresAdmin` on `navEntry`: hide the nav item for non-admins (cosmetic only, always pair with route guard)
+- `AdminGuard` wrapping a route's `Outlet`: protect the entire route subtree
+- `AdminGuard` wrapping a component section: protect part of a page
+
+---
+
+## 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                                    |
+
+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.
+
+---
+
+## 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 `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.
+
+- **Confusing `requiresAdmin` with `AdminGuard`.** `requiresAdmin` on a `FeatureNavEntry` is a display hint read by the shell nav renderer -- it hides the nav item but does not block the route. `AdminGuard` is a React component that actively redirects. You need both if you want the nav hidden and the route blocked.
+
+- **Placing `FeatureGuard` or `AdminGuard` outside `ProtectedRoute`.** Both guards depend on the user profile being loaded. Unauthenticated users will see a redirect loop or a blank screen if the profile is not yet available. Always nest guards inside `ProtectedRoute`.
+
+- **Using `hasFeature` from `useFeatureAccess` as a route guard.** `hasFeature` is for conditional
+  rendering inside components. A user can still navigate directly to a URL and reach the route
+  component. Use `FeatureGuard` in the route file for actual access control.

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

@@ -0,0 +1,241 @@
+---
+title: Feature Shell & Provider Runtime
+description: Organization OS UI Shell Runtime and Features layer architecture covering FeatureModule manifests, ElevasisFeaturesProvider, route-to-sidebar dispatch, and organization-model-aware runtime resolution.
+---
+
+## Overview
+
+Within Organization OS, the feature shell spans two layers: the **UI Shell Runtime** that resolves shared nav/sidebar behavior, and the **Features** layer that declares what each feature contributes. It lets command-center and external template consumers compose the same nav, sidebars, and subshell routes from a small set of manifests. It is intentionally a thin layer: manifests describe what a feature contributes, the provider resolves that into a runtime shell model, and consumers still own their own routes, branding, and app-local nav.
+
+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).
+
+One shell feature can contain several platform capabilities; shell and organization-model keys are different concepts.
+
+## Source of Truth
+
+- `packages/ui/src/features/registry/types.ts` -- `FeatureModule` contract
+- `packages/ui/src/features/registry/manifests.ts` -- published `FEATURE_MANIFESTS` convenience map
+- `packages/ui/src/provider/ElevasisFeaturesProvider.tsx` -- runtime composition
+- `packages/ui/src/provider/FeatureShell.tsx` -- route-to-sidebar dispatch
+- `packages/ui/src/provider/resolvers/{RouteResolver,NavResolver}.ts` -- pure path/nav helpers
+- `packages/ui/src/provider/validateManifests.ts` -- startup-time manifest validation
+- `packages/ui/src/provider/published.ts` -- headless published barrel
+- `apps/command-center/src/routes/__root.tsx` -- reference composition
+
+## The FeatureModule Contract
+
+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
+- `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.
+
+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.
+
+### 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
+
+`ResolvedFeatureSemantics.surfaces` carries the full `OrganizationModelSurface[]` objects (not just IDs), so consumers can inspect surface metadata without a separate lookup.
+
+## Provider Architecture
+
+The provider layer is composed of several focused context providers. `ElevasisCoreProvider` and `ElevasisFeaturesProvider` are the two consumer-facing entry points; the others are internal building blocks also published for advanced use.
+
+### ElevasisCoreProvider
+
+`ElevasisCoreProvider` is the headless root provider for Elevasis-powered applications. It is pure auth + API with no style side-effects -- no CSS variables, no `data-elevasis-scheme`, no font loading. When `apiUrl` is provided it composes the full provider stack:
+
+`QueryClientProvider` -> `AuthProvider` -> `ApiClientProvider` -> `ProfileProvider` -> `OrganizationProvider` -> `ElevasisServiceProvider` -> `NotificationProvider` -> `InitializationProvider`
+
+Consumers that need Mantine theming use `ElevasisUIProvider` (internal) or `ElevasisProvider` instead. `ElevasisCoreProvider` is exported from `packages/ui/src/provider/published.ts` for headless SDK consumers.
+
+### ElevasisServiceProvider
+
+`ElevasisServiceProvider` (from `ElevasisServiceContext.tsx`) is the standalone service context. It accepts three props directly: `apiRequest`, `organizationId`, and `isReady`. `ElevasisCoreProvider` composes this internally after org resolution; advanced consumers can mount it standalone for testing or embedding.
+
+`useElevasisServices()` reads this context and throws if used outside a provider. Consumed throughout the shared component library wherever API requests are needed.
+
+### AppearanceProvider
+
+`AppearanceProvider` (from `AppearanceContext.tsx`) supplies an `AppearanceConfig` to the tree: `{ background?: ReactNode, loader?: ReactNode }`. The `background` field controls layers rendered behind app content; `loader` controls loading-state elements. Defaults are set in the provider rather than at context creation to avoid importing heavy visual components at module scope.
+
+`useAppearance()` reads this context and throws if used outside a provider.
+
+### NotificationProvider
+
+`NotificationProvider` (from `NotificationContext.tsx`) accepts a pluggable `NotificationAdapter` for routing notifications to any library. The adapter interface is `{ success, error, info, warning, apiError }`. `ElevasisUIProvider` wires the Mantine adapter automatically.
+
+When no provider is present in the tree, `useNotificationAdapter()` falls back to a console-based adapter (not a no-op), so template consumers work without Mantine. The hook never throws.
+
+### Memoization Strategy
+
+All computed values inside `ElevasisFeaturesProvider` are wrapped in `useMemo()` with precise dependency tracking. Resolved features, nav items, shell model, organization graph, and the context value object are each memoized separately so downstream consumers only re-render when their specific inputs change.
+
+## Provider Responsibilities
+
+`ElevasisFeaturesProvider` owns:
+
+- registration of shared feature manifests
+- feature-flag-aware nav contribution
+- route-to-sidebar subshell dispatch (via `shellRuntime.resolveRoute`)
+- provider-scoped shared runtime context
+- resolved shell-model composition and shell-native route matching
+- organization-model-aware nav label and path resolution
+- resolved feature output (no legacy `shellModule` wrapper)
+
+It does **not** own:
+
+- TanStack file-based route registration
+- app branding, topbar behavior, admin entries, assistant/context glue
+
+Consumers keep thin local route wrappers and app-local nav where needed.
+
+## Runtime Flow
+
+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.
+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
+   - `hidden` -- render `FeatureUnavailableState`
+   - `unmatched` -- render plain children (consumer owns the route)
+
+   A route resolves as `hidden` when the matched nav link meets either of these conditions: its `featureKey` fails the `isFeatureEnabled()` check, or its path matches an entry in `disabledSubsectionPaths`. Both checks are applied recursively through nested nav links.
+
+Consumer nav derivation runs locally from `shellModel.navItems`; the provider no longer exposes `visibleNavItems`.
+
+## Provider-Scoped Runtime Context
+
+`useElevasisFeatures()` exposes:
+
+- `shellModel` -- `{ navItems: ResolvedShellNavItem[] }` -- the full resolved nav list
+- `shellRuntime` -- `{ resolveRoute: (path) => ResolvedShellRouteMatch }` -- route dispatch
+- `resolvedFeatures` -- all `ResolvedFeatureModule[]` regardless of enabled state
+- `enabledResolvedFeatures` -- filtered to `access.enabled === true`
+- `timeRange`
+- `operationsApiUrl`, `operationsSSEManager`
+- `organizationModel`
+- `organizationGraph` (resolved from `operations.organization-graph` surface; see [Organization Graph](../core/organization-graph.mdx))
+- `disabledSubsectionPaths` -- used by consumers like `_template` to hide specific subsections (e.g., `/settings/appearance`)
+- `isFeatureEnabled(key: string): boolean` -- checks both membership flag and organization-model feature state
+- `getResolvedFeature(key: string): ResolvedFeatureModule | undefined` -- looks up a resolved feature by its `key` field (module key, not access key)
+
+## Nav Resolution
+
+### ResolvedShellNavItem
+
+`ResolvedShellNavItem` extends `FeatureNavEntry` with two additional fields:
+
+- `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
+
+`shellModel.navItems` contains the merged and filtered list of all `ResolvedShellNavItem`s from both manifest features and `appShellOverrides`.
+
+### filterNavLinks
+
+`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
+
+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:
+
+- `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.
+
+## Published Surface
+
+`packages/ui/src/provider/published.ts` is intentionally headless: it exports the provider, types, and hooks, but no Mantine-dependent visual provider pieces. External consumers can adopt the feature/provider contract without pulling the full internal visual surface.
+
+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/monitoring`
+- `@elevasis/ui/features/operations`
+- `@elevasis/ui/features/seo`
+- `@elevasis/ui/features/settings`
+
+The `auth` and `dashboard` features are not in `FEATURE_MANIFESTS` and are not registered with `ElevasisFeaturesProvider`. They are standalone published feature modules consumed directly by host apps.
+
+## Composition Patterns
+
+### Command-center composition
+
+`apps/command-center/src/routes/__root.tsx`:
+
+1. imports the mounted manifest list
+2. resolves `COMMAND_CENTER_ORGANIZATION_MODEL`
+3. passes manifests, organization model, time range, operations API URL, and SSE manager to `ElevasisFeaturesProvider`
+4. keeps app-local nav entries for dashboard, admin, archive (passed into `appShellOverrides`)
+5. derives filtered nav locally from `shellModel.navItems`
+6. lets `FeatureShell` dispatch subshell sidebars for matched routes
+
+### appShellOverrides
+
+`appShellOverrides` is an `AppShellOverrides` prop on `ElevasisFeaturesProvider` that lets the host app inject nav items outside the manifest registry:
+
+- `primaryNavItems?: FeatureNavEntry[]` -- prepended before feature nav items in the primary nav position; organization-model label and path resolution is applied to these entries
+- `bottomNavItems?: FeatureNavEntry[]` -- rendered at the bottom of the shell nav; also subject to organization-model resolution and `filterNavLinks` filtering
+
+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.
+
+### External-consumer composition
+
+External shells consume the published `@elevasis/ui` provider surface. `_template/ui` imports individual manifests, composes a local `FEATURE_MANIFESTS: FeatureModule[]` array, and passes `canonicalOrganizationModel` (from `@foundation/config/organization-model`) into the provider. Host-local nav (home/dashboard) remains app-owned -- the provider covers shared shell features, not total shell ownership.
+
+See [Composition & Extensibility](./composition-extensibility.mdx) for the sidebar/page override patterns consumers use to customize shared features without forking.
+
+## Feature-Specific Sidebar Behavior
+
+### CRM Sidebar
+
+The CRM sidebar (`packages/ui/src/features/crm/sidebar/`) exports `CrmSidebar`, `CrmSidebarTop`, and `CrmSidebarMiddle`. `SavedViewsPanel` lives in `packages/ui/src/features/crm/workbench/SavedViewsPanel.tsx` and is exported from the CRM workbench barrel; it provides the saved contact views panel rendered within the CRM workbench surface.
+
+### Operations Sidebar
+
+`OperationsSidebarTop` in `packages/ui/src/features/operations/sidebar/OperationsSidebarTop.tsx` is context-aware by route:
+
+- 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.
+
+## Testing
+
+- `createTestFeaturesProvider` fixture at `packages/ui/src/provider/createTestFeaturesProvider.tsx` (internal; exported from `provider/index.ts`) gives tests a pre-wired provider with configurable organization model and feature access.
+- Resolver modules have focused unit tests (`RouteResolver.test.ts`, `NavResolver.test.ts`).
+- `validateManifests.test.ts` covers manifest validation against the organization model.
+- `ElevasisFeaturesProvider.test.tsx`, `FeatureShell.test.tsx`, and `feature-contract.test.ts` cover runtime composition and the published surface.
+
+## 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.
+- **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.