@elevasis/sdk 1.20.2 → 1.22.0

package/reference/deployment/command-center.mdx

@@ -1,209 +1,209 @@
----
-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`                |
-| 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 `DeploymentSpec`.
-
-**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 `DeploymentSpec`:
-
-```typescript
-const org: DeploymentSpec = {
-  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 `DeploymentSpec`
-- 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 deployment
-```
-
-### 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 `DeploymentSpec` 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.
-
----
-
-## 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 (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
+---
+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`                |
+| 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 `DeploymentSpec`.
+
+**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 `DeploymentSpec`:
+
+```typescript
+const org: DeploymentSpec = {
+  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 `DeploymentSpec`
+- 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 deployment
+```
+
+### 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 `DeploymentSpec` 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.
+
+---
+
+## 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 (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