@elevasis/sdk 1.3.0 → 1.5.0

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.
+

package/reference/resources/patterns.mdx

@@ -101,7 +101,7 @@ const scoreStep: WorkflowStep = {
 
 ## Using Platform Tools in Steps
 
-Platform tools let your steps call integrations managed by Elevasis (email, CRM, databases, etc.). Import `platform` from `@elevasis/sdk/worker` and call it with the tool name, method, parameters, and a credential reference.
+Platform tools let your steps call integrations managed by Elevasis (email, CRM, databases, etc.). Import `platform` from `@elevasis/sdk/worker` and call it with the tool name, method, parameters, and an optional credential reference when the tool requires one.
 
 ```typescript
 import { platform, PlatformToolError } from '@elevasis/sdk/worker';
@@ -132,7 +132,7 @@ const sendEmailStep: WorkflowStep = {
 **Key points:**
 
 - `platform.call()` is async and times out after 60 seconds
-- `credential` is the name of a platform environment variable set via `elevasis-sdk env set`
+- `credential` is the name of a platform environment variable set via `elevasis-sdk env set` when the tool needs one
 - On failure, `platform.call()` throws `PlatformToolError` (not `ToolingError`)
 - Always log success so executions are easy to debug in the dashboard
 
@@ -149,18 +149,64 @@ import { platform, PlatformToolError } from '@elevasis/sdk/worker';
 
 const step = async (input) => {
   try {
-    const result = await platform.call({
+    const deals = await platform.call({
       tool: 'crm',
-      method: 'createContact',
-      params: { email: input.email, name: input.name },
-      credential: 'CRM_API_KEY',
+      method: 'listDeals',
+      params: { stage: 'proposal', limit: 10 },
     });
-    return { contactId: result.id };
+
+    const deal = deals[0]
+      ? await platform.call({
+          tool: 'crm',
+          method: 'getDeal',
+          params: { dealId: deals[0].id },
+        })
+      : null;
+
+    if (deal) {
+      await platform.call({
+        tool: 'crm',
+        method: 'updateDealStage',
+        params: { dealId: deal.id, stage: 'closing' },
+      });
+
+      await platform.call({
+        tool: 'crm',
+        method: 'createDealNote',
+        params: {
+          dealId: deal.id,
+          body: 'Reviewed proposal and moved the deal forward.',
+        },
+      });
+
+      await platform.call({
+        tool: 'crm',
+        method: 'createDealTask',
+        params: {
+          dealId: deal.id,
+          title: 'Send updated proposal',
+          dueAt: input.followUpAt ?? null,
+        },
+      });
+
+      await platform.call({
+        tool: 'crm',
+        method: 'recordActivity',
+        params: {
+          dealId: deal.id,
+          type: 'stage_changed',
+          title: 'Deal moved to closing',
+          description: 'Reviewed the proposal and moved the deal forward.',
+        },
+      });
+    }
+
+    return { dealId: deal?.id ?? null, dealCount: deals.length };
   } catch (err) {
     if (err instanceof PlatformToolError) {
       // Tool failed -- log it and return a degraded result
       console.error('CRM tool failed:', err.message);
-      return { contactId: null, error: err.message };
+      return { dealId: null, error: err.message };
     }
     throw err; // re-throw unexpected errors
   }

package/reference/scaffold/core/organization-graph.mdx

@@ -0,0 +1,262 @@
+---
+title: Organization Graph
+description: Organization OS Graph layer documentation for the Cytoscape-based organization graph, derived from the organization model and bridged with Command View runtime topology through the shared feature provider.
+---
+
+## Overview
+
+Within Organization OS, the organization graph is the dedicated **Graph** layer. It treats the organization model as the top-level ontology and bridges in Command View runtime topology so one graph can support semantic exploration and operations-oriented tracing. It is not a replacement renderer for Command View; it is a shared graph product that subsumes Command View as one operational lens.
+
+Graph contracts live in `@repo/core` alongside the organization model. Rendering lives in `@repo/ui` with Cytoscape.js. The command-center route is a thin wrapper over the shared page.
+
+## Status
+
+First implementation slices are live end-to-end. Command View now delegates to the graph through a command-view lens preset. Layout iteration on the one-panel graph + command surface is ongoing; graph contracts and provider bridge are stable.
+
+Graph types are intentionally **not** part of the published `@elevasis/core` surface yet. Graph adoption remains monorepo-first.
+
+## Source of Truth
+
+- `packages/core/src/organization-model/graph/types.ts` -- node/edge DTO shapes
+- `packages/core/src/organization-model/graph/schema.ts` -- runtime validation
+- `packages/core/src/organization-model/graph/build.ts` -- `buildOrganizationGraph(...)` derivation
+- `packages/core/src/organization-model/__tests__/graph.test.ts` -- derivation and bridge tests
+- `packages/ui/src/features/operations/OrganizationGraphPage.tsx` -- shared Cytoscape page
+- `packages/ui/src/features/operations/CommandViewPage.tsx` -- command-view lens delegating to the graph
+- `packages/ui/src/features/operations/organization-graph/` -- filter helpers, detail-state helpers, path tracing, operational summary
+- `packages/ui/src/features/operations/manifest.ts` -- `organizationGraph.surfaceId = 'operations.organization-graph'`
+- `apps/command-center/src/routes/operations/organization-graph.index.tsx` -- route wrapper
+
+## Product Jobs
+
+The graph helps users:
+
+- orient themselves in the organization model
+- discover how domains, capabilities, surfaces, entities, resources, and workflows connect
+- trace upstream/downstream dependencies
+- understand ownership and implementation boundaries
+- assess blast radius before changing a workflow, agent, feature, or integration
+- operate across strategy, operations, and debugging through different lenses on the same graph
+
+The graph does not replace workflow editors, execution-run visualizers, or builder-style authoring canvases. React Flow remains the better fit for editor/execution visuals; Cytoscape fits the exploration-oriented ontology graph.
+
+## Architecture
+
+### Unified graph model
+
+The implementation uses one typed graph, not separate semantic and implementation taxonomies.
+
+- Node kinds: `organization`, `feature`, `domain`, `surface`, `entity`, `capability`, `resource`
+- Edge kinds: `contains`, `references`, `exposes`, `maps_to`
+- `resource` nodes carry `resourceType` metadata: `workflow`, `agent`, `trigger`, `integration`, `external`, or `human_checkpoint`
+- `references` edges may also carry `relationshipType`: `triggers`, `uses`, or `approval`
+
+This means runtime topology is represented as bridged `resource` nodes plus relationship metadata on shared edge types, rather than as a second disconnected edge/node vocabulary.
+
+### Compatibility rules with the organization model
+
+- `OrganizationModelSchema` is the source of truth for semantic structure. The graph does not introduce a second ontology.
+- Graph node IDs and references reuse organization-model IDs wherever those IDs already exist.
+- `domain` nodes derive from `organizationModel.domains`.
+- `surface` nodes derive from `organizationModel.navigation.surfaces`; graph routing respects surface `path` and `defaultSurfaceId`.
+- Feature gating and labels respect `organizationModel.features.enabled` and `.labels`.
+- Implementation-resource bridging prefers `organizationModel.resourceMappings`.
+- Graph defaults remain valid when produced by `resolveOrganizationModel()`.
+- If the graph needs a concept the model cannot express, extend the model first.
+
+### Shared DTO
+
+```ts
+type OrganizationGraphNodeKind =
+  | 'organization'
+  | 'feature'
+  | 'domain'
+  | 'surface'
+  | 'entity'
+  | 'capability'
+  | 'resource'
+
+type OrganizationGraphEdgeKind = 'contains' | 'references' | 'exposes' | 'maps_to'
+
+interface OrganizationGraph {
+  version: 1
+  organizationModelVersion: OrganizationModel['version']
+  nodes: OrganizationGraphNode[]
+  edges: OrganizationGraphEdge[]
+}
+```
+
+`OrganizationGraphNode` also includes optional `sourceId`, `description`, `enabled`, `featureKey`, `surfaceType`, and `resourceType`. `OrganizationGraphEdge` includes optional `label` and `relationshipType`.
+
+### Build pipeline
+
+```ts
+interface BuildOrganizationGraphInput {
+  organizationModel: OrganizationModel
+  commandViewData?: CommandViewData
+}
+```
+
+`buildOrganizationGraph` accepts optional topology input so the semantic graph still renders when operational bridging is sparse. The derivation flow is additive and upsert-oriented:
+
+1. Resolve the active organization model.
+2. Derive semantic nodes and edges from domains, features, surfaces, entities, capabilities, and resource mappings.
+3. Upsert bridged runtime resources from Command View data into shared `resource` nodes.
+4. Merge topology relationships onto the same DTO using `references` or `maps_to` edges plus optional `relationshipType`.
+5. Hand the resulting graph to UI-level lensing, filtering, and Cytoscape projection.
+
+Keeping assembly outside the renderer keeps graph semantics testable without UI and prevents Cytoscape concepts from leaking into business logic.
+
+### Ownership split
+
+- `@repo/core` owns normalized node/edge types, schemas, and build/derivation helpers.
+- `@repo/ui` owns Cytoscape element conversion, layout presets, selection/hover/expansion/viewport state, detail panels, and presentation helpers.
+- `apps/command-center` owns route wiring and page-level integration.
+
+## Interaction Model
+
+### Lenses
+
+The graph ships with two lens presets in UI code:
+
+- `default` -- title "Organization Graph", initial mode `map`, no preset filters
+- `command-view` -- title "Command View", initial mode `trace`, filters preset to `nodeKinds: ['resource']` and `topologyPresence: 'topology-only'`
+
+Lenses do not change the core DTO. They configure how the shared graph is initially presented.
+
+### Modes
+
+- **Map mode** -- clustered for broad graph orientation
+- **Trace mode** -- directed layout that privileges path readability
+- **Impact mode** -- centered radial/concentric layout around the current focus
+
+Layouts are deterministic presets, not unconstrained force simulation:
+
+- `map` uses Cytoscape `cose`
+- `trace` uses directed `breadthfirst`
+- `impact` uses degree-based `concentric`
+
+### Interactions
+
+Primary set, kept small and high-value:
+
+- click node for detail panel
+- click edge for relationship meaning
+- hover for adjacency preview
+- search and jump to node
+- expand immediate neighbors
+- isolate selected node + N-hop neighborhood
+- switch mode
+- pin selected nodes
+- highlight shortest or most relevant path between two nodes
+- filter by node kind, domain, capability, feature, status, environment
+
+Deferred: freeform node placement, collaborative annotations, graph editing/authoring, arbitrary canvas drawing.
+
+### Filtering
+
+The filter state lives in `useOrganizationGraphFilters()` and the toolbar UI in `OrganizationGraphFilterToolbar`.
+
+Filter inputs:
+
+- `search`
+- `nodeKinds`
+- `topologyPresence: 'all' | 'semantic-only' | 'topology-only'`
+
+Presence is derived per node:
+
+- `resource` nodes are `topology-only`
+- nodes with only semantic edges are `semantic-only`
+- nodes with both semantic and topology edges are treated as bridge nodes internally
+
+Search matches node IDs, labels, descriptions, source IDs, feature keys, surface/resource types, edge labels, edge kinds, and `relationshipType`.
+
+The page applies `useDeferredValue()` to the active filters so graph search stays responsive while typing.
+
+### Path tracing
+
+The visible Cytoscape surface projects a **filtered** shared graph DTO rather than rendering the full graph unconditionally. Path tracing resolves and highlights directed paths inside the current visible projection, so filtering and tracing stay coherent.
+
+Renderer-agnostic helpers under `packages/ui/src/features/operations/organization-graph/path-tracing/` implement shortest-path logic independent of Cytoscape.
+
+## Provider Integration
+
+The graph is exposed through `ElevasisFeaturesProvider` rather than as app-local glue:
+
+- `FeatureModule.organizationGraph.surfaceId` declares a manifest's bridge point.
+- `operationsManifest` declares `organizationGraph.surfaceId = 'operations.organization-graph'`.
+- The provider resolves that against `organizationModel.navigation.surfaces` and exposes the result as `organizationGraph` in context.
+- Shared UI/operations code stays manifest-driven while remaining aware of semantic organization topology.
+
+## Command View Integration
+
+`CommandViewPage` now delegates to `OrganizationGraphPage` through a command-view lens preset. The lens restores high-value operational context through:
+
+- route-level execution-health cards
+- selection-aware resource and human-checkpoint summaries inside the shared graph detail panel
+- follow-up actions for recent executions and pending tasks inside the detail panel
+- dedicated command-view sidebar content (`Command View` labeling and node filters live in the subshell sidebar, not on the graph canvas)
+
+Operational summary and drill-down derivation is covered by tests under `packages/ui/src/features/operations/organization-graph/__tests__/`.
+
+The detail experience is shared through `OrganizationGraphDetailPanel`, which can render both semantic context and command-view-specific follow-up sections.
+
+## Cytoscape Responsibility Split
+
+Cytoscape owns:
+
+- element rendering
+- compound/group visualization
+- neighborhood traversal and selection state
+- path highlighting
+- collapsed/expanded cluster behavior
+- layout execution
+- viewport mechanics (pan, zoom, fit, focus)
+
+React owns:
+
+- mode switching
+- side panels and inspectors
+- search and command-palette entry
+- route state and deep-linking
+- server data fetching
+- persistence of saved filters and views
+
+## Package Boundary
+
+- `packages/ui/package.json` declares Cytoscape on the published UI surface.
+- `packages/ui/tsup.config.ts` and `packages/ui/rollup.dts.config.mjs` keep Cytoscape **externalized** for publish output.
+- Graph DTO types are internal to `@repo/core`. The published `@elevasis/core` wrapper still exposes only the narrow organization-model API. External graph adoption should not be assumed.
+
+## Theming
+
+The shared Cytoscape page reads CSS custom properties at runtime via `window.getComputedStyle(document.documentElement)`. Nodes, edges, overlays, and glass panels stay aligned with the active UI theme instead of relying on a fixed graph-only palette.
+
+## Cytoscape States
+
+The renderer applies CSS-class-style state markers to highlight context and traces:
+
+- `.is-faded`
+- `.is-context`
+- `.is-selected`
+- `.is-connected`
+- `.is-trace-node`
+- `.is-trace-endpoint`
+- `.is-trace-edge`
+
+These classes drive neighborhood focus, selection emphasis, and trace-path highlighting without changing the underlying DTO.
+
+## Migration Guardrails
+
+- Do not move canonical graph interfaces into `packages/ui`.
+- Do not redefine organization-model semantics in app-local graph config.
+- Do not make the graph contract depend on Cytoscape-specific types.
+- Existing Command View relationships bridge into `relationshipType = triggers | uses | approval` -- do not overload those operational labels with new semantic meaning.
+
+## Verification
+
+- `pnpm --filter @repo/core test -- organization-model graph`
+- `pnpm --filter @repo/ui test -- commandViewDrillDown commandViewOperationalSummary organizationGraphDetail`
+- `pnpm --filter @repo/ui build`
+- `pnpm --filter @repo/ui build:publish`
+- `pnpm --filter command-center build`