@elevasis/sdk 1.44.2 → 1.45.0

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

@@ -1,236 +1,275 @@
----
-title: Composition & Extensibility
-description: Organization OS Toolkit layer guidance for customizing shared shell systems without forking, including exported nav arrays, optional sidebar props, composable layout primitives, and the manifest.sidebar override pattern.
----
+---
+title: Composition & Extensibility
+description: Organization OS Toolkit layer guidance for customizing shared shell systems without forking, including exported nav arrays, optional sidebar props, composable layout primitives, the manifest.sidebar override pattern, and the render-prop slot + zero-wiring default pattern for the shared session-chat surface.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-## Overview
-
-Within Organization OS, this doc covers the **Toolkit** layer: the primitives consumers use to customize shared shell systems 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 system'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 `SystemModule.sidebar` is a `ComponentType`. Consumers customize by:
-
-1. Importing the system'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 `ElevasisSystemsProvider`.
-
-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 system'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 system 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`
-
-`SystemShell` 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 behavior
-
-`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`. `SystemShell` passes `250` and this is the canonical default for stock system 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>
-  <ElevasisSystemsProvider ...>
-    <SystemShell>...</SystemShell>
-  </ElevasisSystemsProvider>
-</TanStackRouterBridge>
-```
-
-Consumers using a different router can implement `RouterAdapter` directly and pass it to `RouterProvider` instead of using this bridge.
-
-### System 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.
-
-### System pages
-
-Every page each system renders is exported from its system barrel, so consumers can wrap with custom chrome without forking:
-
-- CRM: `DealsListPage`, `DealDetailPage`
-- Lead-gen: `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`
-- Delivery: `AllTasksPage`, `UpcomingMilestonesPage`, `ProjectsListPage`, `ProjectDetailPage`
-- Operations, monitoring, settings -- full page inventories exported from their system 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 Systems
-
-- **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/<system>`, `@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.
-
-## Knowledge Browser Customization
-
-The Knowledge Browser follows the same pattern described in this document. The three tiers map directly:
-
-- **Tier 1** -- import `knowledgeManifest` from `@elevasis/ui/features/knowledge` and pass it to `ElevasisSystemsProvider`. No further code required.
-- **Tier 2** -- spread the manifest, override `sidebar` to a component that composes `KnowledgeSidebar` + `KnowledgeSidebarMiddle items={customItems}`. Same shape as the CRM example above.
-- **Tier 3** -- skip the manifest, own the route, call `bySystem` / `byKind` / `byOwner` from `@elevasis/core/knowledge` directly.
-
-One additional wiring step is required for Knowledge Browser that does not apply to CRM or Lead Gen: add `knowledgePlugin()` from `@elevasis/ui/vite-plugin-knowledge` to `vite.config.ts`. The plugin runs build-time MDX codegen so rendered body components are available at runtime.
-
-See [recipes/customize-knowledge-browser.md](../recipes/customize-knowledge-browser.md) for the full walkthrough including code examples, the CSS import requirement, and the full exports reference.
-
-Phase 1.5 adds two further extension surfaces documented in the same recipe file under the "Phase 1.5" section:
-
-- **Extending the SegmentedControl** -- supply a `segments` prop to `KnowledgeSidebarMiddle` to add custom mount-axis tabs beyond the default five (By Feature, By Kind, By Owner, Governs, Governed By).
+
+## Overview
+
+Within Organization OS, this doc covers the **Toolkit** layer: the primitives consumers use to customize shared shell systems 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 system'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 `SystemModule.sidebar` is a `ComponentType`. Consumers customize by:
+
+1. Importing the system'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 `ElevasisSystemsProvider`.
+
+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 system'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 system 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`
+
+`SystemShell` 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 behavior
+
+`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`. `SystemShell` passes `250` and this is the canonical default for stock system 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>
+  <ElevasisSystemsProvider ...>
+    <SystemShell>...</SystemShell>
+  </ElevasisSystemsProvider>
+</TanStackRouterBridge>
+```
+
+Consumers using a different router can implement `RouterAdapter` directly and pass it to `RouterProvider` instead of using this bridge.
+
+### System 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.
+
+### System pages
+
+Every page each system renders is exported from its system barrel, so consumers can wrap with custom chrome without forking:
+
+- CRM: `DealsListPage`, `DealDetailPage`
+- Lead-gen: `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`
+- Delivery: `AllTasksPage`, `UpcomingMilestonesPage`, `ProjectsListPage`, `ProjectDetailPage`
+- Operations, monitoring, settings -- full page inventories exported from their system 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 Systems
+
+- **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/<system>`, `@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.
+
+## Render-Prop Slots and Zero-Wiring Defaults
+
+Some shared pages expose a render-prop slot rather than rendering a concrete child directly. This keeps the package decoupled from host-specific details (API base URLs, router params) while still letting hosts customize the body.
+
+### Session-Chat Surface
+
+`SessionChatPage` (`@elevasis/ui/features/operations`) is the canonical example. It exposes `renderConversationView(args: ConversationViewSlotArgs)` as a render-prop slot threaded through `SessionChatInterface`. The slot was introduced so the package would not need to know a host's WebSocket base URL.
+
+**Zero-wiring default:** `renderConversationView` is optional. When omitted, `SessionChatPage` internally calls `useDefaultConversationViewRenderer`, which reads `apiUrl` from `useElevasisServices()` and returns `<SessionConversationView apiUrl={apiUrl} {...args} />`. Hosts that need a custom body pass the prop explicitly; customization is opt-in rather than mandatory.
+
+**Why `apiUrl` must come from context, not a prop.** `useSessionWebSocket` needs the raw base URL to derive the `ws(s)://` endpoint. `ElevasisServiceContextValue` exposes `apiRequest` (a closure), not the raw URL. The fix was adding `apiUrl: string` to `ElevasisServiceContextValue` so the package-level default renderer could construct the WebSocket URL without any host involvement. `ElevasisServiceProviderProps` accepts `apiUrl?: string` (defaults to `''`) for standalone and test usage; the guard inside `useDefaultConversationViewRenderer` throws clearly when `apiUrl` is empty in non-service-stack paths.
+
+**Shared component.** `SessionConversationView` (`packages/ui/src/features/operations/sessions/SessionConversationView.tsx`) is the concrete implementation: accepts `apiUrl: string` plus the four `ConversationViewSlotArgs` fields (`onConnectionStateChange`, `emptyStateText`, `emptyStateSubtext`, `placeholder`), calls `useSessionWebSocket(sessionId, apiUrl)`, merges history via `useSessionMessages` + `mergeSessionMessages`, and renders `ChatInterface`. Exported from `packages/ui/src/features/operations/index.ts` under the `// Sessions` block and available via `@elevasis/ui/features/operations`. `SessionConversationViewProps` is also exported.
+
+**Project-local route wrapper stays.** The thin host `SessionChatPage.tsx` wrapper still extracts the router param (`useParams`) and `isReady`/`organizationName` from host-owned auth context. These cannot move into the package without the package owning the host's route tree. The win is removing the mandatory conversation-view slot and the local stub, not the route wrapper itself.
+
+**Scope boundary.** `SessionConversationView` covers the session-detail/plain path only. The command-center `AssistantPanel` has a richer local `ConversationView` (`handleAssistantEvents`, `pageContext`, `sendMessageRef`, `onTokenUsage`, `onMessagesChange`, `messageAreaVariant`) that is left untouched -- that component is CC-only and out of scope for the shared surface.
+
+### The Slot-vs-Default Decision
+
+When deciding whether a render-prop slot needs a zero-wiring default:
+
+- **Provide a default** when most hosts want the same behaviour and only need to customize rarely. Make customization opt-in.
+- **Keep the slot required** only when every host genuinely needs to supply a different implementation and there is no sensible shared fallback.
+- **Expose context values** (like `apiUrl`) when the package-level default needs host-configured state that was previously consumed internally but not re-exposed.
+
+The `optional prop + self-default` pattern (one component, one mental model) is preferred over a separate `StandardizedXPage` wrapper, which would duplicate plumbing and invite drift.
+
+## Chat Surface Theme Integration
+
+The shared session-chat surface (`ChatInterface` and `ChatInputArea` in `packages/ui/src/components/chat/`) follows the same Mantine token system as all other `@repo/ui` panels.
+
+**Unified panel.** `ChatInterface` renders a single Mantine `<Paper withBorder p={0}>` that wraps both the message scroll area and the input bar. The `ScrollableContainer` inside is transparent and scrolls; `ChatInputArea` is inset at the bottom (`px="sm" pb="sm" flexShrink: 0`). This matches the surface, border, radius, and shadow of sibling `<Paper withBorder p="sm">` panels (for example, `ResourceDefinitionSection` in `packages/ui/src/components/resource-definition/ResourceDefinitionSection.tsx`).
+
+**Opaque input.** `ChatInputArea` uses `color-mix(in srgb, var(--color-text) 7%, var(--color-background))` as its fill instead of the translucent `--color-surface` token (`rgba(18,19,21,0.2)`). This makes the input bar read as a solid element rather than a glassy void.
+
+**`messageAreaVariant` semantics.** The prop on `ChatInterface` now toggles paneled-vs-transparent on the scroll area. The grid/gradient/radial background is removed. The `variant` prop was dropped from `ScrollableContainer` (internal component) as it is no longer needed.
+
+**Token guidance.** Never use hardcoded hex values or `mantine-gray-*` tokens for chat surface backgrounds. Use semantic tokens (`--color-background`, `--color-text`, `--glass-background`, `--glass-blur`) per `.claude/rules/theme-system.md`. A bare `<Paper>` is not automatically opaque in this theme -- several Paper variants render `rgba(0,0,0,0)`; the glass look comes from `withBorder` combined with the theme defaults.
+
+## Knowledge Browser Customization
+
+The Knowledge Browser follows the same pattern described in this document. The three tiers map directly:
+
+- **Tier 1** -- import `knowledgeManifest` from `@elevasis/ui/features/knowledge` and pass it to `ElevasisSystemsProvider`. No further code required.
+- **Tier 2** -- spread the manifest and override `sidebar` with a project-owned component. Same shape as the CRM example above. Note that the Knowledge Browser's own sidebar parts are internal: `@elevasis/ui/features/knowledge` publishes `knowledgeManifest` and nothing else, so compose from the published knowledge primitives instead.
+- **Tier 3** -- skip the manifest, own the route, call `bySystem` / `byKind` / `byOwner` from `@elevasis/core/knowledge` directly.
+
+One additional wiring step is required for Knowledge Browser that does not apply to CRM or Lead Gen: add `knowledgePlugin()` from `@elevasis/ui/vite-plugin-knowledge` to `vite.config.ts`. The plugin runs build-time MDX codegen so rendered body components are available at runtime.
+
+See [recipes/customize-knowledge-browser.md](../recipes/customize-knowledge-browser.md) for the full walkthrough including code examples, the CSS import requirement, and the full exports reference.
+
+Phase 1.5 adds a further extension surface documented in the same recipe file under the "Phase 1.5" section:
+
 - **Replacing `DescribeNodeView`** -- override the `/knowledge/:nodeId` route component to swap the entire main-pane dispatcher, or wrap `DescribeNodeView` from `@elevasis/ui/knowledge` to intercept specific node-kind views while falling back to the platform defaults for the rest.
-
-## 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 `SYSTEM_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.
+
+## 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 `SYSTEM_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/feature-flags-and-gating.md

@@ -43,18 +43,26 @@ import { AccessGuard } from '@elevasis/ui/auth'
 
 ## Adding A Gated System
 
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
 ```ts
-{
-  id: 'analytics',
-  label: 'Analytics',
-  lifecycle: 'active',
-  path: '/analytics',
-  uiPosition: 'sidebar-primary'
+systems: {
+  analytics: {
+    id: 'analytics',
+    order: 70,
+    label: 'Analytics',
+    lifecycle: 'active',
+    ui: { path: '/analytics' }
+  }
 }
 ```
 
+`order` is required. Sidebar placement is authored in `navigation.sidebar`, not via the deprecated top-level `uiPosition`.
+
 Use the same System path in `AccessGuard accessKey` and `SystemModule.systemId`. For action-level checks, use the structured key shape:
 
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
 ```ts
 { systemPath: 'analytics', action: 'manage' }
 ```