@elevasis/sdk 1.9.0 → 1.11.0

package/reference/deployment/provided-features.mdx

@@ -1,64 +1,36 @@
 ---
 title: Provided Features
-description: Shared UI and API surfaces for packaged business systems like Lead Gen, CRM, and Projects via @elevasis/ui/features/* and the SDK CLI
+description: Shared UI and API surfaces for packaged business systems like Lead Gen, CRM, Projects, Operations, Monitoring, and Settings via @elevasis/ui/features/*.
 loadWhen: "Building against packaged app features, list-oriented lead gen, CRM, or project-management surfaces"
 ---
 
-The SDK now covers more than raw workflow execution. The published `@elevasis/ui@2.9.0` package includes:
-
-- manifest-backed shared features under `@elevasis/ui/features/<name>`
-- headless shell/provider exports under `@elevasis/ui/provider`
-- compatibility re-exports from `@elevasis/ui/components` for existing consumers
-
-Use this page to understand what the shared shell actually owns, which surfaces are still host-owned, and which API or CLI surface to reach for.
-
----
+The SDK includes more than workflow execution. The published `@elevasis/ui` package provides feature manifests, pages, hooks, and headless provider exports for building shell-aware applications.
 
 ## Shared Shell Contract
 
-`ElevasisFeaturesProvider` and `FeatureShell` give you a shared manifest-driven shell layer, not a full application shell. In `2.9.0` they handle:
-
-- feature registration
-- feature-gated nav contribution
-- route-to-sidebar subshell dispatch when a manifest includes a shared sidebar
-- shared provider context such as `timeRange` and operations runtime inputs
-
-Your host app still owns:
-
-- TanStack route registration
-- top-level app nav, topbar, branding, and auth wiring
-- app-specific assistant/admin behavior
-- any dashboard or landing page experience that is not backed by a published manifest
+`ElevasisFeaturesProvider` reads a flat `OrganizationModel.features` list and exposes a shell model with feature-tree helpers. Feature manifests provide implementation hooks such as icons and sidebars; they do not own structural navigation.
 
 ```tsx
 import { Outlet } from '@tanstack/react-router'
-import { IconLayoutDashboard } from '@tabler/icons-react'
-import {
-  ElevasisFeaturesProvider,
-  FeatureShell,
-  type AppShellOverrides
-} from '@elevasis/ui/provider'
+import { ElevasisFeaturesProvider, FeatureShell } from '@elevasis/ui/provider'
 import { leadGenManifest } from '@elevasis/ui/features/lead-gen'
 import { crmManifest } from '@elevasis/ui/features/crm'
 import { deliveryManifest } from '@elevasis/ui/features/delivery'
 import { monitoringManifest } from '@elevasis/ui/features/monitoring'
 import { settingsManifest } from '@elevasis/ui/features/settings'
+import { canonicalOrganizationModel } from '@foundation/config/organization-model'
 
 const features = [
   leadGenManifest,
   crmManifest,
   deliveryManifest,
   monitoringManifest,
-  settingsManifest,
+  settingsManifest
 ]
 
-const appShellOverrides: AppShellOverrides = {
-  primaryNavItems: [{ label: 'Dashboard', icon: IconLayoutDashboard, link: '/' }],
-}
-
 export function AppShell() {
   return (
-    <ElevasisFeaturesProvider features={features} appShellOverrides={appShellOverrides}>
+    <ElevasisFeaturesProvider features={features} organizationModel={canonicalOrganizationModel}>
       <FeatureShell>
         <Outlet />
       </FeatureShell>
@@ -67,254 +39,55 @@ export function AppShell() {
 }
 ```
 
-What this gives you:
-
-- manifest-backed nav items merged with app-owned nav
-- automatic shared sidebar dispatch for manifests that define both routes and a sidebar
-- shared pages and hooks without copying the same subshell wiring into each app
-
-Dashboard is not part of that shared manifest shell by default. `@elevasis/ui/features/dashboard` exports reusable dashboard components, but it does not publish a `dashboardManifest`.
-
----
+Host apps still own TanStack route registration, topbar behavior, branding, auth wiring, and any root dashboard composition.
 
 ## Contract Matrix
 
-This is the published contract split in `@elevasis/ui@2.9.0`:
-
-| Contract type                            | What is published                                                                                                                   | Current examples                                                                                                                           |
-| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| Manifest-backed shared subshell features | Feature manifest plus shared sidebar/pages, mounted through `@elevasis/ui/provider`                                                 | Lead Gen, CRM, Projects, Operations, SEO                                                                                                   |
-| Manifest-backed nav/app sections         | Feature manifest contributes gated nav and route metadata, but the host still owns the route pages or shell chrome                  | Monitoring, Settings                                                                                                                       |
-| Exported compatibility components        | Reusable components exported without a manifest-backed shell contract                                                               | Dashboard components such as `Dashboard`, `OperationsOverview`, `ResourceOverview`, `RecentExecutionsByResource`, `UnresolvedErrorsTeaser` |
-| Compatibility barrel                     | Existing imports remain available from `@elevasis/ui/components`, but new host integrations should prefer feature/provider subpaths | Manifests, sidebars, and page components re-exported for compatibility                                                                     |
-
-Projects is currently the only packaged system with a first-class `elevasis-sdk project:*` CLI family. Treat that CLI family as the canonical project-management path. Lead Gen and CRM are still primarily UI + API + workflow/runtime surfaces, and browser-facing interactions remain REST-driven even when runtime tools exist.
+| Contract type | What is published | Current examples |
+| --- | --- | --- |
+| Manifest-backed shared subshell features | Feature manifest plus shared sidebar/pages, mounted through `@elevasis/ui/provider` | Lead Gen, CRM, Projects, Operations |
+| Shared feature pages and hooks | Pages, hooks, and helpers that can be composed inside host routes | Monitoring, Settings, Dashboard widgets |
+| Headless provider contract | Provider, hooks, and shell model helpers | `ElevasisFeaturesProvider`, `useElevasisFeatures`, `FeatureShell` |
+| Compatibility barrel | Existing imports remain available while newer integrations prefer feature/provider subpaths | `@elevasis/ui/components` |
 
 ## System Map
 
-| System     | Primary route space | Shared UI surface                                                                               | Main data surface                                                                       | Best SDK entry point                                                                      |
-| ---------- | ------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| Lead Gen   | `/lead-gen/*`       | Lead Gen pages, sidebars, list detail page, run dialogs                                         | Acquisition list APIs + list/acqDb platform tools                                       | `@elevasis/ui/features/lead-gen`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker`            |
-| CRM        | `/crm/*`            | CRM sidebar, overview widgets, deal/detail pages, workbench panels                              | Deal APIs, recent-activity API, acquisition-backed hooks, and the `crm` runtime adapter | `@elevasis/ui/features/crm`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker`                 |
-| Projects   | `/projects/*`       | Projects list page, milestones/tasks/notes sidebars and pages                                   | Project, milestone, task, note REST endpoints + CLI                                     | `@elevasis/ui/features/delivery`, `@elevasis/ui/hooks/delivery`, `elevasis-sdk project:*` |
-| Dashboard  | host-owned          | Dashboard and overview components only; no shared manifest-backed nav contract                  | Host-chosen API composition                                                             | `@elevasis/ui/features/dashboard`                                                         |
-| Monitoring | `/monitoring/*`     | Monitoring nav metadata plus exported pages/components; no shared `FeatureShell` sidebar today  | Monitoring REST APIs                                                                    | `@elevasis/ui/features/monitoring`                                                        |
-| Settings   | `/settings/*`       | Settings nav metadata plus exported settings components; no shared `FeatureShell` sidebar today | Settings/account/org REST APIs                                                          | `@elevasis/ui/features/settings`                                                          |
-
----
-
-## Lead Gen
-
-Lead Gen is now list-oriented. The operational unit is a list, not a batch. Each list owns its own pipeline config and execution history.
-
-### Shared UI Surface
+| System | Primary route space | Shared UI surface | Best SDK entry point |
+| --- | --- | --- | --- |
+| Lead Gen | `/lead-gen/*` | Lead Gen pages, sidebars, list detail page, run dialogs | `@elevasis/ui/features/lead-gen`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker` |
+| CRM | `/crm/*` | CRM sidebar, overview widgets, deal/detail pages, workbench panels | `@elevasis/ui/features/crm`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker` |
+| Projects | `/projects/*` | Projects list page, milestones/tasks/notes sidebars and pages | `@elevasis/ui/features/delivery`, `@elevasis/ui/hooks/delivery`, `elevasis-sdk project:*` |
+| Operations | `/operations/*` | Command View, resources, organization graph, sessions | `@elevasis/ui/features/operations` |
+| Dashboard | `/` host-owned | Dashboard and overview components only | `@elevasis/ui/features/dashboard` |
+| Monitoring | `/monitoring/*` | Monitoring pages/components | `@elevasis/ui/features/monitoring` |
+| Settings | `/settings/*` | Settings/account/org components | `@elevasis/ui/features/settings` |
 
-`@elevasis/ui/features/lead-gen` exports the main Lead Gen building blocks:
+## Organization Model Alignment
 
-- `LeadGenSidebar`
-- `LeadGenOverviewPage`
-- `LeadGenListsPage`
-- `LeadGenListDetailPage`
-- `LeadGenCompaniesPage`
-- `LeadGenContactsPage`
-- `LIST_TEMPLATE_OPTIONS`
-- `buildListConfig`
-
-The most important page for downstream agents is `LeadGenListDetailPage`. It combines:
-
-- list config editing
-- live progress and funnel views
-- execution history
-- per-step run actions via `ResourceExecuteDialog`
-
-### Shared UI Hooks
-
-`@elevasis/ui/hooks` exposes list-aware hooks backed by the acquisition API:
-
-| Hook                          | HTTP path                                   |
-| ----------------------------- | ------------------------------------------- |
-| `useLists()`                  | `GET /acquisition/lists`                    |
-| `useList(listId)`             | `GET /acquisition/lists/:listId`            |
-| `useListsTelemetry()`         | `GET /acquisition/lists/telemetry`          |
-| `useListProgress(listId)`     | `GET /acquisition/lists/:listId/progress`   |
-| `useListExecutions(listId)`   | `GET /acquisition/lists/:listId/executions` |
-| `useCreateList()`             | `POST /acquisition/lists`                   |
-| `useUpdateList(listId)`       | `PATCH /acquisition/lists/:listId`          |
-| `useUpdateListConfig(listId)` | `PATCH /acquisition/lists/:listId/config`   |
-| `useDeleteList()`             | `DELETE /acquisition/lists/:listId`         |
-
-Lead Gen also sits on broader acquisition endpoints for companies and contacts:
-
-- `GET /acquisition/companies`
-- `POST /acquisition/companies`
-- `GET /acquisition/contacts`
-- `POST /acquisition/contacts`
-
-### Workflow Runtime Surface
-
-Inside workflows and agents, there are two relevant platform adapters:
-
-- `acqDb` for broad acquisition CRUD
-- `list` for focused list execution and stage-tracking operations
+Feature IDs in manifests must match Organization Model feature IDs:
 
 ```ts
-import { acqDb, list } from '@elevasis/sdk/worker'
-
-const config = await list.getConfig({ listId })
-
-await list.recordExecution({
-  listId,
-  executionId: context.executionId,
-  payload: { resourceId: context.resourceId },
-})
-
-await list.updateCompanyStage({
-  listId,
-  companyId,
-  stage: 'qualified',
-})
-```
-
-Use `list` when the workflow is scoped to a list run. Use `acqDb` when you need broader company, contact, or deal CRUD.
-
-### CLI Status
-
-There is no dedicated downstream `elevasis-sdk lead-gen:*` family today.
-
-- In this monorepo there is platform-side lead-gen operational tooling, but that is not the same thing as a published downstream SDK CLI contract.
-- For downstream SDK users, the contract is currently UI + HTTP API + workflow/runtime adapters.
-
----
-
-## CRM
-
-CRM is packaged as a shared feature module rather than a one-off app implementation.
-
-### Shared UI Surface
-
-`@elevasis/ui/features/crm` exports:
-
-- `CrmSidebar`
-- `CrmOverview`
-- `DealsListPage`
-- `DealDetailPage`
-- `PipelineFunnelWidget`
-- `TasksDueWidget`
-- `ActivityFeedWidget`
-- `MetricsStrip`
-- `MyTasksPanel`
-- `SavedViewsPanel`
-- `QuickCreateActions`
-
-The CRM manifest is `crmManifest`, with the route prefix `/crm` and feature-key alignment to the acquisition feature set.
-
-### API Surface
-
-CRM is not CLI-first today, but it does have real API-backed behavior and a dedicated runtime adapter for agent/workflow use.
-
-Shared CRM pages and hooks currently rely on:
-
-- deal list/detail surfaces through the acquisition/deal APIs
-- `GET /crm/recent-activity` for the overview activity feed
-- the `crm` platform tool for runtime access to deal, task, note, stage, and activity operations
-
-That means downstream users can build against CRM with shared UI, API, and runtime contracts, but there is not yet a dedicated `elevasis-sdk crm:*` CLI family.
-
-### Practical Guidance
-
-- Use the shared CRM pages first; do not rebuild sidebar and overview chrome locally unless the app truly diverges.
-- Treat CRM overview/workbench components as the canonical packaged surface for downstream apps.
-- When CRM actions depend on acquisition or delivery state, keep the route shell local and compose the shared packaged widgets inside it.
-- Treat CRM as UI + API + runtime tools today, with browser interactivity still driven primarily by REST endpoints rather than the platform adapter.
-
----
-
-## Projects
-
-Projects is the packaged delivery/project-management system. It has both a shared UI surface and a first-class CLI surface in `elevasis-sdk`, plus a dedicated runtime adapter for workflow and agent use.
-
-Within Organization OS, this packaged system sits on the **delivery** semantic domain but is exposed as the first-class feature ID **`projects`**. In practice that means:
-
-- the published UI manifest is `deliveryManifest`
-- the manifest gates against `featureId: 'projects'`
-- the default navigation surface is `projects.index`
-- the underlying semantic entities and capabilities still use delivery-scoped IDs such as `delivery.project`, `delivery.milestone`, `delivery.task`, and `delivery.projects.view`
-
-Treat `elevasis-sdk project:*` as the operational interface to that same contract, not as a separate project system layered beside Organization OS.
-
-### Shared UI Surface
-
-`@elevasis/ui/features/delivery` exports:
-
-- `ProjectsListPage`
-- `ProjectsSidebar`
-- `ProjectsSidebarMiddle`
-- milestone, task, and note status helpers
-- `deliveryManifest`
-
-### Shared UI Hooks
-
-`@elevasis/ui/hooks/delivery` talks to the project-management API:
-
-| Hook                             | HTTP path                             |
-| -------------------------------- | ------------------------------------- |
-| `useProjects()`                  | `GET /projects`                       |
-| `useProject(id)`                 | `GET /projects/:id`                   |
-| `useTasks({ projectId })`        | `GET /projects/:projectId/tasks`      |
-| `useMilestones({ projectId })`   | `GET /projects/:projectId/milestones` |
-| `useProjectNotes({ projectId })` | `GET /projects/:projectId/notes`      |
-| `useCreateTask()`                | `POST /project-tasks`                 |
-| `useUpdateTask()`                | `PATCH /project-tasks/:id`            |
-| `useCreateNote()`                | `POST /project-notes`                 |
-
-### CLI Surface
-
-The SDK CLI exposes the canonical project-management commands:
-
-```bash
-elevasis-sdk project:list
-elevasis-sdk project:get <id>
-elevasis-sdk project:create --name "Website Refresh" --kind client_engagement
-
-elevasis-sdk project:milestone:list --project <id>
-elevasis-sdk project:task:list --project <id>
-elevasis-sdk project:note:list --project <id>
-
-elevasis-sdk project:task:resume <task-id> --pretty
-elevasis-sdk project:task:save <task-id> --current-state "Implemented the API slice"
+features: [
+  { id: 'dashboard', label: 'Dashboard', enabled: true, path: '/', uiPosition: 'sidebar-primary' },
+  { id: 'sales', label: 'Sales', enabled: true, uiPosition: 'sidebar-primary' },
+  { id: 'sales.crm', label: 'CRM', enabled: true, path: '/crm' },
+  { id: 'operations.resources', label: 'Resources', enabled: true, path: '/operations/resources' }
+]
 ```
 
-This matters for downstream user agents because project tasks now have a resumable machine-readable surface. `project:task:resume` returns `resume_context`, and `project:task:save` updates it.
-
-For semantic context, the CLI maps onto the same Organization OS contract that drives the shared shell:
-
-- project records correspond to the `projects` feature in the organization model
-- the shared UI route space resolves through `projects.index`
-- status semantics still come from `organizationModel.delivery`, not from a separate CLI-only schema
-
-### Command Boundary
-
-- `/project` should route here. It is a convenience layer over `elevasis-sdk project:*`, not a separate system.
-- `/work` should stay focused on docs-backed task tracking and resume notes.
-- `/external` applies only to standalone apps in `external/`.
-- `/adev` applies when building, testing, debugging, or executing resources, not when managing project records.
-
----
+Sidebar hierarchy is derived from dotted IDs. Containers omit `path`; leaves provide `path`.
 
 ## Choosing The Right Surface
 
-- Need packaged nav contribution or shared subshell routing? Use `ElevasisFeaturesProvider`, `FeatureShell`, and manifests from `@elevasis/ui/features/<name>`.
-- Need a dashboard or landing page in the app root? Keep that route host-owned and compose exported components from `@elevasis/ui/features/dashboard` or `@elevasis/ui/components`.
+- Need packaged sidebar/page composition? Use `ElevasisFeaturesProvider`, `FeatureShell`, and manifests from `@elevasis/ui/features/*`.
+- Need a root dashboard? Keep that route host-owned and compose dashboard components.
 - Need list-scoped lead-gen runtime behavior? Use the `list` adapter, then `acqDb` for broader acquisition CRUD.
-- Need a custom React page against an existing system? Start with the shared `@elevasis/ui` pages and hooks before writing app-local fetch logic.
-- Need project/task automation from an agent or terminal workflow? Use `elevasis-sdk project:*`.
-
----
+- Need project/task automation? Use `elevasis-sdk project:*`.
 
 ## Related
 
-- [Deployment](index.mdx) - Deploy lifecycle and bundle behavior
-- [Command Center](command-center.mdx) - Managed platform UI after deploy
-- [UI Execution](ui-execution.mdx) - `ResourceExecuteDialog`, execution hooks, and custom run flows
-- [Platform Adapters](../platform-tools/adapters-platform.mdx) - `acqDb`, `list`, `execution`, and other platform services
-- [CLI Reference](../cli.mdx) - Full command catalog, now including project-management commands
+- [Deployment](index.mdx)
+- [Command Center](command-center.mdx)
+- [UI Execution](ui-execution.mdx)
+- [Platform Adapters](../platform-tools/adapters-platform.mdx)
+- [CLI Reference](../cli.mdx)