@elevasis/sdk 1.4.0 → 1.5.0

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

@@ -0,0 +1,30 @@
+---
+title: Feature Registry
+description: Auto-generated catalog of registered feature manifests. Do not edit manually.
+---
+
+> **Auto-generated** from source manifests. Do not edit manually. Run `node scripts/monorepo/generate-scaffold-feature-registry.js` to regenerate.
+
+## Registered Feature Manifests
+
+| Feature Key | Access Key | Nav Label | Domains | Routes |
+| --- | --- | --- | --- | --- |
+| `crm` | `acquisition` | CRM | crm | /crm |
+| `delivery` | `delivery` | Projects | delivery | /projects |
+| `lead-gen` | `acquisition` | Lead Gen | lead-gen | /lead-gen |
+| `monitoring` | `monitoring` | Monitoring | — | — |
+| `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
+
+Values defined in `FeatureKeySchema` (`packages/core/src/organization-model/domains/features.ts`):
+
+```typescript
+type OrganizationModelFeatureKey = 'acquisition' | 'delivery' | 'operations' | 'monitoring' | 'settings' | 'seo' | 'calibration'
+```
+
+These are the valid values for `accessFeatureKey` in a `FeatureModule` manifest and for feature-flag gating in the organization model.

package/reference/scaffold/reference/glossary.md

@@ -0,0 +1,88 @@
+---
+title: Glossary
+description: Terminology disambiguation for Organization OS concepts used in the template scaffold, foundations, and published packages.
+---
+
+# Glossary
+
+For canonical (internal) definitions, see the Organization OS glossary in the monorepo architecture docs.
+
+This condensed version covers every ambiguity-prone term a template consumer or agent is likely to encounter. Alphabetical within each section.
+
+---
+
+## 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.
+
+**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.
+
+**Contract** -- the publishable I/O boundary: Zod schemas in `foundations/types/index.ts` for workflow inputs/outputs, or the `FeatureModule` TypeScript shape for shell features. Distinct from "manifest": a contract is the structural definition; a manifest is a specific feature instance conforming to that shape.
+
+**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.
+
+**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:
+
+- **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.
+
+**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.
+
+**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`.
+
+**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.
+
+**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**).
+
+**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`.
+
+**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.
+
+**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.
+
+**Topology** -- resource relationships (`triggers`, `uses`, `approval`) declared in `DeploymentSpec.relationships` and `HumanCheckpointDefinition.routesTo`. Used for Command View graph edges.
+
+---
+
+## Package-Boundary Cheat Sheet
+
+**`@elevasis/core`** (published npm)
+
+- `OrganizationModel`, `OrganizationModelFeatureKey`, `OrganizationModelSurface`, `OrganizationModelResourceMapping`
+- `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
+- `MembershipFeatureConfig`
+
+**`@elevasis/ui`** (published npm)
+
+- `FeatureModule`, `FeatureNavEntry`, `FeatureNavLink`
+- `ResolvedFeatureModule`, `ResolvedShellNavItem`
+- `FeatureGuard`, `AdminGuard`, `ProtectedRoute`
+- `ElevasisFeaturesProvider`, `ElevasisCoreProvider`, `useElevasisFeatures`
+- `FEATURE_KEY_ALIASES`, `createFeatureAccessHook`
+
+**`foundations/`** (local source package -- not published)
+
+- `canonicalOrganizationModel` -- passed to `ElevasisFeaturesProvider`
+- `organizationModel` -- enriched shape for app-local code
+- Workflow I/O schemas (`types/index.ts`)

package/reference/scaffold/ui/composition-extensibility.mdx

@@ -0,0 +1,216 @@
+---
+title: Composition & Extensibility
+description: Organization OS Toolkit layer guidance for customizing shared shell features without forking, including exported nav arrays, optional sidebar props, composable layout primitives, and the manifest.sidebar override pattern.
+---
+
+## Overview
+
+Within Organization OS, this doc covers the **Toolkit** layer: the primitives consumers use to customize shared shell features by composition instead of fork. Consumers extend nav items, inject panels, or wrap pages by combining published primitives and assigning a custom component to `manifest.sidebar`. Copying source is physically possible but unsupported -- a fork owns upstream drift forever.
+
+The core pattern: set `sidebar` on your manifest to a component that composes the feature's published pieces. If the published pieces can't express what you need, the missing export is a bug. File an issue instead of forking.
+
+Shipped in `@elevasis/ui >= 2.8.1`.
+
+## The Override Pattern
+
+Every `FeatureModule.sidebar` is a `ComponentType`. Consumers customize by:
+
+1. Importing the feature's published sidebar wrapper and middle component.
+2. Wrapping or replacing the middle with custom content.
+3. Spreading the stock manifest and setting `sidebar` to their component.
+4. Passing the customized manifest to `ElevasisFeaturesProvider`.
+
+No new manifest fields. No discriminated unions. No runtime machinery.
+
+## Decision Tree
+
+- **Adding or changing nav items?** -> Extend the exported item array and pass to `<*SidebarMiddle items={...}>`.
+- **Structural changes (injecting panels, wrapping sections)?** -> Compose `SidebarTop`, `SidebarMiddle`, and exported panels directly in your own component.
+- **Wrapping pages?** -> Import the feature's page component and wrap with custom chrome in a route file.
+- **None of these fits?** -> Missing export is the bug. File an issue.
+
+## Exported Primitives
+
+### Nav item arrays
+
+Re-exported from each feature's sidebar barrel:
+
+- `CRM_ITEMS` from `@elevasis/ui/features/crm`
+- `LEAD_GEN_ITEMS` from `@elevasis/ui/features/lead-gen`
+- `DELIVERY_PROJECT_ITEMS`, `DELIVERY_WORK_ITEMS`, `DELIVERY_COMMUNICATION_ITEMS` from `@elevasis/ui/features/delivery`
+
+Shape is the shared `NavItem` type exported from `@elevasis/ui/layout`.
+
+### Sidebar wrappers
+
+Thin Top+Middle composers. Each accepts optional `children?: ReactNode` that replaces the default middle:
+
+- `CrmSidebar`, `LeadGenSidebar`, `ProjectsSidebar`
+
+### Middle components with optional item props
+
+- `CrmSidebarMiddle` -- `items?: NavItem[]` (defaults to `CRM_ITEMS`)
+- `LeadGenSidebarMiddle` -- `items?: NavItem[]` (defaults to `LEAD_GEN_ITEMS`)
+- `ProjectsSidebarMiddle` -- `projectItems?`, `workItems?`, `communicationItems?` (each defaults to its respective exported array)
+
+Delivery's three sections are preserved intentionally -- a real UX pattern consumers may want to extend with additional sections.
+
+### Composable layout primitives
+
+From `@elevasis/ui/layout`:
+
+- `SubshellNavItem` -- individual nav link
+- `SubshellNavList` -- router-context-aware list renderer (accepts `items: NavItem[]`, derives active state via `useRouterContext()`)
+- `SubshellSidebarSection` -- section header with icon, label, optional top border
+- `NavItem` -- shared item shape type
+- `SubshellContainer` -- full-width, full-height flex wrapper that composes sidebar and content side by side
+- `SubshellRightSideContainer` -- content area column (`flex: 1`, `minWidth: 0`) that prevents sidebar from squeezing content
+- `SubshellContentContainer` -- scrollable content area with standard `md` padding and automatic topbar offset applied via `paddingTop`
+- `SubshellLoader` -- loading placeholder centered in the subshell viewport; reads the active loader from `AppearanceContext`
+
+`FeatureShell` wires these together at `width={250}` as the default sidebar width. Consumers composing their own shell layout can pass a different `width` prop to `SubshellSidebar`.
+
+### SubshellSidebar features
+
+`SubshellSidebar` is more than a thin wrapper. Key behaviors verified in source:
+
+- **Collapsible** -- controlled by `collapsible` prop (defaults to `true`) and `defaultOpen` prop (defaults to `true`). When collapsed, the sidebar animates to zero width and a small toggle button remains visible at the bottom-right edge.
+- **Glass morphism** -- applies `color-mix(in srgb, var(--glass-background) 80%, transparent)` as background and `var(--glass-blur)` as `backdropFilter`, consistent with the theme token system.
+- **Animated transitions** -- width and opacity animate on collapse/expand using `sidebarTransitionDuration` from the layout constants.
+- **Width** -- no built-in default; the caller supplies `width`. `FeatureShell` passes `250` and this is the canonical default for stock feature sidebars.
+
+From `@elevasis/ui/router/context`:
+
+- `useRouterContext` -- access route state for custom active-state logic
+
+### RouterAdapter interface
+
+`RouterAdapter` is the interface that bridges any router implementation to the shared layout primitives. Defined in `packages/ui/src/router/context.ts`:
+
+- `currentPath: string` -- current pathname, used by `SubshellNavList` to derive active state
+- `currentSearch?: string` -- current search string (optional)
+- `navigate: (to: string) => void` -- imperative navigation
+- `Link: ElementType<LinkProps>` -- router-aware anchor component; `LinkProps` extends `AnchorHTMLAttributes\<HTMLAnchorElement>` with a required `to: string` field
+
+Consumers calling `useRouterContext()` get back a `RouterAdapter`. Any component that needs to read `currentPath` or call `navigate` can use the hook directly rather than prop-drilling from a parent.
+
+### TanStackRouterBridge
+
+`TanStackRouterBridge` is the concrete `RouterAdapter` implementation for TanStack Router. Exported from `packages/ui/src/router/providers/TanStackRouterBridge.tsx` and available via `@elevasis/ui/router`.
+
+It wraps `RouterProvider` and supplies the adapter by reading `useLocation` and `useRouter` from `@tanstack/react-router`. The adapter value is stabilized with `useMemo` to prevent unnecessary re-renders in downstream consumers. Place it inside TanStack's `RouterProvider`:
+
+```tsx
+<TanStackRouterBridge>
+  <ElevasisFeaturesProvider ...>
+    <FeatureShell>...</FeatureShell>
+  </ElevasisFeaturesProvider>
+</TanStackRouterBridge>
+```
+
+Consumers using a different router can implement `RouterAdapter` directly and pass it to `RouterProvider` instead of using this bridge.
+
+### Feature panels (CRM)
+
+- `MyTasksPanel`, `QuickCreateActions` -- exported from `@elevasis/ui/features/crm`, included by default in `CrmSidebarMiddle`; consumers composing their own middle can re-include them explicitly.
+
+### Feature pages
+
+Every page each feature renders is exported from its feature barrel, so consumers can wrap with custom chrome without forking:
+
+- CRM: `DealsListPage`, `DealDetailPage`
+- Lead-gen: `LeadGenOverviewPage`, `LeadGenDeliverabilityPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`
+- Delivery: `AllTasksPage`, `UpcomingMilestonesPage`, `ProjectsListPage`, `ProjectDetailPage`
+- Operations, monitoring, settings -- full page inventories exported from their feature barrels
+
+## Consumer Patterns
+
+### 1. Extend nav items (shortest path)
+
+```tsx
+import { CrmSidebar, CrmSidebarMiddle, CRM_ITEMS } from '@elevasis/ui/features/crm'
+import { IconFileText } from '@tabler/icons-react'
+
+const customItems = [
+  ...CRM_ITEMS,
+  { label: 'Reports', to: '/crm/reports', icon: IconFileText, exact: false },
+]
+
+const MyCrmSidebar = () => (
+  <CrmSidebar>
+    <CrmSidebarMiddle items={customItems} />
+  </CrmSidebar>
+)
+
+const customCrmManifest = { ...crmManifest, sidebar: MyCrmSidebar }
+```
+
+### 2. Inject a new delivery section (compose from primitives)
+
+```tsx
+import {
+  ProjectsSidebar,
+  DELIVERY_PROJECT_ITEMS,
+  DELIVERY_WORK_ITEMS,
+  DELIVERY_COMMUNICATION_ITEMS,
+} from '@elevasis/ui/features/delivery'
+import { SubshellSidebarSection, SubshellNavList } from '@elevasis/ui/layout'
+import { Stack } from '@mantine/core'
+import { IconChartBar, IconListCheck, IconMessageCircle } from '@tabler/icons-react'
+
+const ANALYTICS_ITEMS = [
+  { label: 'Dashboard', to: '/projects/analytics', icon: IconChartBar, exact: true },
+]
+
+const MyDeliveryMiddle = () => (
+  <Stack gap={0} style={{ flex: 1, overflowY: 'auto' }}>
+    <Stack gap={0} p="sm"><SubshellNavList items={DELIVERY_PROJECT_ITEMS} /></Stack>
+    <SubshellSidebarSection icon={IconListCheck} label="Work" withTopBorder />
+    <Stack gap={0} p="sm"><SubshellNavList items={DELIVERY_WORK_ITEMS} /></Stack>
+    <SubshellSidebarSection icon={IconMessageCircle} label="Communication" withTopBorder />
+    <Stack gap={0} p="sm"><SubshellNavList items={DELIVERY_COMMUNICATION_ITEMS} /></Stack>
+    <SubshellSidebarSection icon={IconChartBar} label="Analytics" withTopBorder />
+    <Stack gap={0} p="sm"><SubshellNavList items={ANALYTICS_ITEMS} /></Stack>
+  </Stack>
+)
+
+const MyDeliverySidebar = () => (
+  <ProjectsSidebar>
+    <MyDeliveryMiddle />
+  </ProjectsSidebar>
+)
+```
+
+### 3. Wrap a page with custom chrome
+
+```tsx
+// in a route file
+import { DealsListPage } from '@elevasis/ui/features/crm'
+
+export default function CustomDealsRoute() {
+  return (
+    <MyChromeWrapper>
+      <DealsListPage />
+    </MyChromeWrapper>
+  )
+}
+```
+
+## Operations & Unmodified Features
+
+- **Operations** -- uses `sidebar?: ComponentType` with route-aware dispatch; the items-prop pattern does not apply.
+- **Monitoring, Settings** -- no subshell sidebar. No customization surface needed.
+- **SEO** -- has sidebar components (`SEOSidebar`, `SEOSidebarTop`, `SEOSidebarMiddle`) but no page inventory in `@elevasis/ui`.
+
+## Publish-Surface Discipline
+
+All primitives above flow through published subpaths (`@elevasis/ui/features/<feature>`, `@elevasis/ui/layout`, `@elevasis/ui/router/context`). Any new primitive must sync four files per `.claude/rules/ui-package.md`: `package.json` `exports`, `publishConfig.exports`, `rollup.dts.config.mjs`, and `tsup.config.ts`.
+
+The published barrel (`packages/ui/src/provider/published.ts`) remains headless -- no Mantine-dependent visual pieces leak into the external contract.
+
+## What Not to Do
+
+- **Don't fork sidebar files into your app tree.** You own upstream drift forever.
+- **Don't redefine `NavItem` locally.** Import it from `@elevasis/ui/layout` so future shape changes stay coherent.
+- **Don't monkey-patch `FEATURE_MANIFESTS`.** It's a published convenience constant; consumers build their own manifest array and pass it to the provider.
+- **Don't add discriminated-union sidebar configuration to manifests.** The single pattern (assign a component to `manifest.sidebar`) is intentional.

package/reference/scaffold/ui/customization.md

@@ -0,0 +1,239 @@
+---
+title: Customizing Features
+description: One pattern for customizing feature sidebars and pages -- set manifest.sidebar to a component composing the feature's published pieces. Decision tree + three worked examples.
+---
+
+# Customizing Features
+
+**Status:** 🟢 Stable
+
+> **Requires `@elevasis/ui` >= 2.8.1.**
+
+There is one pattern for customizing a feature's sidebar or pages: set `sidebar` on your manifest override to a component that composes the feature's published pieces. Pass custom `items` to swap the nav array, or compose `SidebarTop` + `SidebarMiddle` + exported panels directly for structural changes. Never fork a source file as a first resort -- if you copy source you own upstream drift forever.
+
+## Decision Tree
+
+**Adding or changing nav items?** Extend the exported item array and pass to `<*SidebarMiddle items={...}>`. This covers the vast majority of sidebar customization needs.
+
+**Structural changes (injecting panels, reordering sections, wrapping sections)?** Compose `SidebarTop`, `SidebarMiddle`, and exported panels (`MyTasksPanel`, `QuickCreateActions`) directly into your own component and assign it to the manifest's `sidebar` field.
+
+**Wrapping pages?** Import the feature's page component and wrap with custom chrome in a route file.
+
+**Neither fits?** The missing export is a bug in `@elevasis/ui` -- file an issue. Copying source is physically possible but unsupported. You own upstream drift forever.
+
+## Worked Example 1: Sidebar Nav Extension
+
+Extend CRM's nav by spreading `CRM_ITEMS` and appending a Reports entry. Pass the extended array to `CrmSidebarMiddle`.
+
+Wire the override in `ui/src/routes/__root.tsx`, where feature manifests are assembled before being passed to `ElevasisFeaturesProvider`.
+
+```tsx
+// ui/src/routes/__root.tsx (excerpt -- add after existing imports)
+
+import { crmManifest, CrmSidebar, CrmSidebarMiddle, CRM_ITEMS } from '@elevasis/ui/features/crm'
+import { IconFileText } from '@tabler/icons-react'
+import type { NavItem } from '@elevasis/ui/layout'
+
+// Extend the published CRM nav array with a project-specific Reports entry.
+const customCrmItems: NavItem[] = [
+  ...CRM_ITEMS,
+  { label: 'Reports', to: '/crm/reports', icon: IconFileText, exact: false }
+]
+
+// Compose CrmSidebar (Top + Middle) with the extended item list.
+const MyCrmSidebar = () => (
+  <CrmSidebar>
+    <CrmSidebarMiddle items={customCrmItems} />
+  </CrmSidebar>
+)
+
+// Override the manifest's sidebar, keeping every other field unchanged.
+const customCrmManifest = { ...crmManifest, sidebar: MyCrmSidebar }
+```
+
+Then swap `crmManifest` for `customCrmManifest` in the `FEATURE_MANIFESTS` array:
+
+```tsx
+// In the FEATURE_MANIFESTS array (same file)
+const FEATURE_MANIFESTS: FeatureModule[] = [
+  leadGenManifest,
+  customCrmManifest,   // <-- replaces crmManifest
+  deliveryManifest,
+  operationsManifest,
+  monitoringManifest,
+  settingsManifest
+]
+```
+
+Your new `/crm/reports` route file still needs to be created in `ui/src/routes/crm/` -- the nav item just controls the link.
+
+## Worked Example 2: Sidebar with Injected Panel
+
+Inject a custom panel between the nav list and the My Tasks section. Compose the parts explicitly rather than relying on `CrmSidebarMiddle`'s default layout.
+
+```tsx
+// ui/src/routes/__root.tsx (excerpt)
+
+import {
+  crmManifest,
+  CrmSidebar,
+  CrmSidebarMiddle,
+  CrmSidebarTop,
+  MyTasksPanel,
+  QuickCreateActions,
+  CRM_ITEMS
+} from '@elevasis/ui/features/crm'
+import { SubshellNavList, SubshellSidebarSection } from '@elevasis/ui/layout'
+import { Stack } from '@mantine/core'
+import { IconChartBar } from '@tabler/icons-react'
+
+// Custom middle that inserts a Pipeline Health panel between nav and My Tasks.
+const MyCrmMiddle = () => (
+  <Stack gap={0} style={{ flex: 1, overflowY: 'auto' }}>
+    <Stack gap={0} p="sm">
+      <SubshellNavList items={CRM_ITEMS} />
+    </Stack>
+    {/* Inject custom panel here */}
+    <SubshellSidebarSection icon={IconChartBar} label="Pipeline Health" withTopBorder />
+    <Stack gap={0} p="sm">
+      <PipelineHealthWidget />
+    </Stack>
+    {/* Preserve the My Tasks section from the default middle */}
+    <MyTasksPanel footer={<QuickCreateActions showSectionLabel={false} />} showSectionLabel />
+  </Stack>
+)
+
+// Full sidebar: Top stays unchanged, Middle is replaced.
+const MyCrmSidebar = () => (
+  <CrmSidebar>
+    <MyCrmMiddle />
+  </CrmSidebar>
+)
+
+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.
+
+## Worked Example 3: Page Wrapping
+
+Import a feature's page component and wrap it with custom chrome in a route file. This keeps the feature's business logic intact while adding project-specific framing (banners, secondary nav, analytics context, etc.).
+
+The exported CRM page components are `DealsListPage` and `DealDetailPage`:
+
+```tsx
+// ui/src/routes/crm/deals.index.tsx
+
+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 { Stack } from '@mantine/core'
+
+export const Route = createFileRoute('/crm/deals/')({
+  component: DealsListPageGuarded
+})
+
+function DealsListPageGuarded() {
+  return (
+    <ProtectedRoute>
+      <Stack gap={0}>
+        <ProjectAnnouncementBanner context="crm-deals" />
+        <DealsListPage />
+      </Stack>
+    </ProtectedRoute>
+  )
+}
+```
+
+The pattern is identical for `DealDetailPage`. Import the published component, wrap it in your chrome, export as the route component. No forking, no copying source.
+
+## Delivery: Three-Section Sidebar
+
+Delivery keeps three named sections (Projects, Work, Communication). It exports three separate arrays and `ProjectsSidebarMiddle` accepts three matching optional props -- one per section. There is no single `items` prop.
+
+```tsx
+// Adding items to an existing delivery section
+import {
+  deliveryManifest,
+  ProjectsSidebar,
+  ProjectsSidebarMiddle,
+  DELIVERY_PROJECT_ITEMS,
+  DELIVERY_WORK_ITEMS,
+  DELIVERY_COMMUNICATION_ITEMS
+} from '@elevasis/ui/features/delivery'
+import type { NavItem } from '@elevasis/ui/layout'
+import { IconChartBar } from '@tabler/icons-react'
+
+const customProjectItems: NavItem[] = [
+  ...DELIVERY_PROJECT_ITEMS,
+  { label: 'Analytics', to: '/projects/analytics', icon: IconChartBar, exact: false }
+]
+
+const MyDeliverySidebar = () => (
+  <ProjectsSidebar>
+    <ProjectsSidebarMiddle
+      projectItems={customProjectItems}
+      workItems={DELIVERY_WORK_ITEMS}
+      communicationItems={DELIVERY_COMMUNICATION_ITEMS}
+    />
+  </ProjectsSidebar>
+)
+
+const customDeliveryManifest = { ...deliveryManifest, sidebar: MyDeliverySidebar }
+```
+
+**Adding a new section** (not extending an existing one) requires composing from primitives. Use `SubshellSidebarSection` as the section header and `SubshellNavList` to render items inside it:
+
+```tsx
+import {
+  ProjectsSidebar,
+  DELIVERY_PROJECT_ITEMS,
+  DELIVERY_WORK_ITEMS,
+  DELIVERY_COMMUNICATION_ITEMS
+} from '@elevasis/ui/features/delivery'
+import { SubshellSidebarSection, SubshellNavList } from '@elevasis/ui/layout'
+import { Stack } from '@mantine/core'
+import { IconChartBar, IconListCheck, IconMessageCircle, IconBriefcase } from '@tabler/icons-react'
+import type { NavItem } from '@elevasis/ui/layout'
+
+const ANALYTICS_ITEMS: NavItem[] = [
+  { label: 'Dashboard', to: '/projects/analytics', icon: IconChartBar, exact: true }
+]
+
+const MyDeliveryMiddle = () => (
+  <Stack gap={0} style={{ flex: 1, overflowY: 'auto' }}>
+    <Stack gap={0} p="sm">
+      <SubshellNavList items={DELIVERY_PROJECT_ITEMS} />
+    </Stack>
+    <SubshellSidebarSection icon={IconListCheck} label="Work" withTopBorder />
+    <Stack gap={0} p="sm">
+      <SubshellNavList items={DELIVERY_WORK_ITEMS} />
+    </Stack>
+    <SubshellSidebarSection icon={IconMessageCircle} label="Communication" withTopBorder />
+    <Stack gap={0} p="sm">
+      <SubshellNavList items={DELIVERY_COMMUNICATION_ITEMS} />
+    </Stack>
+    <SubshellSidebarSection icon={IconChartBar} label="Analytics" withTopBorder />
+    <Stack gap={0} p="sm">
+      <SubshellNavList items={ANALYTICS_ITEMS} />
+    </Stack>
+  </Stack>
+)
+
+const MyDeliverySidebar = () => <ProjectsSidebar><MyDeliveryMiddle /></ProjectsSidebar>
+```
+
+This is the same compose-from-primitives path CRM consumers use for structural changes. No special API -- just `SubshellSidebarSection` + `SubshellNavList` from `@elevasis/ui/layout`.
+
+## Imports Cheat Sheet
+
+| What you need                                                                                                                                                         | Import from                      |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| `CRM_ITEMS`, `CrmSidebar`, `CrmSidebarTop`, `CrmSidebarMiddle`, `MyTasksPanel`, `QuickCreateActions`, `DealsListPage`, `DealDetailPage`, `crmManifest`                | `@elevasis/ui/features/crm`      |
+| `LEAD_GEN_ITEMS`, `LeadGenSidebar`, `LeadGenSidebarTop`, `LeadGenSidebarMiddle`, `leadGenManifest`                                                                    | `@elevasis/ui/features/lead-gen` |
+| `DELIVERY_PROJECT_ITEMS`, `DELIVERY_WORK_ITEMS`, `DELIVERY_COMMUNICATION_ITEMS`, `ProjectsSidebar`, `ProjectsSidebarTop`, `ProjectsSidebarMiddle`, `deliveryManifest` | `@elevasis/ui/features/delivery` |
+| `SubshellNavList`, `SubshellNavItem`, `SubshellSidebarSection`, `NavItem`                                                                                             | `@elevasis/ui/layout`            |
+| `FeatureModule`                                                                                                                                                       | `@elevasis/ui/provider`          |
+
+Operations, monitoring, and settings have no customizable sidebar items. Operations sidebar is route-aware dispatch and not extended via the `items` pattern.