@elevasis/sdk 0.5.12 → 0.5.13

package/reference/deployment/{command-center-ui.mdx → command-center.mdx}

@@ -1,151 +1,229 @@
----
-title: Command Center UI
-description: Reference for the Elevasis Command Center -- what each page does, when to use it post-deployment, and how SDK concepts map to UI actions
-loadWhen: "User asks about the Command Center UI, post-deployment workflow, or monitoring deployed resources"
----
-
-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. This reference covers each page and how it connects to your SDK code.
-
----
-
-## 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)
-
-**Graph accuracy:** The graph reflects your `relationships` declarations, not runtime behavior. If your handler calls another resource without a declared relationship, the edge is missing from the graph. Keep declarations in sync with your code.
-
-For the full relationship model and what is enforced vs. decorative, see `reference/deployment/command-view.mdx`.
-
-> **SDK takeaway:** Declare relationships in `OrganizationResources` to keep the Command View accurate as your system grows.
-
----
-
-## 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 here when a workflow step calls `approval.requestApproval()`. The workflow pauses at that step and waits for a decision before continuing.
-
-```typescript
-import { approval } from '@elevasis/sdk/worker'
-
-const result = await approval.requestApproval({
-  title: 'Approve proposal before sending',
-  context: { dealId, proposalUrl },
-})
-
-if (result.approved) {
-  // continue
-}
-```
-
-> **SDK takeaway:** Use `approval.requestApproval()` to create approval gates that surface here. 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. Pages appear in the order defined by their `order` frontmatter field.
-
-> **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 |
-
-**OAuth credentials require the UI.** When a workflow uses an OAuth-connected service, the user must complete the OAuth flow here first. The CLI `creds` skill handles API keys; redirect OAuth credential setup to this page.
-
-> **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. If something behaves unexpectedly, look here to confirm the latest version is live.
-
----
-
-**Last Updated:** 2026-03-03
+---
+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: {
+    'score-lead': scoreLeadWorkflow,
+    'send-proposal': 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.requestApproval()`. The workflow pauses at that step and waits for a decision.
+
+```typescript
+import { approval } from '@elevasis/sdk/worker'
+
+const result = await approval.requestApproval({
+  title: 'Approve proposal before sending',
+  context: { dealId, proposalUrl },
+})
+
+if (result.approved) {
+  // continue
+}
+```
+
+> **SDK takeaway:** Use `approval.requestApproval()` 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