@elevasis/sdk 1.21.0 → 1.22.1

package/reference/claude-config/rules/ui.md

@@ -1,200 +1,200 @@
----
-description: UI shell, route structure, auth flow, API access, and template customization points for the ui/ surface
-paths:
-  - ui/**
----
-
-# UI Features
-
-**Status:** Stable
-
-## App Shell Overview
-
-The template frontend is a React 19 + TanStack Router app that composes a local dashboard shell with published System modules from `@elevasis/ui`.
-
-The main join points are:
-
-- `ui/src/main.tsx` -- boots the app with `ElevasisUIProvider`, query client, theme config, WorkOS AuthKit, notifications, and the generated route tree
-- `ui/src/routes/__root.tsx` -- composes the authenticated shell with `ElevasisSystemsProvider`, published System modules, app-local dashboard nav, shell runtime dependencies, and `SystemShell`
-- `ui/src/config/nav-items.ts` -- keeps the host-local dashboard entry separate from the published feature manifests
-- `core/config/organization-model.ts` -- is the template's semantic source of truth, adapting `@elevasis/core/organization-model` into the preserved branding, dashboard label, quick-access, System labels, resource descriptors, and shell helpers
-
-Published System modules mounted by the template shell:
-
-- `lead-gen`
-- `crm`
-- `delivery` at `/projects`
-- `operations`
-- `monitoring`
-- `settings`
-
-Important distinction:
-
-- shared modules gate on current org-model System keys such as `sales.lead-gen` and `projects`
-- template routes and local nav may still use legacy aliases such as `crm`, `lead-gen`, and `projects`
-- `core/config/organization-model.ts` and `ui/src/lib/hooks/useFeatureAccess.ts` are the bridge between those two vocabularies
-
-Dashboard remains a host-local route at `/`, not a shared feature manifest.
-
-This template should be treated as the downstream reference implementation for this composition:
-
-- foundations owns the organization/runtime semantics
-- `ui/src/config/nav-items.ts` preserves the host-local dashboard entry instead of pushing that concern into shared manifests
-- `ui/src/routes/__root.tsx` threads `canonicalOrganizationModel` from foundations into `ElevasisSystemsProvider` so the shared shell/runtime uses the same semantic source of truth as the local template helpers
-- host-local customizations still stay local: dashboard remains app-owned nav, branding stays in app config, and quick-access/dashboard UX stays in the template app
-
-## Auth and Initialization
-
-The app uses WorkOS AuthKit through `ElevasisUIProvider`. Authentication is enforced by the local `ProtectedRoute` wrapper in `ui/src/features/auth/ProtectedRoute.tsx`.
-
-**Sign-in flow:**
-
-1. Unauthenticated user hits a protected route -- `ProtectedRoute` redirects to `/login?returnTo=<path>`
-2. `/login` renders a sign-in card; user clicks Sign In, triggering `signIn({ returnTo })` from `useAuth()`
-3. User authenticates on the WorkOS-hosted sign-in page
-4. WorkOS redirects back to `/auth-redirect` -- `ui/src/routes/auth-redirect.tsx` waits for auth to complete, then navigates to the requested path or `/`
-5. User lands on the home page, fully authenticated
-
-**Route protection:**
-
-Wrap protected route components with the local `ProtectedRoute` from `@/features/auth`, which adds the full-screen loader and delegates to the shared guard from `@elevasis/ui/auth`:
-
-```tsx
-import { ProtectedRoute } from '@/features/auth'
-
-function HomePageGuarded() {
-  return (
-    <ProtectedRoute>
-      <HomePage />
-    </ProtectedRoute>
-  )
-}
-```
-
-**Initialization state:**
-
-Use `useInitialization()` from `@elevasis/ui/initialization` anywhere inside the app to read aggregated auth + org readiness:
-
-```ts
-const { allReady, userReady, isInitializing, error, retry, profile } = useInitialization()
-```
-
-**Organization context:**
-
-Use `useOrganization()` from `@elevasis/ui/organization` to access org-scoped IDs and memberships:
-
-```ts
-const { currentWorkOSOrganizationId, currentSupabaseOrganizationId, memberships, switchOrganization } = useOrganization()
-```
-
-## API and Streaming
-
-Use `useApiClient()` from `@/lib/hooks/useApiClient` in route components and feature hooks:
-
-```ts
-const { apiRequest, isOrganizationReady } = useApiClient()
-const data = await apiRequest('/executions', { method: 'GET' })
-```
-
-The template also re-exports `useApiClientContext()` and the shared API client types from `@/lib/hooks/useApiClient`.
-
-For real-time updates, feature surfaces use the local singleton wrapper:
-
-```ts
-import { sseConnectionManager } from '@/lib/sse/SSEConnectionManager'
-```
-
-**WorkOS config:**
-
-WorkOS `clientId`, `redirectUri`, and `signoutUri` are hardcoded in `ui/src/config/workos.ts` -- no UI env vars are required to run the template. Edit that file if a fork needs a different WorkOS client. The dev server runs on port `4300` with Vite `strictPort: true`, so a second `pnpm -C ui dev` on the same machine fails fast instead of drifting.
-
-The API URL is centralized in `ui/src/lib/constants/api.ts`. In the current template it is hard-coded to `https://api.elevasis.io`, so if the bootstrap is repointed to another API target, that file is the source of truth.
-
-## Route Structure
-
-Current top-level app sections:
-
-- `/` -- host-local dashboard entrypoint with quick links derived from `organizationModel.navigation.quickAccessSurfaceIds`
-- `/lead-gen/*` -- lead generation pages (`lists`, `companies`, `contacts`)
-- `/crm/*` -- CRM overview, pipeline, and deals
-- `/projects/*` -- delivery feature pages (projects, milestones, tasks, notes)
-- `/operations/*` -- operations overview, resources, command queue, command view, sessions, task scheduler
-- `/monitoring/*` -- execution logs, execution health, activity log, cost analytics, notifications
-- `/settings/*` -- account, organization, credentials, API keys, deployments, webhooks, and appearance
-- `/login` and `/auth-redirect` -- auth entry/callback routes
-
-Section guards currently follow this pattern:
-
-- `ProtectedRoute` for all authenticated sections
-- `SystemGuard` on sections that should hard-stop when a System is disabled: `crm`, `lead-gen`, `projects`, `operations`, and `monitoring`
-- provider-level shell gating for shared System nav and sub-shell behavior
-
-The app shell in `__root.tsx` derives visible nav from `shellModel.systems` and `getSidebarLinks()`, filters admin-only entries locally using the signed-in profile, and passes `canonicalOrganizationModel` into `ElevasisSystemsProvider` so shared nav labels, paths, and graph runtime behavior resolve from the same foundations-backed semantic model.
-
-## Dashboard and Feature Areas
-
-**Dashboard**
-
-`ui/src/features/dashboard/components/Dashboard.tsx` is intentionally lightweight. It acts as the host-owned landing page and renders quick access cards for the most important organization surfaces instead of duplicating the shared operations overview.
-
-**Operations**
-
-The operations area is the richest shared shell in the template. It includes:
-
-- resource inventory and detail pages
-- command queue and command view
-- sessions screens
-- the shared operations overview at `/operations/`
-
-**Monitoring**
-
-Monitoring is scaffolded as a shared feature area with route files for:
-
-- activity log
-- cost analytics
-- execution health
-- execution logs
-- notifications
-
-## Customization Points
-
-The main template-owned customization surfaces are:
-
-- `ui/src/config/app-config.ts` -- brand name, logos, and app version
-- `ui/src/config/theme.ts` -- theme presets and defaults
-- `ui/src/config/background.tsx` -- shared background treatment
-- `ui/src/config/loader.tsx` -- global loader element
-- `ui/src/config/nav-items.ts` -- app-local nav entries, including the preserved dashboard/home entry
-- `core/config/organization-model.ts` -- product labels, System availability, resource descriptors, semantic surfaces, canonical-to-legacy surface aliases, and quick-access behavior
-- `ui/src/config/README.md` -- the deeper guide for those config files
-
-## Customizing System Sidebars
-
-The template demonstrates one override pattern in `ui/src/routes/__root.tsx`: it extends `CRM_ITEMS` with a template-owned Reports link and replaces `crmManifest` with `customCrmManifest` in the System module array. The backing route lives at `ui/src/routes/crm/reports.tsx` -- delete both the nav item and the route if you don't need them.
-
-Two customization layers are available for every shared System sidebar:
-
-1. **Nav-item shortcut (`items` prop)** -- when you just need to swap or extend the nav array, spread the published items constant and pass the result to `*SidebarMiddle`. The template's CRM customization uses this path.
-
-   ```tsx
-   import { crmManifest, CrmSidebar, CrmSidebarMiddle, CRM_ITEMS } from '@elevasis/ui/features/crm'
-   import type { NavItem } from '@elevasis/ui/layout'
-
-   const customItems: NavItem[] = [...CRM_ITEMS, { label: 'Reports', to: '/crm/reports', icon: IconFileText, exact: false }]
-   const CustomCrmSidebar = () => <CrmSidebar><CrmSidebarMiddle items={customItems} /></CrmSidebar>
-   const customCrmManifest = { ...crmManifest, sidebar: CustomCrmSidebar }
-   ```
-
-2. **Compose-primitives (structural changes)** -- when you need to inject panels, reorder sections, or add a new section, drop down to `CrmSidebarTop` + `SubshellNavList` + `SubshellSidebarSection` + published panels (`MyTasksPanel`, `QuickCreateActions`) and compose your own Middle.
-
-`manifest.sidebar` accepts any component, so arbitrary customization is always available. The `items` prop is an abstraction barrier for the common case, not a limit.
-
-See `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` for the decision tree, page-wrapping pattern, and delivery's three-section variant. 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`. See `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for `NavItem`, `SystemModule`, CRM platform primitives, Lead Gen platform primitives, and related TypeScript shapes.
-
-For CRM deal action buttons, read `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` before changing `crmActions`, `DealDetailPage`, `DealDrawer`, or custom workflow buttons. Start with the shared `crmActions` provider path for action visibility, labels, ordering, and render-time configuration. In v1, platform-known/default action endpoint behavior is server-constrained; use project-owned UI that calls the workflow directly when a custom key sits outside that server-dispatched set.
-
-## Notes
-
-- `ui/src/routeTree.gen.ts` is generated by TanStack Router tooling. Do not hand-edit it.
-- The template ships a broad route surface so downstream projects can trim or reshape features without having to re-derive the shared shell contract from scratch.
-- For package-export discovery, glob `node_modules/@elevasis/sdk/reference/` or `node_modules/@repo/ui/dist/` for the current SDK/UI package surface.
+---
+description: UI shell, route structure, auth flow, API access, and template customization points for the ui/ surface
+paths:
+  - ui/**
+---
+
+# UI Features
+
+**Status:** Stable
+
+## App Shell Overview
+
+The template frontend is a React 19 + TanStack Router app that composes a local dashboard shell with published System modules from `@elevasis/ui`.
+
+The main join points are:
+
+- `ui/src/main.tsx` -- boots the app with `ElevasisUIProvider`, query client, theme config, WorkOS AuthKit, notifications, and the generated route tree
+- `ui/src/routes/__root.tsx` -- composes the authenticated shell with `ElevasisSystemsProvider`, published System modules, app-local dashboard nav, shell runtime dependencies, and `SystemShell`
+- `ui/src/config/nav-items.ts` -- keeps the host-local dashboard entry separate from the published feature manifests
+- `core/config/organization-model.ts` -- is the template's semantic source of truth, adapting `@elevasis/core/organization-model` into the preserved branding, dashboard label, quick-access, System labels, resource descriptors, and shell helpers
+
+Published System modules mounted by the template shell:
+
+- `lead-gen`
+- `crm`
+- `delivery` at `/projects`
+- `operations`
+- `monitoring`
+- `settings`
+
+Important distinction:
+
+- shared modules gate on current org-model System keys such as `sales.lead-gen` and `projects`
+- template routes and local nav may still use legacy aliases such as `crm`, `lead-gen`, and `projects`
+- `core/config/organization-model.ts` and `ui/src/lib/hooks/useFeatureAccess.ts` are the bridge between those two vocabularies
+
+Dashboard remains a host-local route at `/`, not a shared feature manifest.
+
+This template should be treated as the downstream reference implementation for this composition:
+
+- `core/config/organization-model.ts` owns the organization/runtime semantics
+- `ui/src/config/nav-items.ts` preserves the host-local dashboard entry instead of pushing that concern into shared manifests
+- `ui/src/routes/__root.tsx` threads `canonicalOrganizationModel` from `@core/config/organization-model` into `ElevasisSystemsProvider` so the shared shell/runtime uses the same semantic source of truth as the local template helpers
+- host-local customizations still stay local: dashboard remains app-owned nav, branding stays in app config, and quick-access/dashboard UX stays in the template app
+
+## Auth and Initialization
+
+The app uses WorkOS AuthKit through `ElevasisUIProvider`. Authentication is enforced by the local `ProtectedRoute` wrapper in `ui/src/features/auth/ProtectedRoute.tsx`.
+
+**Sign-in flow:**
+
+1. Unauthenticated user hits a protected route -- `ProtectedRoute` redirects to `/login?returnTo=<path>`
+2. `/login` renders a sign-in card; user clicks Sign In, triggering `signIn({ returnTo })` from `useAuth()`
+3. User authenticates on the WorkOS-hosted sign-in page
+4. WorkOS redirects back to `/auth-redirect` -- `ui/src/routes/auth-redirect.tsx` waits for auth to complete, then navigates to the requested path or `/`
+5. User lands on the home page, fully authenticated
+
+**Route protection:**
+
+Wrap protected route components with the local `ProtectedRoute` from `@/features/auth`, which adds the full-screen loader and delegates to the shared guard from `@elevasis/ui/auth`:
+
+```tsx
+import { ProtectedRoute } from '@/features/auth'
+
+function HomePageGuarded() {
+  return (
+    <ProtectedRoute>
+      <HomePage />
+    </ProtectedRoute>
+  )
+}
+```
+
+**Initialization state:**
+
+Use `useInitialization()` from `@elevasis/ui/initialization` anywhere inside the app to read aggregated auth + org readiness:
+
+```ts
+const { allReady, userReady, isInitializing, error, retry, profile } = useInitialization()
+```
+
+**Organization context:**
+
+Use `useOrganization()` from `@elevasis/ui/organization` to access org-scoped IDs and memberships:
+
+```ts
+const { currentWorkOSOrganizationId, currentSupabaseOrganizationId, memberships, switchOrganization } = useOrganization()
+```
+
+## API and Streaming
+
+Use `useApiClient()` from `@/lib/hooks/useApiClient` in route components and feature hooks:
+
+```ts
+const { apiRequest, isOrganizationReady } = useApiClient()
+const data = await apiRequest('/executions', { method: 'GET' })
+```
+
+The template also re-exports `useApiClientContext()` and the shared API client types from `@/lib/hooks/useApiClient`.
+
+For real-time updates, feature surfaces use the local singleton wrapper:
+
+```ts
+import { sseConnectionManager } from '@/lib/sse/SSEConnectionManager'
+```
+
+**WorkOS config:**
+
+WorkOS `clientId`, `redirectUri`, and `signoutUri` are hardcoded in `ui/src/config/workos.ts` -- no UI env vars are required to run the template. Edit that file if a fork needs a different WorkOS client. The dev server runs on port `4300` with Vite `strictPort: true`, so a second `pnpm -C ui dev` on the same machine fails fast instead of drifting.
+
+The API URL is centralized in `ui/src/lib/constants/api.ts`. In the current template it is hard-coded to `https://api.elevasis.io`, so if the bootstrap is repointed to another API target, that file is the source of truth.
+
+## Route Structure
+
+Current top-level app sections:
+
+- `/` -- host-local dashboard entrypoint with quick links derived from `organizationModel.navigation.quickAccessSurfaceIds`
+- `/lead-gen/*` -- lead generation pages (`lists`, `companies`, `contacts`)
+- `/crm/*` -- CRM overview, pipeline, and deals
+- `/projects/*` -- delivery feature pages (projects, milestones, tasks, notes)
+- `/operations/*` -- operations overview, resources, command queue, command view, sessions, task scheduler
+- `/monitoring/*` -- execution logs, execution health, activity log, cost analytics, notifications
+- `/settings/*` -- account, organization, credentials, API keys, deployments, webhooks, and appearance
+- `/login` and `/auth-redirect` -- auth entry/callback routes
+
+Section guards currently follow this pattern:
+
+- `ProtectedRoute` for all authenticated sections
+- `SystemGuard` on sections that should hard-stop when a System is disabled: `crm`, `lead-gen`, `projects`, `operations`, and `monitoring`
+- provider-level shell gating for shared System nav and sub-shell behavior
+
+The app shell in `__root.tsx` derives visible nav from `shellModel.systems` and `getSidebarLinks()`, filters admin-only entries locally using the signed-in profile, and passes `canonicalOrganizationModel` into `ElevasisSystemsProvider` so shared nav labels, paths, and graph runtime behavior resolve from the same organization-model semantic source.
+
+## Dashboard and Feature Areas
+
+**Dashboard**
+
+`ui/src/features/dashboard/components/Dashboard.tsx` is intentionally lightweight. It acts as the host-owned landing page and renders quick access cards for the most important organization surfaces instead of duplicating the shared operations overview.
+
+**Operations**
+
+The operations area is the richest shared shell in the template. It includes:
+
+- resource inventory and detail pages
+- command queue and command view
+- sessions screens
+- the shared operations overview at `/operations/`
+
+**Monitoring**
+
+Monitoring is scaffolded as a shared feature area with route files for:
+
+- activity log
+- cost analytics
+- execution health
+- execution logs
+- notifications
+
+## Customization Points
+
+The main template-owned customization surfaces are:
+
+- `ui/src/config/app-config.ts` -- brand name, logos, and app version
+- `ui/src/config/theme.ts` -- theme presets and defaults
+- `ui/src/config/background.tsx` -- shared background treatment
+- `ui/src/config/loader.tsx` -- global loader element
+- `ui/src/config/nav-items.ts` -- app-local nav entries, including the preserved dashboard/home entry
+- `core/config/organization-model.ts` -- product labels, System availability, resource descriptors, semantic surfaces, canonical-to-legacy surface aliases, and quick-access behavior
+- `ui/src/config/README.md` -- the deeper guide for those config files
+
+## Customizing System Sidebars
+
+The template demonstrates one override pattern in `ui/src/routes/__root.tsx`: it extends `CRM_ITEMS` with a template-owned Reports link and replaces `crmManifest` with `customCrmManifest` in the System module array. The backing route lives at `ui/src/routes/crm/reports.tsx` -- delete both the nav item and the route if you don't need them.
+
+Two customization layers are available for every shared System sidebar:
+
+1. **Nav-item shortcut (`items` prop)** -- when you just need to swap or extend the nav array, spread the published items constant and pass the result to `*SidebarMiddle`. The template's CRM customization uses this path.
+
+   ```tsx
+   import { crmManifest, CrmSidebar, CrmSidebarMiddle, CRM_ITEMS } from '@elevasis/ui/features/crm'
+   import type { NavItem } from '@elevasis/ui/layout'
+
+   const customItems: NavItem[] = [...CRM_ITEMS, { label: 'Reports', to: '/crm/reports', icon: IconFileText, exact: false }]
+   const CustomCrmSidebar = () => <CrmSidebar><CrmSidebarMiddle items={customItems} /></CrmSidebar>
+   const customCrmManifest = { ...crmManifest, sidebar: CustomCrmSidebar }
+   ```
+
+2. **Compose-primitives (structural changes)** -- when you need to inject panels, reorder sections, or add a new section, drop down to `CrmSidebarTop` + `SubshellNavList` + `SubshellSidebarSection` + published panels (`MyTasksPanel`, `QuickCreateActions`) and compose your own Middle.
+
+`manifest.sidebar` accepts any component, so arbitrary customization is always available. The `items` prop is an abstraction barrier for the common case, not a limit.
+
+See `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` for the decision tree, page-wrapping pattern, and delivery's three-section variant. 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`. See `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for `NavItem`, `SystemModule`, CRM platform primitives, Lead Gen platform primitives, and related TypeScript shapes.
+
+For CRM deal action buttons, read `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` before changing `crmActions`, `DealDetailPage`, `DealDrawer`, or custom workflow buttons. Start with the shared `crmActions` provider path for action visibility, labels, ordering, and render-time configuration. In v1, platform-known/default action endpoint behavior is server-constrained; use project-owned UI that calls the workflow directly when a custom key sits outside that server-dispatched set.
+
+## Notes
+
+- `ui/src/routeTree.gen.ts` is generated by TanStack Router tooling. Do not hand-edit it.
+- The template ships a broad route surface so downstream projects can trim or reshape features without having to re-derive the shared shell contract from scratch.
+- For package-export discovery, glob `node_modules/@elevasis/sdk/reference/` or `node_modules/@repo/ui/dist/` for the current SDK/UI package surface.