@elevasis/sdk 1.3.0 → 1.4.0

package/dist/cli.cjs

@@ -43917,7 +43917,7 @@ function wrapAction(commandName, fn) {
 // package.json
 var package_default = {
   name: "@elevasis/sdk",
-  version: "1.3.0",
+  version: "1.4.0",
   description: "SDK for building Elevasis organization resources",
   type: "module",
   bin: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -44,7 +44,7 @@
     "tsup": "^8.0.0",
     "typescript": "5.9.2",
     "zod": "^4.1.0",
-    "@repo/core": "0.0.0",
+    "@repo/core": "0.1.0",
     "@repo/typescript-config": "0.0.0"
   },
   "scripts": {

package/reference/_navigation.md

@@ -2,16 +2,90 @@
 
 Auto-generated from the package reference manifests.
 
-Package entries indexed: 2.
+Package entries indexed: 36.
 
-## Getting Started
+## @elevasis/core / Core
 
 | Resource | Location | Description | When to Load |
 | --- | --- | --- | --- |
-| SDK | `../src/index.ts` | Root SDK types, config, runtime errors, and registry surface. | (not specified) |
+| Core | `packages/core/src/README.md` | Published core wrapper for the curated contract surface. | (not specified) |
 
-## Runtime
+## @elevasis/core / Organization Model
 
 | Resource | Location | Description | When to Load |
 | --- | --- | --- | --- |
-| Worker Runtime | `../src/worker/index.ts` | Worker runtime entrypoint, adapters, and platform execution surface. | (not specified) |
+| Organization Model | `packages/core/src/organization-model/README.md` | Published organization-model schema, defaults, resolver, and types. | (not specified) |
+
+## @elevasis/sdk / Getting Started
+
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| SDK | `index.mdx` | Root SDK types, config, runtime errors, and registry surface. | (not specified) |
+
+## @elevasis/sdk / Runtime
+
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Worker Runtime | `runtime.mdx` | Worker runtime entrypoint, adapters, and platform execution surface. | (not specified) |
+
+## @elevasis/ui / Components
+
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Components | `packages/ui/src/components/README.md` | Published UI component barrel for downstream applications. | (not specified) |
+| Navigation Components | `packages/ui/src/components/README.md` | Published navigation component entry for downstream applications. | (not specified) |
+| Chat Components | `packages/ui/src/components/README.md` | Published chat component entry for downstream applications. | (not specified) |
+| Layout | `packages/ui/src/components/README.md` | Published layout component entry for downstream applications. | (not specified) |
+| Charts | `packages/ui/src/components/README.md` | Published chart component entry for downstream applications. | (not specified) |
+
+## @elevasis/ui / Features
+
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Features Auth | `packages/ui/src/features/README.md` | Published auth feature surface for downstream shells. | (not specified) |
+| Features CRM | `packages/ui/src/features/README.md` | Published CRM feature surface for downstream shells. | (not specified) |
+| Features Dashboard | `packages/ui/src/features/README.md` | Published dashboard feature surface for downstream shells. | (not specified) |
+| Features Delivery | `packages/ui/src/features/README.md` | Published delivery feature surface for downstream shells. | (not specified) |
+| Features Lead Gen | `packages/ui/src/features/README.md` | Published lead generation feature surface for downstream shells. | (not specified) |
+| Features Operations | `packages/ui/src/features/README.md` | Published operations feature surface for downstream shells. | (not specified) |
+| Features Monitoring | `packages/ui/src/features/README.md` | Published monitoring feature surface for downstream shells. | (not specified) |
+| Features SEO | `packages/ui/src/features/README.md` | Published SEO feature surface for downstream shells. | (not specified) |
+| Features Settings | `packages/ui/src/features/README.md` | Published settings feature surface for downstream shells. | (not specified) |
+
+## @elevasis/ui / Foundation
+
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Auth | `packages/ui/src/auth/README.md` | Published authentication surface for UI integrations. | (not specified) |
+| Auth Context | `packages/ui/src/auth/README.md` | Published auth context entry for UI integrations. | (not specified) |
+| SSE | `packages/ui/src/sse/README.md` | Published server-sent events helpers and connection utilities. | (not specified) |
+| Initialization | `packages/ui/src/initialization/README.md` | Published app initialization provider and bootstrap helpers. | (not specified) |
+| Profile | `packages/ui/src/profile/README.md` | Published user profile surface for UI applications. | (not specified) |
+| Organization | `packages/ui/src/organization/README.md` | Published organization shell, store, and helper surface. | (not specified) |
+| Types | `packages/ui/src/types/README.md` | Published UI types entry for downstream applications. | (not specified) |
+| API | `packages/ui/src/api/README.md` | Published API client entry for downstream applications. | (not specified) |
+| Utils | `packages/ui/src/utils/README.md` | Published utility entry for downstream applications. | (not specified) |
+| Execution | `packages/ui/src/execution/README.md` | Published execution visualization and helper entry. | (not specified) |
+| Router | `packages/ui/src/router/README.md` | Published router entry for downstream applications. | (not specified) |
+| Router Context | `packages/ui/src/router/README.md` | Published router context entry for downstream applications. | (not specified) |
+| Zustand | `packages/ui/src/zustand/README.md` | Published Zustand slice entry for downstream applications. | (not specified) |
+
+## @elevasis/ui / Hooks
+
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Hooks | `packages/ui/src/hooks/README.md` | Headless hooks surface for executions, sessions, observability, and operations. | (not specified) |
+
+## @elevasis/ui / Provider
+
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Provider | `packages/ui/src/provider/README.md` | Published provider and feature-shell contract for downstream apps. | (not specified) |
+| Provider UI | `packages/ui/src/provider/README.md` | Published provider UI entry for downstream applications. | (not specified) |
+
+## @elevasis/ui / Visual
+
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Theme | `packages/ui/src/theme/README.md` | Published theme entry for downstream applications. | (not specified) |
+| Graph | `packages/ui/src/graph/README.md` | Published graph helper and visualization entry. | (not specified) |

package/reference/_reference-manifest.json

@@ -11,6 +11,8 @@
       "group": "Core",
       "order": 1,
       "sourcePath": "packages/core/src/published.ts",
+      "docPath": "packages/core/src/README.md",
+      "referencePath": "packages/core/src/README.md",
       "publishedExportPath": "./dist/index.js"
     },
     {
@@ -23,6 +25,8 @@
       "group": "Organization Model",
       "order": 1,
       "sourcePath": "packages/core/src/organization-model/published.ts",
+      "docPath": "packages/core/src/organization-model/README.md",
+      "referencePath": "packages/core/src/organization-model/README.md",
       "publishedExportPath": "./dist/organization-model/index.js"
     },
     {
@@ -35,6 +39,8 @@
       "group": "Getting Started",
       "order": 1,
       "sourcePath": "packages/sdk/src/index.ts",
+      "docPath": "apps/docs/content/docs/sdk/index.mdx",
+      "referencePath": "index.mdx",
       "publishedExportPath": "./dist/index.js"
     },
     {
@@ -47,6 +53,8 @@
       "group": "Runtime",
       "order": 1,
       "sourcePath": "packages/sdk/src/worker/index.ts",
+      "docPath": "apps/docs/content/docs/sdk/runtime.mdx",
+      "referencePath": "runtime.mdx",
       "publishedExportPath": "./dist/worker/index.js"
     },
     {
@@ -59,6 +67,8 @@
       "group": "Components",
       "order": 1,
       "sourcePath": "packages/ui/src/components/index.ts",
+      "docPath": "packages/ui/src/components/README.md",
+      "referencePath": "packages/ui/src/components/README.md",
       "publishedExportPath": "./dist/components/index.js"
     },
     {
@@ -71,6 +81,8 @@
       "group": "Components",
       "order": 2,
       "sourcePath": "packages/ui/src/components/navigation/index.ts",
+      "docPath": "packages/ui/src/components/README.md",
+      "referencePath": "packages/ui/src/components/README.md",
       "publishedExportPath": "./dist/components/navigation/index.js"
     },
     {
@@ -83,6 +95,8 @@
       "group": "Components",
       "order": 3,
       "sourcePath": "packages/ui/src/components/chat/index.ts",
+      "docPath": "packages/ui/src/components/README.md",
+      "referencePath": "packages/ui/src/components/README.md",
       "publishedExportPath": "./dist/components/chat/index.js"
     },
     {
@@ -95,6 +109,8 @@
       "group": "Components",
       "order": 4,
       "sourcePath": "packages/ui/src/components/layout/index.ts",
+      "docPath": "packages/ui/src/components/README.md",
+      "referencePath": "packages/ui/src/components/README.md",
       "publishedExportPath": "./dist/layout/index.js"
     },
     {
@@ -107,6 +123,8 @@
       "group": "Components",
       "order": 5,
       "sourcePath": "packages/ui/src/components/charts/index.ts",
+      "docPath": "packages/ui/src/components/README.md",
+      "referencePath": "packages/ui/src/components/README.md",
       "publishedExportPath": "./dist/charts/index.js"
     },
     {
@@ -119,6 +137,8 @@
       "group": "Features",
       "order": 1,
       "sourcePath": "packages/ui/src/features/auth/index.ts",
+      "docPath": "packages/ui/src/features/README.md",
+      "referencePath": "packages/ui/src/features/README.md",
       "publishedExportPath": "./dist/features/auth/index.js"
     },
     {
@@ -131,6 +151,8 @@
       "group": "Features",
       "order": 2,
       "sourcePath": "packages/ui/src/features/crm/index.ts",
+      "docPath": "packages/ui/src/features/README.md",
+      "referencePath": "packages/ui/src/features/README.md",
       "publishedExportPath": "./dist/features/crm/index.js"
     },
     {
@@ -143,6 +165,8 @@
       "group": "Features",
       "order": 3,
       "sourcePath": "packages/ui/src/features/dashboard/index.ts",
+      "docPath": "packages/ui/src/features/README.md",
+      "referencePath": "packages/ui/src/features/README.md",
       "publishedExportPath": "./dist/features/dashboard/index.js"
     },
     {
@@ -155,6 +179,8 @@
       "group": "Features",
       "order": 4,
       "sourcePath": "packages/ui/src/features/delivery/index.ts",
+      "docPath": "packages/ui/src/features/README.md",
+      "referencePath": "packages/ui/src/features/README.md",
       "publishedExportPath": "./dist/features/delivery/index.js"
     },
     {
@@ -167,6 +193,8 @@
       "group": "Features",
       "order": 5,
       "sourcePath": "packages/ui/src/features/lead-gen/index.ts",
+      "docPath": "packages/ui/src/features/README.md",
+      "referencePath": "packages/ui/src/features/README.md",
       "publishedExportPath": "./dist/features/lead-gen/index.js"
     },
     {
@@ -179,6 +207,8 @@
       "group": "Features",
       "order": 6,
       "sourcePath": "packages/ui/src/features/operations/index.ts",
+      "docPath": "packages/ui/src/features/README.md",
+      "referencePath": "packages/ui/src/features/README.md",
       "publishedExportPath": "./dist/features/operations/index.js"
     },
     {
@@ -191,6 +221,8 @@
       "group": "Features",
       "order": 7,
       "sourcePath": "packages/ui/src/features/monitoring/index.ts",
+      "docPath": "packages/ui/src/features/README.md",
+      "referencePath": "packages/ui/src/features/README.md",
       "publishedExportPath": "./dist/features/monitoring/index.js"
     },
     {
@@ -203,6 +235,8 @@
       "group": "Features",
       "order": 8,
       "sourcePath": "packages/ui/src/features/seo/index.ts",
+      "docPath": "packages/ui/src/features/README.md",
+      "referencePath": "packages/ui/src/features/README.md",
       "publishedExportPath": "./dist/features/seo/index.js"
     },
     {
@@ -215,6 +249,8 @@
       "group": "Features",
       "order": 9,
       "sourcePath": "packages/ui/src/features/settings/index.ts",
+      "docPath": "packages/ui/src/features/README.md",
+      "referencePath": "packages/ui/src/features/README.md",
       "publishedExportPath": "./dist/features/settings/index.js"
     },
     {
@@ -227,6 +263,8 @@
       "group": "Foundation",
       "order": 1,
       "sourcePath": "packages/ui/src/auth/index.ts",
+      "docPath": "packages/ui/src/auth/README.md",
+      "referencePath": "packages/ui/src/auth/README.md",
       "publishedExportPath": "./dist/auth/index.js"
     },
     {
@@ -239,6 +277,8 @@
       "group": "Foundation",
       "order": 2,
       "sourcePath": "packages/ui/src/auth/context.ts",
+      "docPath": "packages/ui/src/auth/README.md",
+      "referencePath": "packages/ui/src/auth/README.md",
       "publishedExportPath": "./dist/auth/context.js"
     },
     {
@@ -251,6 +291,8 @@
       "group": "Foundation",
       "order": 3,
       "sourcePath": "packages/ui/src/sse/index.ts",
+      "docPath": "packages/ui/src/sse/README.md",
+      "referencePath": "packages/ui/src/sse/README.md",
       "publishedExportPath": "./dist/sse/index.js"
     },
     {
@@ -263,6 +305,8 @@
       "group": "Foundation",
       "order": 4,
       "sourcePath": "packages/ui/src/initialization/index.ts",
+      "docPath": "packages/ui/src/initialization/README.md",
+      "referencePath": "packages/ui/src/initialization/README.md",
       "publishedExportPath": "./dist/initialization/index.js"
     },
     {
@@ -275,6 +319,8 @@
       "group": "Foundation",
       "order": 5,
       "sourcePath": "packages/ui/src/profile/index.ts",
+      "docPath": "packages/ui/src/profile/README.md",
+      "referencePath": "packages/ui/src/profile/README.md",
       "publishedExportPath": "./dist/profile/index.js"
     },
     {
@@ -287,6 +333,8 @@
       "group": "Foundation",
       "order": 6,
       "sourcePath": "packages/ui/src/organization/index.ts",
+      "docPath": "packages/ui/src/organization/README.md",
+      "referencePath": "packages/ui/src/organization/README.md",
       "publishedExportPath": "./dist/organization/index.js"
     },
     {
@@ -299,6 +347,8 @@
       "group": "Foundation",
       "order": 7,
       "sourcePath": "packages/ui/src/types/index.ts",
+      "docPath": "packages/ui/src/types/README.md",
+      "referencePath": "packages/ui/src/types/README.md",
       "publishedExportPath": "./dist/types/index.js"
     },
     {
@@ -311,6 +361,8 @@
       "group": "Foundation",
       "order": 8,
       "sourcePath": "packages/ui/src/api/index.ts",
+      "docPath": "packages/ui/src/api/README.md",
+      "referencePath": "packages/ui/src/api/README.md",
       "publishedExportPath": "./dist/api/index.js"
     },
     {
@@ -323,6 +375,8 @@
       "group": "Foundation",
       "order": 9,
       "sourcePath": "packages/ui/src/utils/index.ts",
+      "docPath": "packages/ui/src/utils/README.md",
+      "referencePath": "packages/ui/src/utils/README.md",
       "publishedExportPath": "./dist/utils/index.js"
     },
     {
@@ -335,6 +389,8 @@
       "group": "Foundation",
       "order": 10,
       "sourcePath": "packages/ui/src/execution/index.ts",
+      "docPath": "packages/ui/src/execution/README.md",
+      "referencePath": "packages/ui/src/execution/README.md",
       "publishedExportPath": "./dist/execution/index.js"
     },
     {
@@ -347,6 +403,8 @@
       "group": "Foundation",
       "order": 11,
       "sourcePath": "packages/ui/src/router/index.ts",
+      "docPath": "packages/ui/src/router/README.md",
+      "referencePath": "packages/ui/src/router/README.md",
       "publishedExportPath": "./dist/router/index.js"
     },
     {
@@ -359,6 +417,8 @@
       "group": "Foundation",
       "order": 12,
       "sourcePath": "packages/ui/src/router/context.ts",
+      "docPath": "packages/ui/src/router/README.md",
+      "referencePath": "packages/ui/src/router/README.md",
       "publishedExportPath": "./dist/router/context.js"
     },
     {
@@ -371,6 +431,8 @@
       "group": "Foundation",
       "order": 13,
       "sourcePath": "packages/ui/src/zustand/index.ts",
+      "docPath": "packages/ui/src/zustand/README.md",
+      "referencePath": "packages/ui/src/zustand/README.md",
       "publishedExportPath": "./dist/zustand/index.js"
     },
     {
@@ -383,6 +445,8 @@
       "group": "Hooks",
       "order": 1,
       "sourcePath": "packages/ui/src/hooks/published.ts",
+      "docPath": "packages/ui/src/hooks/README.md",
+      "referencePath": "packages/ui/src/hooks/README.md",
       "publishedExportPath": "./dist/hooks/published.js"
     },
     {
@@ -395,6 +459,8 @@
       "group": "Provider",
       "order": 1,
       "sourcePath": "packages/ui/src/provider/published.ts",
+      "docPath": "packages/ui/src/provider/README.md",
+      "referencePath": "packages/ui/src/provider/README.md",
       "publishedExportPath": "./dist/provider/published.js"
     },
     {
@@ -407,6 +473,8 @@
       "group": "Provider",
       "order": 2,
       "sourcePath": "packages/ui/src/provider/index.ts",
+      "docPath": "packages/ui/src/provider/README.md",
+      "referencePath": "packages/ui/src/provider/README.md",
       "publishedExportPath": "./dist/provider/index.js"
     },
     {
@@ -419,6 +487,8 @@
       "group": "Visual",
       "order": 1,
       "sourcePath": "packages/ui/src/theme/index.ts",
+      "docPath": "packages/ui/src/theme/README.md",
+      "referencePath": "packages/ui/src/theme/README.md",
       "publishedExportPath": "./dist/theme/index.js"
     },
     {
@@ -431,6 +501,8 @@
       "group": "Visual",
       "order": 2,
       "sourcePath": "packages/ui/src/graph/index.ts",
+      "docPath": "packages/ui/src/graph/README.md",
+      "referencePath": "packages/ui/src/graph/README.md",
       "publishedExportPath": "./dist/graph/index.js"
     }
   ]

package/reference/packages/core/src/README.md

@@ -0,0 +1,34 @@
+# @elevasis/core
+
+Published browser-safe shared contracts for the Elevasis platform.
+
+This package is the source of truth for shared types, schemas, and contract helpers that are safe to consume from apps and other packages. In this repo the source package is named `@repo/core`, but these docs describe the published `@elevasis/core` surface.
+
+## Import Rules
+
+- Use `@elevasis/core` for browser-safe shared types and schemas.
+- Use `@elevasis/core/server` only for Node.js-only helpers and services.
+- Use `@elevasis/core/test-utils` for test fixtures and mocks.
+- Prefer the narrowest published subpath that matches the work you are doing.
+
+## Published Surface Groups
+
+- `platform` - shared constants, utilities, registry, SSE, and API types.
+- `auth` - multi-tenancy types for organizations, users, memberships, invitations, and credentials.
+- `execution` - workflow, agent, scheduler, calibration, and execution-interface contracts.
+- `commands` - command queue types and schemas.
+- `deployments` - deployment response types.
+- `operations` - sessions, notifications, observability, activities, triggers, and debug logs.
+- `business` - acquisition and SEO contracts, plus the PDF surface under its own subpaths.
+- `organization-model` - the semantic contract layer for CRM, lead gen, delivery, features, branding, and navigation.
+- `supabase` - generated database types and helpers.
+- `forms` - shared form schemas and form-facing types.
+- `integrations` - OAuth and credential contracts.
+- `projects` - project management request and response schemas.
+- `content` - published content metadata types.
+
+## When To Read Deeper
+
+- For the organization model contract, start with [organization-model/README.md](./organization-model/README.md).
+- For test utilities, read [test-utils/README.md](./test-utils/README.md).
+- For credentials, read [auth/multi-tenancy/credentials/README.md](./auth/multi-tenancy/credentials/README.md) if you are working in source. The runtime helpers are server-only.

package/reference/packages/core/src/organization-model/README.md

@@ -0,0 +1,79 @@
+# Organization Model
+
+The organization model is the published semantic contract that maps a tenant's product shape to domain surfaces, features, and navigation.
+
+Use this module when you need to resolve or validate an organization's contract before wiring UI shells, routing, or domain-specific capability checks.
+
+## Published Exports
+
+The public entry point exposes:
+
+- `OrganizationModelSchema`
+- `DEFAULT_ORGANIZATION_MODEL`
+- `defineOrganizationModel`
+- `resolveOrganizationModel`
+- `OrganizationModel` and the supporting domain types
+
+Import it from the published subpath:
+
+```ts
+import {
+  DEFAULT_ORGANIZATION_MODEL,
+  defineOrganizationModel,
+  resolveOrganizationModel,
+  type OrganizationModel
+} from '@elevasis/core/organization-model'
+```
+
+## Contract Shape
+
+The model is versioned and currently validates against `version: 1`.
+
+Top-level fields:
+
+- `domains` - semantic domain entries that bind entity IDs, surface IDs, resource IDs, and capability IDs.
+- `branding` - organization branding defaults and overrides.
+- `features` - feature flags and labels for the shell.
+- `navigation` - navigation model for the product shell.
+- `crm` - CRM-specific contract data.
+- `leadGen` - lead generation contract data.
+- `delivery` - delivery and project contract data.
+- `resourceMappings` - cross-surface resource mappings.
+
+## Default Domain Set
+
+The default model includes four semantic domains:
+
+- `crm` - deal pipeline and relationship management.
+- `lead-gen` - lists, companies, and contacts.
+- `delivery` - projects, milestones, and tasks.
+- `operations` - organization graph and command-view surfaces.
+
+## Feature Keys
+
+The current feature keys are:
+
+- `acquisition`
+- `delivery`
+- `operations`
+- `monitoring`
+- `settings`
+- `seo`
+- `calibration`
+
+Each feature can carry an enabled flag and an optional label override.
+
+## Resolution Semantics
+
+- `defineOrganizationModel()` is a typed helper. It does not validate or merge anything by itself.
+- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates the result with `OrganizationModelSchema`.
+- Plain objects merge recursively.
+- Arrays replace the default value instead of merging element-by-element.
+- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
+
+## Practical Guidance
+
+- Use `resolveOrganizationModel()` when you need a runtime-safe model for rendering or policy checks.
+- Use `defineOrganizationModel()` when authoring a static partial model in source.
+- Keep domain IDs, surface IDs, and capability IDs stable because downstream UI and policy code depend on them.
+

package/reference/packages/ui/src/api/README.md

@@ -0,0 +1,18 @@
+# API
+
+The API surface provides the HTTP client provider, the context hook, and the API config types.
+
+## Exports
+
+- `ApiClientProvider`
+- `useApiClientContext`
+- `useApiClient`
+- `ApiClientContextValue`
+- `ApiClientProviderProps`
+- `ApiErrorDetails`
+
+## Use When
+
+- You need a shared API request client at the app root.
+- You want org-aware request access through `useApiClient`.
+

package/reference/packages/ui/src/auth/README.md

@@ -0,0 +1,18 @@
+# Auth
+
+The auth surface is the published authentication entry point for UI shells.
+
+## Exports
+
+- `AuthProvider`
+- `useAuthContext`
+- `useStableAccessToken`
+- `useSessionCheck`
+- `ProtectedRoute`
+- `AdminGuard`
+
+## Use When
+
+- You need auth state, access tokens, or session lifecycle checks.
+- You need route-level guards for protected or admin-only UI.
+

package/reference/packages/ui/src/components/README.md

@@ -0,0 +1,24 @@
+# Components
+
+This barrel groups the shared visual and domain UI surfaces that remain part of the published component layer.
+
+## What It Covers
+
+- Acquisition and CRM UI primitives
+- Navigation, breadcrumbs, tables, forms, modals, and display components
+- Charts, monitoring widgets, notifications, and error states
+- Layout shells, backgrounds, and sidebar primitives
+- Typeform, rich text, content, and resource-definition helpers
+- Operations UI surfaces that are still shared at the component layer
+
+## Related Subpaths
+
+- `./components/navigation`
+- `./components/chat`
+- `./layout`
+- `./charts`
+
+## Notes
+
+- The component layer is broad by design, but feature-oriented application shells should still prefer `./features/*` when a dedicated feature surface exists.
+

package/reference/packages/ui/src/execution/README.md

@@ -0,0 +1,16 @@
+# Execution
+
+The execution surface contains headless helpers for execution timelines, workflow layouts, and execution-specific data shaping.
+
+## Exports
+
+- Hooks under `./hooks`
+- Utilities under `./utils`
+- Execution types under `./types`
+- Shared execution constants
+
+## Use When
+
+- You need execution timeline or workflow graph helpers without pulling in visual shells.
+- You need shared execution math or formatting utilities.
+

package/reference/packages/ui/src/features/README.md

@@ -0,0 +1,28 @@
+# Features
+
+Feature subpaths package complete shell-level UI flows for downstream apps.
+
+## Published Feature Surfaces
+
+- `./features/auth`
+- `./features/crm`
+- `./features/dashboard`
+- `./features/delivery`
+- `./features/lead-gen`
+- `./features/operations`
+- `./features/monitoring`
+- `./features/seo`
+- `./features/settings`
+
+## What They Contain
+
+- Route shells and page-level components
+- Sidebars and feature-specific navigation
+- Feature manifests for registry consumers
+- Feature-specific hooks and shared constants
+
+## Notes
+
+- These surfaces are meant for app composition, not for low-level design-system primitives.
+- Some feature exports are also re-exported through `./components` for convenience in legacy or mixed consumers.
+

package/reference/packages/ui/src/graph/README.md

@@ -0,0 +1,16 @@
+# Graph
+
+The graph surface is headless. It provides hooks, types, constants, and utilities for ReactFlow-based graph behavior.
+
+## Exports
+
+- Graph constants
+- Graph types
+- Graph hooks
+- Graph utilities
+
+## Notes
+
+- Visual graph components moved out of this package surface.
+- Use this subpath when you need graph behavior without the visual shell.
+

package/reference/packages/ui/src/hooks/README.md

@@ -0,0 +1,24 @@
+# Hooks
+
+The hooks barrel is the published headless hook surface for the UI package.
+
+## Grouped Areas
+
+- Execution and workflow hooks
+- Scheduling hooks
+- Monitoring, observability, and notification hooks
+- Session and SSE hooks
+- Operations hooks, including command-view and knowledge-base helpers
+- Feature access, table state, and service helpers
+- Acquisition and delivery hooks
+
+## Published Subpaths
+
+- `./hooks`
+- `./hooks/delivery`
+- `./hooks/operations/command-view/utils/transformCommandViewData`
+
+## Notes
+
+- This barrel is intentionally headless. It should not pull in the visual component layer.
+

package/reference/packages/ui/src/initialization/README.md

@@ -0,0 +1,19 @@
+# Initialization
+
+The initialization surface coordinates org-aware app startup.
+
+## Exports
+
+- `InitializationProvider`
+- `useInitialization`
+- `InitializationContext`
+- `createUseAppInitialization`
+- `InitializationError`
+- `AppInitializationState`
+- `SupabaseUserProfile` type re-export
+
+## Use When
+
+- You need zero-config app bootstrap inside an organization-aware provider tree.
+- You still need the deprecated factory pattern for older consumers.
+

package/reference/packages/ui/src/organization/README.md

@@ -0,0 +1,18 @@
+# Organization
+
+The organization surface manages multi-tenancy state and the related UI controls.
+
+## Exports
+
+- `OrganizationProvider`
+- `OrganizationContext`
+- `useOrganization`
+- `OrganizationSwitcher`
+- Store types and the legacy slice creator
+- Deprecated hook factories for older consumers
+
+## Notes
+
+- Prefer the provider and context exports for new code.
+- Legacy Zustand-based helpers remain exported for migration compatibility.
+

package/reference/packages/ui/src/profile/README.md

@@ -0,0 +1,19 @@
+# Profile
+
+The profile surface manages the user profile context and profile-backed helpers.
+
+## Exports
+
+- `ProfileProvider`
+- `useProfile`
+- `ProfileContextValue`
+- `useUserProfile`
+- `UseUserProfileReturn`
+- `UserProfileService`
+- `SupabaseUserProfile` type re-export
+
+## Use When
+
+- You need a shared user profile context.
+- You need a standalone profile service or hook for sync and access.
+

package/reference/packages/ui/src/provider/README.md

@@ -0,0 +1,31 @@
+# Provider
+
+The provider surface composes the shared Elevasis service, feature, appearance, notification, and UI providers.
+
+## Exports
+
+- `ElevasisCoreProvider`
+- `ElevasisFeaturesProvider`
+- `useElevasisFeatures`
+- `useOptionalElevasisFeatures`
+- `FeatureShell`
+- `AppearanceProvider`
+- `useAppearance`
+- `ElevasisServiceProvider`
+- `useElevasisServices`
+- `NotificationProvider`
+- `useNotificationAdapter`
+- `ElevasisUIProvider`
+- Related provider and service types
+
+## Related Published Subpaths
+
+- `./provider`
+- `./provider/ui`
+- `./provider/ElevasisServiceContext`
+
+## Notes
+
+- `published.ts` is the external consumer surface.
+- `ElevasisUIProvider` is the Mantine-facing visual layer; `ElevasisCoreProvider` and `ElevasisFeaturesProvider` handle the platform shell.
+

package/reference/packages/ui/src/router/README.md

@@ -0,0 +1,18 @@
+# Router
+
+The router surface provides the shared TanStack Router bridge and router context helpers.
+
+## Exports
+
+- `RouterProvider`
+- `useRouterContext`
+- `RouterAdapter`
+- `LinkProps`
+- `TanStackRouterBridge`
+- `ScrollToTop`
+
+## Use When
+
+- You need the shared routing abstraction for Elevasis apps.
+- You need a small adapter layer around TanStack Router in a consuming app.
+

package/reference/packages/ui/src/sse/README.md

@@ -0,0 +1,13 @@
+# SSE
+
+The SSE surface provides connection management and token-refresh helpers for server-sent events.
+
+## Exports
+
+- `SSEConnectionManager`
+- `fetchEventSourceWithTokenRefresh`
+
+## Use When
+
+- You need a shared SSE client with auth-aware reconnect behavior.
+

package/reference/packages/ui/src/theme/README.md

@@ -0,0 +1,23 @@
+# Theme
+
+The theme surface provides the preset system, CSS variable bridge, and Mantine theme integration.
+
+## Exports
+
+- `getPreset`
+- `generateShades`
+- `presets`
+- Theme preset types
+- `createCssVariablesResolver`
+- `TOKEN_VAR_MAP`
+- `mantineThemeOverride`
+- `componentThemes`
+- `PresetsProvider`
+- `usePresetsContext`
+- `useAvailablePresets`
+
+## Use When
+
+- You need to build or customize the Elevasis visual theme.
+- You need access to the shared preset registry or CSS variable mapping.
+

package/reference/packages/ui/src/types/README.md

@@ -0,0 +1,16 @@
+# Types
+
+The types surface re-exports the shared platform types that UI consumers need without a direct `@repo/core` dependency.
+
+## Exports
+
+- Execution and resource types
+- Command queue and scheduling types
+- Monitoring, observability, and notification types
+- Session, feature-access, and webhook types
+- Multi-tenancy, deployment, and CRM acquisition types
+
+## Notes
+
+- This is a type-only bridge. It should stay aligned with the current platform contracts.
+

package/reference/packages/ui/src/utils/README.md

@@ -0,0 +1,18 @@
+# Utils
+
+The utils surface groups shared date, formatting, validation, error, and resource helper functions.
+
+## Exports
+
+- Date formatting helpers
+- Relative time helpers
+- Email validation
+- Error helpers
+- Resource icon helpers
+- Shared constants
+- Warning suppression helpers
+
+## Use When
+
+- You need lightweight shared helpers that do not belong in a feature barrel.
+

package/reference/packages/ui/src/zustand/README.md

@@ -0,0 +1,18 @@
+# Zustand
+
+The Zustand surface exposes the shared slice creators used by the UI package.
+
+## Exports
+
+- `createSSESlice`
+- `resetSSEState`
+- `createThemeSlice`
+- `resetThemeState`
+- `createTimeRangeSlice`
+- `resetTimeRangeState`
+- Slice state and configuration types
+
+## Use When
+
+- You need the shared state slices used by the UI package internals or a compatible consumer.
+