@elevasis/sdk 0.5.12 → 0.5.14

package/reference/deployment/command-center.mdx

@@ -0,0 +1,226 @@
+---
+title: Command Center
+description: Post-deployment UI reference -- what each page does, the resource graph model, relationships, validation, and how SDK concepts map to Command Center actions
+loadWhen: "User asks about the Command Center UI, post-deployment workflow, monitoring, or the resource graph"
+---
+
+The Command Center is the browser UI for interacting with deployed resources. After you run `elevasis-sdk deploy`, this is where you run workflows, monitor executions, manage approvals, schedule tasks, and review logs.
+
+---
+
+## Quick Reference
+
+| Task                                               | Page           | Path                    |
+| -------------------------------------------------- | -------------- | ----------------------- |
+| Browse deployed resources, view the resource graph | Command View   | `/command-view`         |
+| Approve or reject pending HITL requests            | Command Queue  | `/queue`                |
+| Browse deployed documentation                      | Knowledge Base | `/knowledge-base`       |
+| Search execution history across all resources      | Execution Logs | `/logs`                 |
+| Create API key and OAuth credentials               | Credentials    | `/settings/credentials` |
+| View deployment history and active version         | Deployments    | `/settings/deployments` |
+
+---
+
+## Command View
+
+The Command View is a visual graph of your deployed resources. Each node is a resource (workflow, agent, trigger, integration). Edges are the relationships you declared in `OrganizationResources`.
+
+**What you can do here:**
+
+- See all deployed resources at a glance
+- Trace data flow between resources via declared relationships
+- Identify which resources depend on which integrations
+- Click a node to view resource details (ID, status, type)
+
+### Node Types
+
+Every resource you deploy becomes a node in the graph. Some nodes are executable; others are visual-only.
+
+**Executable nodes:**
+
+| Type     | What It Does                                      | Deployed By           |
+| -------- | ------------------------------------------------- | --------------------- |
+| Workflow | Runs step handlers in sequence or branching paths | `elevasis-sdk deploy` |
+| Agent    | Autonomous LLM-powered resource with tools        | `elevasis-sdk deploy` |
+
+**Visual-only nodes** (no runtime behavior -- exist for the graph):
+
+| Type              | What It Represents                                  | Why It Exists                                 |
+| ----------------- | --------------------------------------------------- | --------------------------------------------- |
+| Trigger           | A webhook or schedule that starts a workflow        | Shows how executions begin                    |
+| Integration       | A credential reference (provider + credential name) | Shows which external services a resource uses |
+| External Resource | A third-party automation (n8n, Make, Zapier)        | Documents automations outside the platform    |
+| Human Checkpoint  | A point where a human makes a decision              | Shows where HITL approval gates exist         |
+
+### Relationships
+
+Relationships are edges in the graph. Declare them in `OrganizationResources`:
+
+```typescript
+const org: OrganizationResources = {
+  workflows: [scoreLeadWorkflow, sendProposalWorkflow],
+  relationships: {
+    'score-lead': {
+      triggers: {
+        workflows: ['send-proposal'],
+      },
+      uses: {
+        integrations: ['attio-integration'],
+      },
+    },
+  },
+};
+```
+
+| Field                | Type       | Meaning                               |
+| -------------------- | ---------- | ------------------------------------- |
+| `triggers.workflows` | `string[]` | Workflows this resource starts        |
+| `triggers.agents`    | `string[]` | Agents this resource starts           |
+| `uses.integrations`  | `string[]` | Integrations this resource depends on |
+
+**Relationships are declarations, not routing.** Declaring that workflow A triggers workflow B does not route A's output to B -- your handler must explicitly invoke B via the `execution` adapter. The graph can drift from reality if declarations don't match code.
+
+### What Is Enforced vs Decorative
+
+| Category                                 | Validated at Deploy          | Matches Runtime | Status         |
+| ---------------------------------------- | ---------------------------- | --------------- | -------------- |
+| Resource IDs unique                      | Yes                          | Yes             | **Enforced**   |
+| Input schema matches execution interface | Yes                          | Yes             | **Enforced**   |
+| Relationship targets exist               | Yes                          | No              | **Decorative** |
+| Trigger routing                          | No                           | No              | **Decorative** |
+| Tool availability per agent              | No                           | No              | **Decorative** |
+| Model config                             | Yes (provider + model valid) | No              | **Decorative** |
+
+Keep relationships in sync with your handler code. When you add an `execution.trigger()` call, add the corresponding relationship declaration.
+
+### Deploy-Time Validation
+
+`elevasis-sdk deploy` and `elevasis-sdk check` both validate:
+
+- Duplicate resource IDs
+- Relationship targets must exist in the same `OrganizationResources`
+- Agent model params (provider, model name, temperature bounds)
+- Workflow step chains (`next.target` must point to existing step names)
+
+**Validation error examples:**
+
+```
+ERROR  Relationship target 'send-proposal' not found in organization resources
+ERROR  Duplicate resource ID 'score-lead' in organization
+```
+
+### Graph Serialization
+
+The platform converts your definitions into `CommandViewNode` (one per resource) and `CommandViewEdge` (one per relationship) structures. `buildEdges()` reads your `relationships` declarations and produces edges as a pure transformation -- no runtime behavior is inferred.
+
+> **SDK takeaway:** Declare relationships in `OrganizationResources` to keep the Command View accurate as your system grows. Update declarations whenever you add or remove `execution.trigger()` calls.
+
+---
+
+## Command Queue
+
+The Command Queue surfaces all pending Human-in-the-Loop (HITL) approval requests from running workflows.
+
+**What you can do here:**
+
+- View pending approval requests with context provided by the workflow
+- Filter by resource, status, or date
+- Approve or reject with an optional comment
+- See the history of past decisions
+
+**How it connects to your code:** Approval requests appear when a workflow step calls `approval.create()`. The workflow pauses at that step and waits for a decision.
+
+```typescript
+import { approval } from '@elevasis/sdk/worker'
+
+const task = await approval.create({
+  actions: [
+    { id: 'approve', label: 'Approve', type: 'primary' },
+    { id: 'reject', label: 'Reject', type: 'danger' },
+  ],
+  context: { dealId, proposalUrl },
+  description: 'Approve proposal before sending',
+})
+```
+
+> **SDK takeaway:** Use `approval.create()` to create approval gates. Provide rich `context` so reviewers have what they need to decide.
+
+---
+
+## Knowledge Base
+
+The Knowledge Base renders the `docs/` directory of your deployed workspace as browsable documentation.
+
+**What you can do here:**
+
+- Browse pages you created in `docs/*.mdx`
+- Search across all documentation
+- Share links to specific pages with team members
+
+**How it connects to your code:** Every `.mdx` file in your workspace's `docs/` directory is bundled at deploy time and rendered here.
+
+> **SDK takeaway:** Write `docs/*.mdx` pages for your team -- business process docs, schema references, usage guides. They appear here automatically after each deploy.
+
+---
+
+## Execution Logs
+
+The Execution Logs page shows the history of all executions across every deployed resource.
+
+**What you can do here:**
+
+- Search and filter by resource, status (completed/failed/running), date range
+- Click any execution to view full detail: input, output, step-level trace, duration
+- Identify failed executions and see error messages with stack traces
+- Navigate from a log entry directly to the resource in Command View
+
+**Filtering tips:**
+
+- Filter by resource name to debug a specific workflow
+- Filter by `failed` status to triage production issues
+- Use date range to narrow down incidents
+
+> **SDK takeaway:** Every `elevasis-sdk exec` and every scheduled run appears here. Use this page to verify behavior after deploy and to diagnose failures before opening code.
+
+---
+
+## Credentials
+
+The Credentials page manages encrypted API keys and OAuth tokens used by your workflows at runtime.
+
+**What you can do here:**
+
+- Create API key and webhook-secret credentials via a form
+- Connect OAuth providers (Notion, Google Sheets, Dropbox) via browser flow
+- View existing credentials (values are never shown after creation)
+- Delete credentials that are no longer needed
+
+**Two credential types:**
+
+| Type                     | Created via                                  | Notes                                                  |
+| ------------------------ | -------------------------------------------- | ------------------------------------------------------ |
+| API key / webhook secret | CLI (`elevasis-sdk creds create`) or UI form | Either method works                                    |
+| OAuth                    | UI only                                      | Requires browser redirect -- cannot be created via CLI |
+
+> **SDK takeaway:** Reference credentials in your code by name (`credential: 'my-cred-name'`). Create API keys via CLI or UI; OAuth credentials require this page.
+
+---
+
+## Deployments
+
+The Deployments page shows the history of all deployments for your organization.
+
+**What you can do here:**
+
+- View a chronological list of past deployments
+- See which resources changed in each deployment
+- Identify the currently active version
+- Compare resource counts across deployments
+
+**How it connects to your code:** Each `elevasis-sdk deploy` run creates a new deployment entry. The platform activates the new version atomically -- in-flight executions complete against the previous version while new executions start against the new one.
+
+> **SDK takeaway:** Check this page after `elevasis-sdk deploy` to confirm your resources are active.
+
+---
+
+**Last Updated:** 2026-03-06

package/reference/deployment/index.mdx

@@ -1,153 +1,158 @@
----
-title: Deploying Resources
-description: How to deploy your Elevasis SDK resources to the platform using elevasis-sdk deploy, including configuration, validation, and environment setup
-loadWhen: "Preparing to deploy or debugging deploy failures"
----
-
-Deploying your resources makes them live on the Elevasis platform and immediately available for execution. The deploy process validates your resource definitions, bundles your code into a single self-contained file, and uploads it to the platform -- no server-side dependency installation required.
-
----
-
-## How Deployment Works
-
-When you run `elevasis-sdk deploy`, the CLI performs these steps in order:
-
-1. **Authenticate** -- calls the API with your `ELEVASIS_API_KEY` to verify credentials and resolve your organization name
-2. **Validate** -- runs your `src/index.ts` through `ResourceRegistry`, catching the same errors as the platform
-3. **Bundle** -- uses esbuild to produce a single self-contained `dist/bundle.js` file (~50-200 KB) containing your code and all dependencies
-4. **Upload** -- sends the bundle and resource metadata to the platform via `POST /api/external/deploy`
-5. **Go live** -- the platform registers your resources; they are immediately available for execution
-
-There is no local dev server and no separate staging environment. Deployed resources run directly on the platform. Local testing uses `tsc --noEmit` and Vitest with direct handler calls.
-
----
-
-## Running a Deploy
-
-```bash
-elevasis-sdk deploy
-```
-
-**Successful deploy output:**
-
-```
-  Authenticating...          done (acme-corp)
-  Validating...              done (4 resources, 0 errors)
-  Bundling...                done (142 KB)
-  Uploading...               done
-
-  Deployed! 4 resources live.
-  Deployment: deploy_abc123
-```
-
-Each deploy creates a new deployment record. The previous active deployment is automatically stopped. You can view all deployments with `elevasis-sdk deployments`.
-
----
-
-## Validation
-
-The CLI validates your resources before bundling. Validation uses the same `ResourceRegistry` as the platform, so errors caught locally are the same errors that would be caught at deploy time.
-
-**Validation checks:**
-
-- Duplicate `resourceId` within your organization
-- Invalid model configuration (temperature and token bounds out of range)
-- `ExecutionInterface` form fields not matching `inputSchema`
-- Broken workflow step chains (`next` referencing a step that does not exist)
-- Relationship declarations referencing resources that do not exist
-
-**Validation failure output:**
-
-```
-  Authenticating...          done (acme-corp)
-  Validating...
-    ERROR  Duplicate resource ID 'onboard-client' in organization 'Acme Corp'
-    ERROR  Workflow step 'send-email' references non-existent next step 'notify'
-
-  2 errors. Deploy aborted.
-```
-
-Run `elevasis-sdk check` at any time to validate without deploying.
-
----
-
-## Configuration
-
-The CLI reads `elevasis.config.ts` from your project root. All fields are optional -- the organization name is resolved from your API key, not from config.
-
-```typescript
-// elevasis.config.ts
-import type { ElevasConfig } from '@elevasis/sdk'
-
-export default {} satisfies ElevasConfig
-```
-
-The `ElevasConfig` type is exported from `@elevasis/sdk`. You can leave the config empty or extend it as options are added in future SDK versions.
-
----
-
-## Environment Variables
-
-| Variable | Required | Description |
-| -------- | -------- | ----------- |
-| `ELEVASIS_API_KEY` | Yes | Your `sk_...` API key. Used for authentication and organization resolution. |
-| `ELEVASIS_API_URL` | No | Override the API base URL. Useful for pointing at a staging environment. |
-
-The CLI also accepts a `--api-url` flag on every command, which takes priority over `ELEVASIS_API_URL`.
-
-**API URL resolution order:**
-
-1. `--api-url` flag (highest priority)
-2. `ELEVASIS_API_URL` environment variable
-3. `NODE_ENV`-based default (production: `https://api.elevasis.io`, development: localhost)
-
-**Setting `ELEVASIS_API_KEY` via `.env` file:**
-
-```
-ELEVASIS_API_KEY=sk_***
-```
-
-Place `.env` in your project root. The CLI reads it automatically. Never commit this file.
-
----
-
-## Deployment Lifecycle
-
-Each call to `elevasis-sdk deploy` creates a new deployment. The platform tracks all deployments for your organization.
-
-| Status | Meaning |
-| ------ | ------- |
-| `deploying` | Bundle is being processed and resources are being registered |
-| `active` | Resources are live and available for execution |
-| `stopped` | Superseded by a newer deployment |
-| `failed` | Deploy did not complete (validation or bundle error) |
-
-Only one deployment can be `active` at a time. Deploying again automatically moves the previous active deployment to `stopped`.
-
-**View deployment history:**
-
-```bash
-elevasis-sdk deployments
-```
-
-```
-  deploy_abc123   active    2026-02-25 14:00:00   4 resources
-  deploy_abc122   stopped   2026-02-24 09:30:00   3 resources
-  deploy_abc121   stopped   2026-02-23 11:15:00   3 resources
-```
-
----
-
-## Bundle Details
-
-The deploy bundle is a single CJS file produced by esbuild. It includes:
-
-- Your resource definitions from `src/index.ts`
-- The `@elevasis/sdk/worker` runtime that handles execution messages from the platform
-- All your npm dependencies (fully self-contained, no `node_modules` needed on the server)
-
-The bundle is stored on the platform for durability and restart recovery. If the platform API restarts, it re-downloads your bundle and re-registers your resources automatically -- no action required on your part.
-
----
-
-**Last Updated:** 2026-02-25
+---
+title: Deploying Resources
+description: How to deploy your Elevasis SDK resources to the platform using elevasis-sdk deploy, including configuration, validation, and environment setup
+loadWhen: "Preparing to deploy or debugging deploy failures"
+---
+
+Deploying your resources makes them live on the Elevasis platform and immediately available for execution. The deploy process validates your resource definitions, bundles your code into a single self-contained file, and uploads it to the platform -- no server-side dependency installation required.
+
+---
+
+## How Deployment Works
+
+When you run `elevasis-sdk deploy`, the CLI performs these steps in order:
+
+1. **Authenticate** -- calls the API with your `ELEVASIS_PLATFORM_KEY` to verify credentials and resolve your organization name
+2. **Validate** -- runs your `src/index.ts` through `ResourceRegistry`, catching the same errors as the platform
+3. **Bundle** -- uses esbuild to produce a single self-contained `dist/bundle.js` file (~50-200 KB) containing your code and all dependencies
+4. **Upload** -- sends the bundle and resource metadata to the platform via `POST /api/external/deploy`
+5. **Go live** -- the platform registers your resources; they are immediately available for execution
+
+There is no local dev server and no separate staging environment. Deployed resources run directly on the platform. Local testing uses `tsc --noEmit` and Vitest with direct handler calls.
+
+---
+
+## Running a Deploy
+
+```bash
+elevasis-sdk deploy
+```
+
+**Successful deploy output:**
+
+```
+  Authenticating...          done (acme-corp)
+  Validating...              done (4 resources, 0 errors)
+  Bundling...                done (142 KB)
+  Uploading...               done
+
+  Deployed! 4 resources live.
+  Deployment: deploy_abc123
+```
+
+Each deploy creates a new deployment record. The previous active deployment is automatically stopped. You can view all deployments with `elevasis-sdk deployments`.
+
+---
+
+## Validation
+
+The CLI validates your resources before bundling. Validation uses the same `ResourceRegistry` as the platform, so errors caught locally are the same errors that would be caught at deploy time.
+
+**Validation checks:**
+
+- Duplicate `resourceId` within your organization
+- Invalid model configuration (temperature and token bounds out of range)
+- `ExecutionInterface` form fields not matching `inputSchema`
+- Broken workflow step chains (`next` referencing a step that does not exist)
+- Relationship declarations referencing resources that do not exist
+
+**Validation failure output:**
+
+```
+  Authenticating...          done (acme-corp)
+  Validating...
+    ERROR  Duplicate resource ID 'onboard-client' in organization 'Acme Corp'
+    ERROR  Workflow step 'send-email' references non-existent next step 'notify'
+
+  2 errors. Deploy aborted.
+```
+
+Run `elevasis-sdk check` at any time to validate without deploying.
+
+---
+
+## Configuration
+
+The CLI reads `elevasis.config.ts` from your project root. All fields are optional -- the organization name is resolved from your API key, not from config.
+
+```typescript
+// elevasis.config.ts
+import type { ElevasConfig } from '@elevasis/sdk'
+
+export default {} satisfies ElevasConfig
+```
+
+The `ElevasConfig` type is exported from `@elevasis/sdk`. You can leave the config empty or extend it as options are added in future SDK versions.
+
+---
+
+## Environment Variables
+
+| Variable                | Required | Description                                                                 |
+| ----------------------- | -------- | --------------------------------------------------------------------------- |
+| `ELEVASIS_PLATFORM_KEY` | Yes      | Your `sk_...` API key. Used for authentication and organization resolution. |
+| `ELEVASIS_API_URL`      | No       | Override the API base URL. Useful for pointing at a staging environment.    |
+
+The CLI also accepts a `--api-url` flag on every command, which takes priority over `ELEVASIS_API_URL`.
+
+**API URL resolution order:**
+
+1. `--api-url` flag (highest priority)
+2. `ELEVASIS_API_URL` environment variable
+3. `NODE_ENV`-based default (production: `https://api.elevasis.io`, development: localhost)
+
+**Setting `ELEVASIS_PLATFORM_KEY` via `.env` file:**
+
+```
+ELEVASIS_PLATFORM_KEY=sk_***
+```
+
+Place `.env` in your project root. The CLI reads it automatically. Never commit this file.
+
+---
+
+## Deployment Lifecycle
+
+Each call to `elevasis-sdk deploy` creates a new deployment. The platform tracks all deployments for your organization.
+
+| Status      | Meaning                                                      |
+| ----------- | ------------------------------------------------------------ |
+| `deploying` | Bundle is being processed and resources are being registered |
+| `active`    | Resources are live and available for execution               |
+| `stopped`   | Superseded by a newer deployment                             |
+| `failed`    | Deploy did not complete (validation or bundle error)         |
+
+Only one deployment can be `active` at a time. Deploying again automatically moves the previous active deployment to `stopped`.
+
+**View deployment history:**
+
+```bash
+elevasis-sdk deployments
+```
+
+```
+  deploy_abc123   active    2026-02-25 14:00:00   4 resources
+  deploy_abc122   stopped   2026-02-24 09:30:00   3 resources
+  deploy_abc121   stopped   2026-02-23 11:15:00   3 resources
+```
+
+---
+
+## Bundle Details
+
+The deploy bundle is a single CJS file produced by esbuild. It includes:
+
+- Your resource definitions from `src/index.ts`
+- The `@elevasis/sdk/worker` runtime that handles execution messages from the platform
+- All your npm dependencies (fully self-contained, no `node_modules` needed on the server)
+
+The bundle is stored on the platform for durability and restart recovery. If the platform API restarts, it re-downloads your bundle and re-registers your resources automatically -- no action required on your part.
+
+## Documentation
+
+- [Command Center](command-center.mdx) - Resource graph, relationships, node types, and post-deployment UI reference
+- [Execution API](api.mdx) - REST endpoints for executing resources and managing deployments
+
+---
+
+**Last Updated:** 2026-02-25