@elevasis/sdk 1.26.1 → 1.27.0

package/reference/scaffold/reference/contracts.md

@@ -1331,38 +1331,33 @@ export interface HumanCheckpointDefinition extends ResourceDefinition {
 ### `DeploymentSpec`
 
 ```typescript
-/**
- * Organization-specific resource collection
- *
- * Complete manifest of all automation resources for an organization.
- * Used by ResourceRegistry for discovery and Command View for visualization.
- */
-export interface DeploymentSpec {
+/**
+ * Organization-specific resource collection
+ *
+ * Complete manifest of all automation resources for an organization.
+ * Used by ResourceRegistry for discovery and Command View for visualization.
+ */
+export interface DeploymentSpec {
   /** Deployment version (semver) */
   version: string
-  /** Optional Organization Model governance catalog used for OM-code validation */
-  organizationModel?: Partial<
-    Pick<
-      OrganizationModel,
-      'systems' | 'resources' | 'ontology' | 'topology' | 'roles' | 'policies' | 'entities' | 'actions'
-    >
-  >
-  /** Workflow definitions */
-  workflows?: WorkflowDefinition[]
-  /** Agent definitions */
-  agents?: AgentDefinition[]
-
-  // Resource Manifest fields (optional for backwards compatibility)
-  /** Trigger definitions - entry points that initiate executions */
-  triggers?: TriggerDefinition[]
-  /** Integration definitions - external service connections */
-  integrations?: IntegrationDefinition[]
-  /** Explicit relationship declarations between resources */
-  relationships?: ResourceRelationships
-  /** External automation resources (n8n, Make, Zapier, etc.) */
-  externalResources?: ExternalResourceDefinition[]
-  /** Human checkpoint definitions - human decision points in automation */
-  humanCheckpoints?: HumanCheckpointDefinition[]
+  /** Optional full Organization Model snapshot used for OM-code validation and deployment persistence */
+  organizationModel?: OrganizationModel
+  /** Workflow definitions */
+  workflows?: WorkflowDefinition[]
+  /** Agent definitions */
+  agents?: AgentDefinition[]
+
+  // Resource Manifest fields (optional for backwards compatibility)
+  /** Trigger definitions - entry points that initiate executions */
+  triggers?: TriggerDefinition[]
+  /** Integration definitions - external service connections */
+  integrations?: IntegrationDefinition[]
+  /** Explicit relationship declarations between resources */
+  relationships?: ResourceRelationships
+  /** External automation resources (n8n, Make, Zapier, etc.) */
+  externalResources?: ExternalResourceDefinition[]
+  /** Human checkpoint definitions - human decision points in automation */
+  humanCheckpoints?: HumanCheckpointDefinition[]
 }
 ```
 

package/reference/deployment/api.mdx

@@ -1,296 +0,0 @@
----
-title: Execution API
-description: REST endpoints for executing resources, querying execution history, and managing deployments via the Elevasis external API
----
-
-The Elevasis external API exposes REST endpoints under `/api/external/` for executing your deployed resources and inspecting results. All endpoints require your `ELEVASIS_PLATFORM_KEY` sent as a Bearer token. Organization is resolved server-side from the API key -- you never pass an org identifier in requests.
-
-**Authentication header:**
-
-```
-Authorization: Bearer sk_...
-```
-
----
-
-## API Base URL
-
-| Environment | Base URL                    |
-| ----------- | --------------------------- |
-| Production  | `https://api.elevasis.io`   |
-| Development | `http://localhost:<port>` |
-
-Override the base URL by setting `ELEVASIS_API_URL` in your environment or passing `--api-url` to any CLI command.
-
----
-
-## Endpoints
-
-| Method | Path                                                       | Purpose                                  |
-| ------ | ---------------------------------------------------------- | ---------------------------------------- |
-| `GET`  | `/api/external/resources`                                  | List all resources for your organization |
-| `GET`  | `/api/external/resources/:resourceId/definition`           | Get resource metadata and schemas        |
-| `POST` | `/api/external/execute`                                    | Execute a resource synchronously         |
-| `POST` | `/api/external/execute-async`                              | Execute a resource asynchronously        |
-| `POST` | `/api/external/executions/:resourceId/:executionId/cancel` | Cancel a running execution               |
-| `GET`  | `/api/external/executions/:resourceId`                     | List execution history for a resource    |
-| `GET`  | `/api/external/executions/:resourceId/:executionId`        | Get full execution detail                |
-| `POST` | `/api/external/deploy`                                     | Upload bundle and deploy resources       |
-| `GET`  | `/api/external/deployments`                                | List all deployments                     |
-| `GET`  | `/api/external/deployments/:id`                            | Get a deployment by ID                   |
-
----
-
-## Execution Endpoints
-
-### POST /api/external/execute
-
-Execute a resource synchronously. The request waits for the resource to complete and returns the full result.
-
-**Request body:**
-
-```json
-{
-  "resourceId": "onboard-client",
-  "input": {
-    "clientName": "Jane",
-    "email": "jane@example.com"
-  }
-}
-```
-
-**Response:**
-
-```json
-{
-  "executionId": "550e8400-e29b-41d4-a716-446655440000",
-  "success": true,
-  "data": {
-    "success": true,
-    "clientId": "client_1708521600000",
-    "welcomeEmailSent": true
-  }
-}
-```
-
-### POST /api/external/execute-async
-
-Execute a resource asynchronously. Returns immediately with an `executionId`. Poll `GET /executions/:resourceId/:executionId` to check status and retrieve output.
-
-**Request body:**
-
-```json
-{
-  "resourceId": "onboard-client",
-  "input": { "clientName": "Jane" }
-}
-```
-
-**Response:**
-
-```json
-{
-  "executionId": "550e8400-e29b-41d4-a716-446655440000",
-  "status": "running"
-}
-```
-
-### POST /api/external/executions/:resourceId/:executionId/cancel
-
-Cancel a running execution. If the execution is found in memory, sends a cancellation signal immediately. Falls back to a database status update if no in-memory signal is found.
-
-**Response:**
-
-```json
-{
-  "success": true
-}
-```
-
----
-
-## Resource Endpoints
-
-### GET /api/external/resources
-
-List all resources registered to your organization. In production, only `status: 'prod'` resources are returned.
-
-**Response:**
-
-```json
-[
-  {
-    "resourceId": "onboard-client",
-    "resourceType": "workflow",
-    "name": "Onboard Client",
-    "status": "prod"
-  },
-  {
-    "resourceId": "email-assistant",
-    "resourceType": "agent",
-    "name": "Email Assistant",
-    "status": "prod"
-  }
-]
-```
-
-### GET /api/external/resources/:resourceId/definition
-
-Get the full definition for a single resource: metadata, input schema, and output schema.
-
-**Response:**
-
-```json
-{
-  "resourceId": "onboard-client",
-  "resourceType": "workflow",
-  "name": "Onboard Client",
-  "description": "Creates a client record and sends a welcome email",
-  "status": "prod",
-  "inputSchema": {
-    "type": "object",
-    "properties": {
-      "clientName": { "type": "string" },
-      "email": { "type": "string", "format": "email" }
-    },
-    "required": ["clientName", "email"]
-  },
-  "outputSchema": {
-    "type": "object",
-    "properties": {
-      "success": { "type": "boolean" },
-      "clientId": { "type": "string" }
-    }
-  }
-}
-```
-
-Returns `404` if the resource is not found.
-
----
-
-## Execution History Endpoints
-
-### GET /api/external/executions/:resourceId
-
-List execution history for a resource.
-
-**Query parameters:**
-
-| Parameter | Description                                                     |
-| --------- | --------------------------------------------------------------- |
-| `limit`   | Maximum number of results (default: 20)                         |
-| `status`  | Filter by status: `running`, `completed`, `failed`, `cancelled` |
-
-**Response:**
-
-```json
-[
-  {
-    "executionId": "550e8400-e29b-41d4-a716-446655440000",
-    "resourceId": "onboard-client",
-    "status": "completed",
-    "createdAt": "2026-02-25T14:32:01Z",
-    "durationMs": 1234
-  }
-]
-```
-
-### GET /api/external/executions/:resourceId/:executionId
-
-Get the full detail for a single execution including input, output, logs, and error.
-
-**Response:**
-
-```json
-{
-  "executionId": "550e8400-e29b-41d4-a716-446655440000",
-  "resourceId": "onboard-client",
-  "status": "completed",
-  "createdAt": "2026-02-25T14:32:01Z",
-  "durationMs": 1234,
-  "input": {
-    "clientName": "Jane",
-    "email": "jane@example.com"
-  },
-  "output": {
-    "success": true,
-    "clientId": "client_1708521600000",
-    "welcomeEmailSent": true
-  },
-  "logs": [
-    { "timestamp": "2026-02-25T14:32:01.123Z", "message": "Starting onboard-client workflow" },
-    { "timestamp": "2026-02-25T14:32:01.456Z", "message": "Created client record" }
-  ],
-  "error": null
-}
-```
-
----
-
-## Deployment Endpoints
-
-### POST /api/external/deploy
-
-Upload a resource bundle and deploy it. Accepts a multipart request with the compiled bundle and resource metadata.
-
-**Response:**
-
-```json
-{
-  "deployId": "deploy_abc123",
-  "status": "active",
-  "resources": 4
-}
-```
-
-Use `elevasis-sdk deploy` from the CLI rather than calling this endpoint directly -- the CLI handles bundling, metadata generation, and status streaming automatically.
-
-### GET /api/external/deployments
-
-List all deployments for your organization.
-
-**Response:**
-
-```json
-[
-  {
-    "id": "deploy_abc123",
-    "status": "active",
-    "createdAt": "2026-02-25T14:00:00Z",
-    "resources": 4
-  },
-  {
-    "id": "deploy_abc122",
-    "status": "stopped",
-    "createdAt": "2026-02-24T09:30:00Z",
-    "resources": 3
-  }
-]
-```
-
-### GET /api/external/deployments/:id
-
-Get a single deployment by ID.
-
-**Response shape:** Same as a single item from `GET /deployments`.
-
----
-
-## CLI Execution Commands
-
-The SDK CLI wraps all execution endpoints. Use these commands instead of calling the API directly during development:
-
-| Command                                                | API call                                     | Purpose                  |
-| ------------------------------------------------------ | -------------------------------------------- | ------------------------ |
-| `elevasis-sdk resources`                               | `GET /api/external/resources`                | List all resources       |
-| `elevasis-sdk describe <resource>`                   | `GET /api/external/resources/:id/definition` | Show resource definition |
-| `elevasis-sdk exec <resource> --input '...'`         | `POST /api/external/execute`                 | Execute synchronously    |
-| `elevasis-sdk exec <resource> --input '...' --async` | `POST /api/external/execute-async`           | Execute asynchronously   |
-| `elevasis-sdk executions <resource>`                 | `GET /api/external/executions/:id`           | List execution history   |
-| `elevasis-sdk execution <resource> <id>`           | `GET /api/external/executions/:id/:execId`   | Get execution detail     |
-| `elevasis-sdk deployments`                             | `GET /api/external/deployments`              | List deployments         |
-
----
-
-**Last Updated:** 2026-02-25

package/reference/deployment/provided-features.mdx

@@ -1,110 +0,0 @@
----
-title: Provided Features
-description: Shared UI and API surfaces for packaged business systems like Lead Gen, CRM, Projects, Operations, Monitoring, and Settings via @elevasis/ui/features/*.
----
-
-The SDK includes more than workflow execution. The published `@elevasis/ui` package provides system manifests, pages, hooks, and headless provider exports for building shell-aware applications.
-
-## Shared Shell Contract
-
-`ElevasisSystemsProvider` reads the canonical `OrganizationModel`, including `navigation.sidebar`, and exposes a shell model plus sidebar projection helpers. System manifests provide implementation hooks such as icons and subshell sidebars; they do not own structural navigation.
-
-```tsx
-import { Outlet } from '@tanstack/react-router'
-import { ElevasisSystemsProvider, SystemShell } 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 '@core/config/organization-model'
-
-const systems = [
-  leadGenManifest,
-  crmManifest,
-  deliveryManifest,
-  monitoringManifest,
-  settingsManifest
-]
-
-export function AppShell() {
-  return (
-    <ElevasisSystemsProvider systems={systems} organizationModel={canonicalOrganizationModel}>
-      <SystemShell>
-        <Outlet />
-      </SystemShell>
-    </ElevasisSystemsProvider>
-  )
-}
-```
-
-Host apps still own TanStack route registration, topbar behavior, branding, auth wiring, and any root dashboard composition.
-
-## Contract Matrix
-
-| Contract type                           | What is published                                                                           | Current examples                                               |
-| --------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| Manifest-backed shared subshell systems | System 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                                                    | `ElevasisSystemsProvider`, `useElevasisSystems`, `SystemShell` |
-| 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                                                  | 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`                                                          |
-
-## Organization Model Alignment
-
-Manifest `systemId` values must match Organization Model System IDs. Sidebar placement is authored in the Organization Model navigation domain:
-
-```ts
-systems: {
-  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
-  clients: { id: 'clients', order: 20, label: 'Clients', lifecycle: 'active' }
-},
-navigation: {
-  sidebar: {
-    primary: {
-      dashboard: { type: 'surface', order: 10, label: 'Dashboard', path: '/', surfaceType: 'dashboard', targets: { systems: ['dashboard'] } },
-      business: {
-        type: 'group',
-        order: 20,
-        label: 'Business',
-        children: {
-          clients: { type: 'surface', order: 20, label: 'Clients', path: '/clients', surfaceType: 'list', targets: { systems: ['clients'] } }
-        }
-      }
-    },
-    bottom: {}
-  }
-}
-```
-
-Dashboard appears before Business in the primary sidebar. Business is a navigation group only; `/clients` is the canonical client route.
-
-## Choosing The Right Surface
-
-- Need packaged sidebar/page composition? Use `ElevasisSystemsProvider`, `SystemShell`, 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 project/task automation? Use `elevasis-sdk project:*`.
-
-## Related
-
-- [Deployment](index.mdx)
-- [Command Center](command-center.mdx)
-- [UI Execution](ui-execution.mdx)
-- [Platform Adapters](../platform-tools/adapters-platform.mdx)
-- [CLI Reference](../cli.mdx)
-
----
-
-**Last Updated:** 2026-03-06