@elevasis/sdk 0.4.9 → 0.4.11

package/reference/_navigation.md

@@ -1,104 +1,106 @@
 # SDK Reference Navigation
 
-Auto-generated from reference file frontmatter. 29 files indexed.
+Auto-generated from reference file frontmatter. 31 files indexed.
 
 All paths are relative to `node_modules/@elevasis/sdk/reference/`.
 
 ## General
 
-| Resource | Location | When to Load |
-| --- | --- | --- |
-| Elevasis SDK | `index.mdx` | First session or new to the SDK |
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Elevasis SDK | `index.mdx` | Build and deploy workflows, agents, and resources with the Elevasis SDK | First session or new to the SDK |
 
 ## Cli
 
-| Resource | Location | When to Load |
-| --- | --- | --- |
-| CLI Reference | `cli/index.mdx` | Running CLI operations |
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| CLI Reference | `cli/index.mdx` | Full reference for every elevasis CLI command -- scaffold, validate, deploy, execute, and inspect resources | Running CLI operations |
 
 ## Concepts
 
-| Resource | Location | When to Load |
-| --- | --- | --- |
-| Concepts Reference | `concepts/index.mdx` | User asks what is or needs conceptual grounding |
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Concepts Reference | `concepts/index.mdx` | Plain-English explanations of Elevasis SDK concepts -- glossary, workflow analogies, Zod schemas, execution model, platform tools, common errors, and design decisions | User asks what is or needs conceptual grounding |
 
 ## Deployment
 
-| Resource | Location | When to Load |
-| --- | --- | --- |
-| Execution API | `deployment/api.mdx` | Calling the API directly or debugging API responses |
-| Deploying Resources | `deployment/index.mdx` | Preparing to deploy or debugging deploy failures |
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Execution API | `deployment/api.mdx` | REST endpoints for executing resources, querying execution history, and managing deployments via the Elevasis external API | Calling the API directly or debugging API responses |
+| Command View | `deployment/command-view.mdx` | How the Command View graph works -- node types, relationships, what is enforced vs decorative, and what the platform needs to render your resource graph | Deploying resources or building resources that invoke other resources |
+| Deploying Resources | `deployment/index.mdx` | How to deploy your Elevasis SDK resources to the platform using elevasis deploy, including configuration, validation, and environment setup | Preparing to deploy or debugging deploy failures |
 
 ## Developer
 
-| Resource | Location | When to Load |
-| --- | --- | --- |
-| Interaction Guidance | `developer/interaction-guidance.mdx` | Unsure how to adapt for a skill combination |
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Interaction Guidance | `developer/interaction-guidance.mdx` | Full dimensional adaptation rules per skill axis -- programming, TypeScript, API integration, automation concepts, domain expertise -- with growth tracking protocol | Unsure how to adapt for a skill combination |
 
 ## Framework
 
-| Resource | Location | When to Load |
-| --- | --- | --- |
-| Agent System | `framework/agent.mdx` | Configuring agent behavior or capabilities |
-| Resource Documentation | `framework/documentation.mdx` | Writing or updating project documentation |
-| Development Framework | `framework/index.mdx` | Understanding the agent framework structure |
-| Memory System | `framework/memory.mdx` | Working with agent memory or session state |
-| Project Structure | `framework/project-structure.mdx` | Understanding scaffolded files or project layout |
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Agent System | `framework/agent.mdx` | CLAUDE.md drives all agent behavior -- project instructions, slash commands, memory-based developer profile, and three-tier adaptive guidance | Configuring agent behavior or capabilities |
+| Resource Documentation | `framework/documentation.mdx` | Write and deploy MDX documentation alongside your Elevasis resources | Writing or updating project documentation |
+| Development Framework | `framework/index.mdx` | The SDK scaffolds a complete development environment for Claude Code -- project instructions, slash commands, cross-session memory, and template versioning | Understanding the agent framework structure |
+| Memory System | `framework/memory.mdx` | Cross-session project knowledge stored in .claude/memory/ -- deployment state, environment, decisions, and error patterns that persist between Claude Code sessions | Working with agent memory or session state |
+| Project Structure | `framework/project-structure.mdx` | Each file scaffolded by elevasis init and its purpose in the development workflow | Understanding scaffolded files or project layout |
 
 ## Getting-started
 
-| Resource | Location | When to Load |
-| --- | --- | --- |
-| Getting Started | `getting-started/index.mdx` | Setting up a new project or onboarding |
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Getting Started | `getting-started/index.mdx` | Install the Elevasis SDK, scaffold a project, and run your first deployment | Setting up a new project or onboarding |
 
 ## Platform-tools
 
-| Resource | Location | When to Load |
-| --- | --- | --- |
-| Integration Examples | `platform-tools/examples.mdx` | Implementing a platform tool call in a workflow step |
-| Platform Tools | `platform-tools/index.mdx` | Connecting to external services |
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Typed Adapters | `platform-tools/adapters.mdx` | Type-safe wrappers over platform.call() for all integrations and platform tools -- Attio, Stripe, Notion, Google Sheets, Trello, and more -- with full autocomplete, compile-time checking, and zero boilerplate | Using typed adapters instead of raw platform.call(), or needs to know what adapter methods are available |
+| Integration Examples | `platform-tools/examples.mdx` | Working code examples for email, CRM, PDF, LLM inference, resource triggering, and storage using typed adapters and platform.call() | Implementing a platform tool call in a workflow step |
+| Platform Tools | `platform-tools/index.mdx` | Access 70+ tools across integration adapters and platform services from your SDK workflows -- typed adapters with full autocomplete for all tools, plus platform.call() as a fallback | Connecting to external services |
 
 ## Resources
 
-| Resource | Location | When to Load |
-| --- | --- | --- |
-| Writing Resources | `resources/index.mdx` | Building or modifying a workflow |
-| Common Patterns | `resources/patterns.mdx` | Building or modifying a workflow |
-| SDK Types | `resources/types.mdx` | Looking up type signatures or SDK exports |
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Writing Resources | `resources/index.mdx` | Guide to creating workflows and agents using WorkflowDefinition, AgentDefinition, and OrganizationResources with the Elevasis SDK | Building or modifying a workflow |
+| Common Patterns | `resources/patterns.mdx` | Common resource patterns for Elevasis SDK developers -- sequential steps, conditional branching, platform tools, error handling, and resource status management | Building or modifying a workflow |
+| SDK Types | `resources/types.mdx` | Complete type reference for @elevasis/sdk -- package exports, re-exported platform types, ElevasConfig interface, StepHandler context, and runtime values | Looking up type signatures or SDK exports |
 
 ## Roadmap
 
-| Resource | Location | When to Load |
-| --- | --- | --- |
-| Roadmap | `roadmap/index.mdx` | Asking about future features or planned capabilities |
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Roadmap | `roadmap/index.mdx` | Planned SDK features -- error taxonomy, retry semantics, circuit breaker, metrics, alerting, and resource lifecycle extensions | Asking about future features or planned capabilities |
 
 ## Runtime
 
-| Resource | Location | When to Load |
-| --- | --- | --- |
-| Execution Runtime | `runtime/index.mdx` | Debugging execution behavior or understanding the runtime model |
-| Resource Limits & Quotas | `runtime/limits.mdx` | Hitting resource limits or planning for scale |
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Execution Runtime | `runtime/index.mdx` | How your code runs on the Elevasis platform -- execution lifecycle, concurrency, timeouts, cancellation, error handling, and observability | Debugging execution behavior or understanding the runtime model |
+| Resource Limits & Quotas | `runtime/limits.mdx` | Memory limits, execution timeouts, scale quotas, networking constraints, and v1 platform limitations for SDK resources | Hitting resource limits or planning for scale |
 
 ## Security
 
-| Resource | Location | When to Load |
-| --- | --- | --- |
-| Credential Security | `security/credentials.mdx` | Setting up integrations or configuring tool access |
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Credential Security | `security/credentials.mdx` | Three-layer credential model: platform tools (server-side injection), http tool (arbitrary APIs), getCredential() (explicit opt-in raw access) -- .env scope and security boundaries | Setting up integrations or configuring tool access |
 
 ## Templates
 
-| Resource | Location | When to Load |
-| --- | --- | --- |
-| Template: Data Enrichment | `templates/data-enrichment.mdx` | Applying the data-enrichment workflow template |
-| Template: Email Sender | `templates/email-sender.mdx` | Applying the email-sender workflow template |
-| Template: Lead Scorer | `templates/lead-scorer.mdx` | Applying the lead-scorer workflow template |
-| Template: PDF Generator | `templates/pdf-generator.mdx` | Applying the pdf-generator workflow template |
-| Template: Recurring Job | `templates/recurring-job.mdx` | Applying the recurring-job workflow template |
-| Template: Text Classifier | `templates/text-classifier.mdx` | Applying the text-classifier workflow template |
-| Template: Web Scraper | `templates/web-scraper.mdx` | Applying the web-scraper workflow template |
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Template: Data Enrichment | `templates/data-enrichment.mdx` | LLM-powered enrichment of existing database records -- read rows, enrich each with an LLM, write results back to Supabase | Applying the data-enrichment workflow template |
+| Template: Email Sender | `templates/email-sender.mdx` | Transactional email via Resend with template support -- send styled emails to one or multiple recipients | Applying the email-sender workflow template |
+| Template: Lead Scorer | `templates/lead-scorer.mdx` | LLM-based lead scoring with Supabase storage -- receive a lead, score it with an LLM, store the result | Applying the lead-scorer workflow template |
+| Template: PDF Generator | `templates/pdf-generator.mdx` | PDF generation from structured data with platform storage upload -- render a PDF from a template and upload to platform storage | Applying the pdf-generator workflow template |
+| Template: Recurring Job | `templates/recurring-job.mdx` | Scheduler-triggered periodic workflow -- run a task on a schedule (daily, weekly, hourly, or custom cron) | Applying the recurring-job workflow template |
+| Template: Text Classifier | `templates/text-classifier.mdx` | Multi-label text classification with structured output -- classify text into predefined categories using an LLM with JSON output | Applying the text-classifier workflow template |
+| Template: Web Scraper | `templates/web-scraper.mdx` | Apify-based web scraper that stores results in Supabase -- fetch structured data from any website via Apify actors | Applying the web-scraper workflow template |
 
 ## Troubleshooting
 
-| Resource | Location | When to Load |
-| --- | --- | --- |
-| Common Errors | `troubleshooting/common-errors.mdx` | Debugging an unknown error not found in workspace memory |
+| Resource | Location | Description | When to Load |
+| --- | --- | --- | --- |
+| Common Errors | `troubleshooting/common-errors.mdx` | Static SDK-level error catalog -- CLI errors, deployment errors, schema validation, platform tool failures, and runtime errors with diagnostic steps | Debugging an unknown error not found in workspace memory |

package/reference/deployment/command-view.mdx

@@ -0,0 +1,154 @@
+---
+title: Command View
+description: How the Command View graph works -- node types, relationships, what is enforced vs decorative, and what the platform needs to render your resource graph
+loadWhen: "Deploying resources or building resources that invoke other resources"
+---
+
+The Command View is a visual graph in the Elevasis command center that shows how your organization's resources connect. Nodes are resources (workflows, agents, integrations). Edges are relationships you declare between them. The graph helps operators understand how automation flows through the system at a glance.
+
+---
+
+## Node Types
+
+Every resource you deploy becomes a node in the Command View. Some nodes are executable (the platform runs them); others are visual-only (they exist for the graph but have no runtime behavior).
+
+### Executable Nodes
+
+| Type | What It Does | Deployed By |
+| ---- | ------------ | ----------- |
+| Workflow | Runs step handlers in sequence or branching paths | `elevasis deploy` |
+| Agent | Autonomous LLM-powered resource with tools | `elevasis deploy` |
+
+### Visual-Only Nodes
+
+These exist solely for the Command View graph. They have no runtime behavior -- the platform does not execute them.
+
+| 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 |
+
+Visual-only nodes are declarations. A `TriggerDefinition` does not set up actual trigger routing -- the webhook gateway routes independently. An `IntegrationDefinition` does not configure or connect to anything -- it is a visual node referencing a credential.
+
+---
+
+## Relationships
+
+Relationships are edges in the Command View graph. You declare them in `OrganizationResources` to tell the platform how resources connect.
+
+### Declaring Relationships
+
+```typescript
+const org: OrganizationResources = {
+  workflows: {
+    'score-lead': scoreLeadWorkflow,
+    'send-proposal': sendProposalWorkflow,
+  },
+  agents: {
+    'research-agent': researchAgent,
+  },
+  relationships: {
+    'score-lead': {
+      triggers: {
+        workflows: ['send-proposal'],  // score-lead triggers send-proposal
+        agents: ['research-agent'],     // score-lead triggers research-agent
+      },
+      uses: {
+        integrations: ['attio-integration'],  // score-lead uses Attio
+      },
+    },
+  },
+};
+```
+
+### Relationship Fields
+
+| 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 |
+
+All referenced IDs must exist in the same organization. Missing targets cause a validation error at deploy time.
+
+### Relationships Are Declarations, Not Routing
+
+Relationships tell the Command View what edges to draw. They do **not** create execution paths. If you declare that workflow A triggers workflow B, the platform does not automatically route A's output to B. Your handler code must explicitly invoke B using the `execution` adapter or `platform.call()`.
+
+This means the graph can drift from reality:
+
+- If your code invokes resource B but you forgot to declare the relationship, the edge is **missing** from the graph
+- If you declared a relationship to resource B but your code never invokes it, the edge is **stale** in the graph
+
+---
+
+## 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 -- invocations are hardcoded strings in handlers | **Decorative** |
+| Trigger routing | No | No -- webhook handlers route independently | **Decorative** |
+| Tool availability per agent | No | No -- tools built dynamically at runtime | **Decorative** |
+| Model config | Yes (provider + model valid) | No -- runtime uses environment config | **Decorative** |
+| Integration usage | Partial (IDs checked) | No -- credentials resolved at runtime | **Decorative** |
+
+**Enforced** means the platform rejects invalid state. **Decorative** means the platform trusts your declaration but does not verify it matches what the code actually does.
+
+### What This Means for You
+
+- Keep relationships in sync with your handler code. When you add an `execution.trigger('other-resource')` call, add the corresponding relationship declaration.
+- When you remove an invocation, remove the relationship.
+- The Command View is only as accurate as your declarations.
+
+---
+
+## Deploy-Time Validation
+
+When you run `elevasis deploy` or `elevasis check`, the SDK validates your resource definitions locally using the same `ResourceRegistry` the platform uses.
+
+### What Gets Checked
+
+- **Duplicate resource IDs** -- two resources with the same key in `workflows` or `agents`
+- **Relationship targets exist** -- every ID in `triggers` and `uses` must match a resource or integration in the same `OrganizationResources`
+- **Model configuration** -- agent model params (provider, model name, temperature bounds) are valid
+- **Step chains** -- `next.target` values in multi-step workflows point to existing step names
+
+### What Does Not Get Checked
+
+- Whether your handler code actually invokes the resources you declared in relationships
+- Whether your handler code invokes resources you did **not** declare in relationships
+- Whether triggers route to the workflows you declared
+- Whether agents use the tools you expect
+
+These are the decorative gaps listed above. The graph is a best-effort representation that depends on you keeping declarations in sync with code.
+
+### Validation Error Examples
+
+```
+ERROR  Relationship target 'send-proposal' not found in organization resources
+  Resource: score-lead
+  Field: relationships.triggers.workflows
+
+ERROR  Duplicate resource ID 'score-lead' in organization
+```
+
+Fix relationship errors by checking that the target resource ID is spelled correctly and exists in your `OrganizationResources` export. If the resource was renamed or removed, update the relationship to match.
+
+---
+
+## Graph Serialization
+
+The platform converts your resource definitions and relationships into a visual graph using two data structures:
+
+- **`CommandViewNode`** -- one per resource (workflow, agent, trigger, integration, etc.). Contains the resource ID, type, name, status, and metadata.
+- **`CommandViewEdge`** -- one per relationship. Contains source node, target node, and edge type (triggers, uses).
+
+The `buildEdges()` function in the platform registry reads your `relationships` declarations and produces `CommandViewEdge[]`. This is a pure transformation -- it does not add or remove edges based on runtime behavior.
+
+---
+
+**Last Updated:** 2026-03-02