@elevasis/sdk 1.39.0 → 1.41.0

package/reference/scaffold/recipes/extend-crm.md

@@ -25,14 +25,14 @@ CRM is a layered platform surface, not one component:
 - **Headless hooks:** deal, company, contact, note, task, list, transition, and action hooks live under `@elevasis/ui/hooks`.
 - **Action system:** `ActionDef`, `deriveActions`, and the caller-supplied provider-level `crmActions` catalog configure deal actions. The published `@elevasis/sdk` surface ships no default Elevasis action catalog -- projects supply their own `ActionDef[]`.
 - **Workflow adapters:** `crm` and `acqDb` from `@elevasis/sdk/worker` let workflows read and mutate CRM/acquisition data through platform tools.
-- **System API Interface:** `sales.crm` uses the flat `system.apiInterface` marker for its API-backed CRM boundary. Readiness is derived from scoped resources, ontology bindings, required catalogs, and scoped topology grants. Cross-system lead-gen handoff belongs in scoped topology, not a top-level Bridge Contract or a hand-authored handoff interface field. Generated contract docs expose the current CRM shapes in `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`.
+- **System API Interface:** `sales.crm` uses the flat `system.apiInterface` marker for its API-backed CRM boundary. Readiness is derived from scoped resources, ontology bindings, required catalogs, and scoped topology grants. Cross-system lead-gen handoff belongs in scoped topology, not a top-level Bridge Contract or a hand-authored handoff interface field. Generated contract docs expose the current CRM shapes in `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`.
 
 ## Decision Table
 
 | User wants                                                                       | Start here                                                                                          | Notes                                                                                                                                                             |
 | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Change CRM System availability, labels, pipeline stages, resource descriptors, or API readiness | `core/config/organization-model.ts`                                                                 | Treat this as Organization OS work. Mark `sales.crm.apiInterface` active only when scoped CRM resources and ontology are ready for API-backed actions.             |
-| Add CRM sidebar nav or a CRM route                                               | `@elevasis/ui/features/crm` and `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` | Prefer manifest/sidebar composition. Do not fork shared source first.                                                                                             |
+| Add CRM sidebar nav or a CRM route                                               | `@elevasis/ui/features/crm` and `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` | Prefer manifest/sidebar composition. Do not fork shared source first.                                                                                             |
 | Wrap a shared CRM page with project chrome                                       | `DealsListPage`, `DealDetailPage`, `CrmOverview` from `@elevasis/ui/features/crm`                   | Keep route files thin and put project-specific logic in local feature modules.                                                                                    |
 | Build a custom deal page                                                         | `useDealDetail`, `useDealNotes`, `useDealTasks`, `useExecuteAction` from `@elevasis/ui/hooks`       | Use hooks for platform data and compose your own UI.                                                                                                              |
 | Add, hide, or replace deal action buttons                                        | [customize-crm-actions.md](customize-crm-actions.md)                                                | Start with the shared `crmActions` provider path; use project-owned UI when a custom workflow path is outside platform-known/default action dispatch constraints. |
@@ -56,7 +56,7 @@ CRM is a layered platform surface, not one component:
 
 Read the generated contracts before changing typed boundaries:
 
-`node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+`operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
 
 Look for the **CRM Platform Primitives** section. It includes deal stages, deal rows, task shapes, API schemas, action definitions, and the focused CRM workflow adapter map. The broader acquisition/list adapter maps live under **Lead Gen Platform Primitives**.
 
@@ -92,7 +92,7 @@ export const customCrmManifest: SystemModule = {
 
 Then replace `crmManifest` with `customCrmManifest` in the local `SYSTEM_MANIFESTS` array and add the matching route under `ui/src/routes/crm/`.
 
-For structural changes, compose `CrmSidebarTop`, `SubshellNavList`, `SubshellSidebarSection`, `MyTasksPanel`, and `QuickCreateActions`. The full sidebar decision tree lives in `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`.
+For structural changes, compose `CrmSidebarTop`, `SubshellNavList`, `SubshellSidebarSection`, `MyTasksPanel`, and `QuickCreateActions`. The full sidebar decision tree lives in `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`.
 
 ## 2. Wrap Shared CRM Pages
 

package/reference/scaffold/recipes/extend-lead-gen.md

@@ -27,14 +27,14 @@ Lead gen is a layered platform surface, not one component. Shared packages own s
 - **Acquisition substrate:** `acq_lists`, `acq_companies`, `acq_contacts`, `acq_artifacts`, list members, list companies, telemetry, and stateful transition shapes are exposed through generated contracts.
 - **Core readers:** `getLeadGenStageCatalog`, `getAllBuildTemplates`, `getProspectingBuildTemplateOptions`, and `createBuildPlanSnapshotFromTemplateId` from `@elevasis/core` read caller-supplied Organization Model/template values. They do not ship tenant catalogs or default templates.
 - **Workflow adapters:** `acqDb`, `list`, and `listBuilderWorkflow` from `@elevasis/sdk/worker` let workflows read and mutate lead-gen data through platform tools.
-- **System API Interface:** `sales.lead-gen` uses the flat `system.apiInterface` marker for its API-backed lead-gen boundary. Readiness is derived from scoped resources, ontology bindings, required catalogs, and scoped topology grants. Lead-gen-to-CRM handoff uses scoped topology, not a top-level Bridge Contract or a hand-authored handoff interface field. Generated contract docs expose the current lead-gen shapes in `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`.
+- **System API Interface:** `sales.lead-gen` uses the flat `system.apiInterface` marker for its API-backed lead-gen boundary. Readiness is derived from scoped resources, ontology bindings, required catalogs, and scoped topology grants. Lead-gen-to-CRM handoff uses scoped topology, not a top-level Bridge Contract or a hand-authored handoff interface field. Generated contract docs expose the current lead-gen shapes in `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`.
 
 ## Decision Table
 
 | User wants                                                                                                                                          | Start here                                                                                                                                      | Notes                                                                                                                                                                                              |
 | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Change lead-gen System availability, labels, quick access, stage catalogs, build templates, workflow actions, resources, topology, or API readiness | `core/config/organization-model.ts`                                                                                                             | Treat this as Organization OS work. Tenant projects own these values. Mark `sales.lead-gen.apiInterface` active only when scoped resources and ontology are ready for API-backed lead-gen actions. |
-| Add lead-gen sidebar nav or a lead-gen route                                                                                                        | `@elevasis/ui/features/lead-gen` and `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`                                        | Prefer manifest/sidebar composition. Do not fork shared source first.                                                                                                                              |
+| Add lead-gen sidebar nav or a lead-gen route                                                                                                        | `@elevasis/ui/features/lead-gen` and `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`                                        | Prefer manifest/sidebar composition. Do not fork shared source first.                                                                                                                              |
 | Wrap a shared lead-gen page with project chrome                                                                                                     | `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `ListBuilderPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`            | Keep route files thin and put project-specific behavior in local feature modules.                                                                                                                  |
 | Build a custom campaign/list workspace                                                                                                              | `ListBuilderPage`, `useLists`, `useList`, `useListProgress`, `useListExecutions`, `useWorkflowExecution`, `useExecutionSSE` from `@elevasis/ui` | Use the shared builder when possible; otherwise compose hooks for platform data and workflow execution.                                                                                            |
 | Add or change list-builder workflow buttons/forms                                                                                                   | `ui/src/config/listActions.ts` plus `ElevasisUIProvider listActions={listActions}` / `createElevasisApp({ listActions })`                       | The shared UI owns the registry contract. The project owns workflow ids, action keys, Zod schemas, layouts, and default inputs.                                                                    |
@@ -64,7 +64,7 @@ Lead gen is a layered platform surface, not one component. Shared packages own s
 
 Read the generated contracts before changing typed boundaries:
 
-`node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+`operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
 
 Look for the **Lead Gen Platform Primitives** section. It includes list shapes, company/contact shapes, list config, telemetry, artifacts, list members, stateful pipeline definitions, and workflow adapter method maps.
 
@@ -98,7 +98,7 @@ export const customLeadGenManifest: SystemModule = {
 
 Then replace `leadGenManifest` with `customLeadGenManifest` in the local `SYSTEM_MANIFESTS` array and add the matching route under `ui/src/routes/lead-gen/`.
 
-For structural changes, compose `LeadGenSidebarTop`, `SubshellNavList`, and `SubshellSidebarSection`. The full sidebar decision tree lives in `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`.
+For structural changes, compose `LeadGenSidebarTop`, `SubshellNavList`, and `SubshellSidebarSection`. The full sidebar decision tree lives in `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`.
 
 ## 2. Wrap Shared Lead-Gen Pages
 

package/reference/scaffold/reference/glossary.md

@@ -16,7 +16,7 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **Boundary invariant** -- Organization Model rule that local resources may bind local System ontology directly, while sibling-System API behavior needs explicit scope through topology. For System Interfaces, lead-gen-to-CRM handoff is allowed through the `sales.lead-gen/crm-handoff` consumer, the `sales.crm/api` provider, scoped resources, and a `metadata.systemInterfaceGrant` topology grant.
 
-**Capability catalog** -- generated SDK-bundled reference that lists the closed System Interface profiles supported by the installed package, their required System paths, interface keys, and derived-readiness requirements. Current source: `packages/core/src/reference/_generated/system-interface-capabilities.md`; SDK mirror: `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md`.
+**Capability catalog** -- generated SDK-bundled reference that lists the closed System Interface profiles supported by the installed package, their required System paths, interface keys, and derived-readiness requirements. Current source: `packages/core/src/reference/_generated/system-interface-capabilities.md`; SDK mirror: `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md`.
 
 **Contract** -- the publishable boundary a consumer depends on: Zod schemas, TypeScript types, provider props, resource definitions, resource ontology workflow I/O refs, or generated reference docs. Retired authored System/Bridge Contract surfaces such as `System.contracts`, `bridgeContracts`, and versioned `*@v1` OM contract IDs are not current authoring patterns.
 

package/reference/scaffold/ui/customization.md

@@ -1,246 +1,246 @@
----
-title: Customizing Systems
-description: One pattern for customizing system sidebars and pages -- set manifest.sidebar to a component composing the system's published pieces. Decision tree + three worked examples.
----
+---
+title: Customizing Systems
+description: One pattern for customizing system sidebars and pages -- set manifest.sidebar to a component composing the system's published pieces. Decision tree + three worked examples.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-# Customizing Systems
-
-**Status:** 🟢 Stable
-
-> **Requires `@elevasis/ui` >= 2.8.1.**
-
-There is one pattern for customizing a system's sidebar or pages: set `sidebar` on your manifest override to a component that composes the system'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 system'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 system manifests are assembled before being passed to `ElevasisSystemsProvider`.
-
-```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 `SYSTEM_MANIFESTS` array:
-
-```tsx
-// In the SYSTEM_MANIFESTS array (same file)
-const SYSTEM_MANIFESTS: SystemModule[] = [
-  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/lib/components/`. Keep route files and `__root.tsx` thin -- push component logic into feature modules.
-
-## Worked Example 3: Page Wrapping
-
-Import a system's page component and wrap it with custom chrome in a route file. This keeps the system'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 '@/lib/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`.
-
-For broader CRM extension work across pages, hooks, actions, workflows, and org-model boundaries, start with `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md`.
-
-For broader lead-gen extension work across pages, hooks, list/member state, artifacts, workflows, and org-model boundaries, start with `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md`.
-
-## 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`            |
-| `SystemModule`                                                                                                                                                        | `@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.
+
+# Customizing Systems
+
+**Status:** 🟢 Stable
+
+> **Requires `@elevasis/ui` >= 2.8.1.**
+
+There is one pattern for customizing a system's sidebar or pages: set `sidebar` on your manifest override to a component that composes the system'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 system'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 system manifests are assembled before being passed to `ElevasisSystemsProvider`.
+
+```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 `SYSTEM_MANIFESTS` array:
+
+```tsx
+// In the SYSTEM_MANIFESTS array (same file)
+const SYSTEM_MANIFESTS: SystemModule[] = [
+  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/lib/components/`. Keep route files and `__root.tsx` thin -- push component logic into feature modules.
+
+## Worked Example 3: Page Wrapping
+
+Import a system's page component and wrap it with custom chrome in a route file. This keeps the system'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 '@/lib/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`.
+
+For broader CRM extension work across pages, hooks, actions, workflows, and org-model boundaries, start with `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md`.
+
+For broader lead-gen extension work across pages, hooks, list/member state, artifacts, workflows, and org-model boundaries, start with `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md`.
+
+## 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`            |
+| `SystemModule`                                                                                                                                                        | `@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.

package/reference/sdk/platform-tools/index.mdx

@@ -134,7 +134,7 @@ Call any supported LLM from your workflow with no API keys required. Keys are re
 | ------------ | --------------------------------------------------------- |
 | `google`     | `gemini-3-flash-preview`, `gemini-3.1-flash-lite-preview` |
 | `openai`     | `gpt-5`, `gpt-5.4-mini`, `gpt-5.4-nano`                   |
-| `anthropic`  | `claude-sonnet-4-5`                                       |
+| `anthropic`  | `claude-sonnet-5`                                         |
 | `openrouter` | `openrouter/z-ai/glm-5`                                   |
 
 **Key params:** `provider`, `model`, `messages` (`{ role, content }[]`), `responseSchema` (optional JSON Schema), `temperature` (optional).

package/reference/sdk/platform-tools/type-safety.mdx

@@ -19,7 +19,7 @@ The approach: tighten types where misconfiguration is a realistic foot-gun, and
 // Required -- both fields must be specified inline
 await llm.generate({
   provider: 'anthropic',
-  model: 'claude-sonnet-4-5',
+  model: 'claude-sonnet-5',
   messages: [...],
   responseSchema: {...},
 })