@elevasis/sdk 0.5.11 → 0.5.13

package/reference/{runtime/index.mdx → runtime.mdx}

@@ -1,141 +1,196 @@
----
-title: Execution Runtime
-description: How your code runs on the Elevasis platform -- execution lifecycle, concurrency, timeouts, cancellation, error handling, and observability
-loadWhen: "Debugging execution behavior or understanding the runtime model"
----
-
-This page covers everything that happens after you deploy -- how resources execute as managed processes, how failures surface to you, and what observability data you can access. For resource limits and quotas, see [Resource Limits & Quotas](limits.mdx).
-
----
-
-## Execution Lifecycle
-
-### The Four Stages
-
-Every execution traverses four stages: trigger, route, execute, and return.
-
-1. **Trigger** -- A user, CLI command, or API call initiates execution. The platform creates an execution record with `status: 'running'` and generates a unique `executionId`.
-2. **Route** -- The platform resolves the target resource from the registry. All resources (static and external) coexist in a single in-memory registry with no database queries at lookup time.
-3. **Execute** -- An ephemeral worker thread is created from your deployed bundle and sent the execution request. The worker matches the `resourceId` to your definition, validates the input against your Zod schema, and runs the handler. For workflows, steps execute sequentially following the `next` chain. The worker is terminated immediately after execution completes.
-4. **Return** -- The worker posts the result back to the platform. The platform stores the final result, updates the execution record, and fans events out to AI Studio and CLI subscribers.
-
-### Concurrency Model
-
-Workers are ephemeral -- each execution creates a new worker thread. There is no persistent pool:
-
-- **Per-execution isolation:** Each execution gets its own worker thread. Concurrent executions for the same organization run in separate workers with no shared state.
-- **Memory:** Each worker is capped at 256MB. Concurrent workers multiply memory usage proportionally.
-- **No cold start:** Workers are created fresh per execution. Your first execution and hundredth are identical in terms of startup behavior.
-
-### Timeout Enforcement
-
-Timeouts are enforced by the platform. You do not handle them explicitly in your code:
-
-- **Default timeout:** A platform default applies to all resource types unless overridden.
-- **Per-resource override:** Agents can configure `constraints.timeout` in the agent definition. Workflows use the platform default.
-- **Enforcement:** When a timeout fires, the worker is terminated immediately -- even if it is stuck in a synchronous loop. No special handler signature is required on your part.
-
-### Cancellation Protocol
-
-Cancellation is initiated by the platform and requires no special code in your handler:
-
-1. A cancellation request is received -- via CLI, API, or platform timeout.
-2. The platform aborts the execution controller registered for that `executionId`.
-3. The worker is terminated immediately (kills the worker even if stuck in a synchronous loop).
-4. The platform records the cancellation in the execution record.
-
-**What triggers cancellation:**
-
-- You call `POST /api/external/executions/:resourceId/:executionId/cancel` via CLI or API
-- The platform timeout expires
-- The resource is deleted while an execution is in-flight
-
----
-
-## Error Handling
-
-### How Errors Reach You
-
-Errors are displayed depending on the surface you use to inspect them:
-
-- **AI Studio:** Shows the error message and execution status. Example: `Remote resource 'onboard-client' failed: Email delivery failed: invalid address`
-- **CLI (`elevasis-sdk execution <resourceId> <id>`):** Shows full execution detail including the error message. The `--json` flag includes an `error` field in structured output.
-- **Error message source:** The error string comes directly from your handler's catch block (`String(err)`). The platform stores this verbatim and displays it as-is. Write descriptive error messages in your handlers -- they surface directly to users.
-
-### What Causes a Failed Execution
-
-- **Unhandled exception in your handler:** The worker reports `status: 'failed'` with the error message.
-- **Memory limit exceeded (256MB):** The worker crashes with an out-of-memory error. The platform catches this; other tenants are unaffected.
-- **Timeout exceeded:** The platform terminates the worker and marks the execution failed with a timeout reason.
-- **Cancellation:** Execution is marked cancelled.
-
----
-
-## Observability
-
-### Logging
-
-You produce logs using standard `console` methods -- no special logger object is needed:
-
-- **Console interception:** The SDK worker runtime intercepts `console.log`, `console.warn`, and `console.error` during handler execution and captures them as structured `{ level, message }` entries.
-- **Level mapping:** `console.log` maps to `info`, `console.warn` maps to `warn`, `console.error` maps to `error`.
-- **No changes required:** Any code that already uses `console.log` automatically has its output captured. Existing code works without modification.
-
-### Log Transport
-
-Logs are delivered to the platform atomically with the execution result:
-
-- **Bundled delivery:** All logs for an execution are included in the result message when the handler completes. There is no real-time streaming -- logs arrive with the final result.
-- **Crash behavior:** If the worker crashes before completing, logs captured up to the crash point are lost. The platform records only the crash error.
-
-### Log Retention and Display
-
-- **Retention:** 30 days by default (configurable per plan).
-- **Real-time fanout:** After execution completes, logs are stored and fanned out to AI Studio and CLI subscribers. AI Studio shows them in the execution detail view.
-- **CLI access:** Use `elevasis-sdk execution <resourceId> <id>` to view execution details including logs.
-
----
-
-## Resource Lifecycle
-
-### Status
-
-Every resource on the platform has a status that you control in your definition:
-
-- **`dev`** -- Default for new resources. Visible in AI Studio and executable, but marked with a "Development" badge. Use this during testing and iteration.
-- **`prod`** -- Set `status: 'prod'` in your resource definition before deploying. No badge. This is the live, production-ready state.
-
-### Versioning
-
-v1 versioning is intentionally simple:
-
-- **One active version per resource per org.** Deploying replaces the running version. There is no version history at the resource level; previous deploys are marked stopped.
-- **Immutable per deploy.** A resource definition is frozen at deploy time. Changing code requires a new deploy.
-
-### Deletion
-
-- **Via CLI:** Remove the resource from your `OrganizationResources` export and run `elevasis-sdk deploy`. Resources absent from the new bundle are automatically deregistered from the platform.
-- **Via AI Studio:** The delete button unregisters the resource immediately and marks the deployment stopped.
-- **In-flight executions:** Workers already running complete normally. Deletion affects only new execution attempts.
-- **Data retention:** Execution logs and history for a deleted resource are retained for 30 days, then purged.
-
----
-
-## Platform Storage
-
-Your deployed bundle is stored in Supabase Storage. On API restart, the platform re-registers all active deployments from the database and re-downloads bundles if needed. This means:
-
-- **No data loss on restart:** Your resources are automatically re-registered after platform restarts.
-- **No action required from you:** The platform handles recovery transparently.
-
----
-
-## Platform Maintenance
-
-- **Rolling updates:** Platform upgrades trigger a re-registration of all active deployments on startup. No in-flight executions are lost (workers are ephemeral and complete independently).
-- **In-flight executions during restart:** Already-running workers complete normally. New executions use the newly reloaded registry after restart.
-- **Advance notice:** You will receive 24-hour advance notice for breaking maintenance windows. These are rare and reserved for major infrastructure changes.
-
----
-
-**Last Updated:** 2026-02-25
+---
+title: Execution Runtime
+description: How your code runs on the Elevasis platform -- execution lifecycle, concurrency, timeouts, cancellation, error handling, observability, resource limits, and v1 limitations
+loadWhen: "Debugging execution behavior or understanding the runtime model"
+---
+
+This page covers everything that happens after you deploy -- how resources execute as managed processes, how failures surface to you, what observability data you can access, and the hard limits enforced on all executions.
+
+---
+
+## Execution Lifecycle
+
+### The Four Stages
+
+Every execution traverses four stages: trigger, route, execute, and return.
+
+1. **Trigger** -- A user, CLI command, or API call initiates execution. The platform creates an execution record with `status: 'running'` and generates a unique `executionId`.
+2. **Route** -- The platform resolves the target resource from the registry. All resources (static and external) coexist in a single in-memory registry with no database queries at lookup time.
+3. **Execute** -- An ephemeral worker thread is created from your deployed bundle and sent the execution request. The worker matches the `resourceId` to your definition, validates the input against your Zod schema, and runs the handler. For workflows, steps execute sequentially following the `next` chain. The worker is terminated immediately after execution completes.
+4. **Return** -- The worker posts the result back to the platform. The platform stores the final result, updates the execution record, and fans events out to AI Studio and CLI subscribers.
+
+### Concurrency Model
+
+Workers are ephemeral -- each execution creates a new worker thread. There is no persistent pool:
+
+- **Per-execution isolation:** Each execution gets its own worker thread. Concurrent executions for the same organization run in separate workers with no shared state.
+- **Memory:** Each worker is capped at 256MB. Concurrent workers multiply memory usage proportionally.
+- **No cold start:** Workers are created fresh per execution. Your first execution and hundredth are identical in terms of startup behavior.
+
+### Timeout Enforcement
+
+Timeouts are enforced by the platform. You do not handle them explicitly in your code:
+
+- **Default timeout:** A platform default applies to all resource types unless overridden.
+- **Per-resource override:** Agents can configure `constraints.timeout` in the agent definition. Workflows use the platform default.
+- **Enforcement:** When a timeout fires, the worker is terminated immediately -- even if it is stuck in a synchronous loop. No special handler signature is required on your part.
+
+### Cancellation Protocol
+
+Cancellation is initiated by the platform and requires no special code in your handler:
+
+1. A cancellation request is received -- via CLI, API, or platform timeout.
+2. The platform aborts the execution controller registered for that `executionId`.
+3. The worker is terminated immediately (kills the worker even if stuck in a synchronous loop).
+4. The platform records the cancellation in the execution record.
+
+**What triggers cancellation:**
+
+- You call `POST /api/external/executions/:resourceId/:executionId/cancel` via CLI or API
+- The platform timeout expires
+- The resource is deleted while an execution is in-flight
+
+---
+
+## Error Handling
+
+### How Errors Reach You
+
+Errors are displayed depending on the surface you use to inspect them:
+
+- **AI Studio:** Shows the error message and execution status. Example: `Remote resource 'onboard-client' failed: Email delivery failed: invalid address`
+- **CLI (`elevasis-sdk execution <resourceId> <id>`):** Shows full execution detail including the error message. The `--json` flag includes an `error` field in structured output.
+- **Error message source:** The error string comes directly from your handler's catch block (`String(err)`). The platform stores this verbatim and displays it as-is. Write descriptive error messages in your handlers -- they surface directly to users.
+
+### What Causes a Failed Execution
+
+- **Unhandled exception in your handler:** The worker reports `status: 'failed'` with the error message.
+- **Memory limit exceeded (256MB):** The worker crashes with an out-of-memory error. The platform catches this; other tenants are unaffected.
+- **Timeout exceeded:** The platform terminates the worker and marks the execution failed with a timeout reason.
+- **Cancellation:** Execution is marked cancelled.
+
+---
+
+## Observability
+
+### Logging
+
+You produce logs using standard `console` methods -- no special logger object is needed:
+
+- **Console interception:** The SDK worker runtime intercepts `console.log`, `console.warn`, and `console.error` during handler execution and captures them as structured `{ level, message }` entries.
+- **Level mapping:** `console.log` maps to `info`, `console.warn` maps to `warn`, `console.error` maps to `error`.
+- **No changes required:** Any code that already uses `console.log` automatically has its output captured. Existing code works without modification.
+
+### Log Transport
+
+Logs are delivered to the platform atomically with the execution result:
+
+- **Bundled delivery:** All logs for an execution are included in the result message when the handler completes. There is no real-time streaming -- logs arrive with the final result.
+- **Crash behavior:** If the worker crashes before completing, logs captured up to the crash point are lost. The platform records only the crash error.
+
+### Log Retention and Display
+
+- **Retention:** 30 days by default (configurable per plan).
+- **Real-time fanout:** After execution completes, logs are stored and fanned out to AI Studio and CLI subscribers. AI Studio shows them in the execution detail view.
+- **CLI access:** Use `elevasis-sdk execution <resourceId> <id>` to view execution details including logs.
+
+---
+
+## Resource Lifecycle
+
+### Status
+
+Every resource on the platform has a status that you control in your definition:
+
+- **`dev`** -- Default for new resources. Visible in AI Studio and executable, but marked with a "Development" badge. Use this during testing and iteration.
+- **`prod`** -- Set `status: 'prod'` in your resource definition before deploying. No badge. This is the live, production-ready state.
+
+### Versioning
+
+v1 versioning is intentionally simple:
+
+- **One active version per resource per org.** Deploying replaces the running version. There is no version history at the resource level; previous deploys are marked stopped.
+- **Immutable per deploy.** A resource definition is frozen at deploy time. Changing code requires a new deploy.
+
+### Deletion
+
+- **Via CLI:** Remove the resource from your `OrganizationResources` export and run `elevasis-sdk deploy`. Resources absent from the new bundle are automatically deregistered from the platform.
+- **Via AI Studio:** The delete button unregisters the resource immediately and marks the deployment stopped.
+- **In-flight executions:** Workers already running complete normally. Deletion affects only new execution attempts.
+- **Data retention:** Execution logs and history for a deleted resource are retained for 30 days, then purged.
+
+---
+
+## Platform Storage
+
+Your deployed bundle is stored in Supabase Storage. On API restart, the platform re-registers all active deployments from the database and re-downloads bundles if needed. This means:
+
+- **No data loss on restart:** Your resources are automatically re-registered after platform restarts.
+- **No action required from you:** The platform handles recovery transparently.
+
+---
+
+## Resource Limits & Quotas
+
+### Per-Worker Limits
+
+Limits enforced per worker thread at runtime:
+
+| Resource         | Value                                                       |
+| ---------------- | ----------------------------------------------------------- |
+| Memory (V8 heap) | 256MB per worker                                            |
+| Disk             | Bundle file only (ephemeral, not persistent across deploys) |
+
+- **Memory:** Enforced by the platform. Exceeding 256MB crashes the worker. The platform catches the error; other tenants are unaffected. If your workflow processes large datasets, consider streaming or batching to stay within the limit.
+- **Disk:** Your bundle is written to disk during deploy and available to the worker at execution time. It is not a persistent write surface -- do not write files to disk from within your handler expecting them to persist.
+
+### Scale Limits
+
+Hard limits to prevent abuse and ensure platform stability:
+
+| Limit                              | Value         |
+| ---------------------------------- | ------------- |
+| Max execution duration (workflows) | 300s (5 min)  |
+| Max execution duration (agents)    | 600s (10 min) |
+| Max log volume                     | 100MB/day     |
+| Max deploy frequency               | 60/day        |
+
+- **Execution duration:** Executions exceeding the timeout are terminated by the platform. The execution is marked failed with a timeout reason.
+- **Log volume:** Total log output across all executions is capped at 100MB per day. Logs beyond this threshold may be truncated.
+- **Deploy frequency:** 60 deploys per day is generous for normal development. This limit prevents accidental deploy loops (for example, a CI pipeline misconfigured to deploy on every commit).
+
+### Networking
+
+- **Outbound:** Unrestricted. Your handlers can call any external API (OpenAI, Twilio, Stripe, etc.) from within the worker.
+- **Inbound:** Workers receive input from the platform coordinator via internal message passing -- they are not exposed to the network directly.
+- **No ports:** Workers communicate with the platform via zero-network-overhead message passing. No port allocation occurs.
+- **Isolation:** Workers have no access to other organizations' data or platform credentials by default. Supabase credentials are not present in the worker environment.
+
+---
+
+## Platform Maintenance
+
+- **Rolling updates:** Platform upgrades re-register all active deployments on startup. No executions are lost.
+- **Node.js updates:** When the server's Node.js version is updated, worker threads pick up the new version on the next execution with no action required from you.
+- **In-flight executions during restart:** Already-running workers complete normally. New executions use the newly reloaded registry after restart.
+- **Advance notice:** 24-hour advance notice is provided for breaking maintenance windows. These are rare and reserved for major infrastructure changes.
+
+---
+
+## v1 Limitations
+
+| Limitation                                      | Reason                                                                                                                                                                                           | Future path                                                                                                             |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| **No nested execution from external resources** | External resources cannot call back to the platform's execution coordinator to trigger other resources as sub-executions.                                                                        | A callback API endpoint that external processes can call to trigger nested executions (requires auth token forwarding). |
+| **No streaming logs**                           | Execution logs are returned in the response body after completion. There is no real-time SSE streaming from within the worker.                                                                   | SSE/WebSocket push from external processes to the platform log system.                                                  |
+| **Static resource priority conflicts**          | If your organization has a static (monorepo) resource with the same ID as a resource in your SDK bundle, the deploy will fail. Static definitions always take priority and cannot be overridden. | Conflict detection is surfaced in the CLI with a clear error message.                                                   |
+
+---
+
+## Organization Provisioning
+
+Organization creation is currently admin-only. If you need a new organization provisioned for SDK access, contact the Elevasis team. Self-serve organization creation and API key generation is on the roadmap.
+
+---
+
+**Last Updated:** 2026-03-06

package/dist/types/worker/adapters/trello.d.ts

@@ -1,14 +0,0 @@
-/**
- * Trello Integration Adapter
- *
- * Typed wrapper over platform.call() for Trello board operations.
- * Uses factory pattern -- credential is bound once at construction time.
- */
-import type { TrelloToolMap } from '../../types/index.js';
-/**
- * Create a typed Trello adapter bound to a specific credential.
- *
- * @param credential - Credential name as configured in the command center
- * @returns Object with 10 typed methods for Trello board operations
- */
-export declare function createTrelloAdapter(credential: string): import("./create-adapter.js").TypedAdapter<TrelloToolMap>;

package/reference/concepts/index.mdx

@@ -1,203 +0,0 @@
----
-title: Concepts Reference
-description: Plain-English explanations of Elevasis SDK concepts -- glossary, workflow analogies, Zod schemas, execution model, platform tools, common errors, and design decisions
-loadWhen: "User asks what is or needs conceptual grounding"
----
-
-This page covers core Elevasis concepts in plain English. It is the teaching vocabulary for the agent when helping you build workflows, and a reference you can return to whenever a term or behavior is unclear.
-
-## Glossary
-
-| Term | Definition |
-| --- | --- |
-| Workflow | A series of named steps that run one after another. Each step does one job. The workflow receives input data and produces output data. |
-| Agent | An autonomous AI resource with access to platform tools. Agents can make decisions and call tools on their own. Run agents with `--async` to avoid HTTP timeout limits on long-running executions. |
-| Resource | Anything you deploy to the platform -- a workflow or an agent. Each resource has a unique ID. |
-| Step | One job inside a workflow. A step receives data, processes it, and passes data to the next step. |
-| Schema | A description of what your data looks like. Schemas validate that input and output data has the right shape -- the right fields with the right types. |
-| Credential | A saved API key or login for an external service (Gmail, Attio, Stripe). Stored securely on the platform, never in your code. |
-| Execution | One run of a resource. Each time someone triggers your workflow, that is one execution. |
-| Deployment | The act of uploading your code to the platform. After deploying, your resources are live and can be executed. |
-| Platform Tool | A pre-built integration the platform provides. You call platform tools from your workflow steps using `platform.call()`. |
-| Organization | Your team or company on the Elevasis platform. Resources, credentials, and executions belong to an organization. |
-| Handler | The function inside a step that does the actual work. It receives input data and returns output data. |
-| Entry Point | The first step that runs when a workflow is executed. Every workflow must have one. |
-| Resource ID | A unique lowercase name for your resource (e.g., `lead-scorer`, `send-welcome-email`). Must be unique within your organization. |
-| Workspace | Your Elevasis project directory. Contains resources (workflows and agents), documentation, and optionally a database connection and custom apps. Created by `elevasis-sdk init`. |
-| Data Table | A table in your database (e.g., Supabase) that stores structured data your workflows can read and write. Defined in `data/schema.ts` as documentation for the agent. |
-
----
-
-## What is a Workflow?
-
-A workflow is a piece of automation that runs on the Elevasis platform. You define the steps in TypeScript; the platform handles running them, logging results, and retrying on failure.
-
-### Two Analogies
-
-**Recipe analogy:** A recipe has ingredients (input), instructions (steps), and a finished dish (output). Each instruction is one step. You follow them in order. If a step fails (you burn the sauce), the recipe stops.
-
-**Assembly line analogy:** Raw material goes in one end (input). Each station does one job (step). The finished product comes out the other end (output).
-
-### When to Use a Workflow
-
-- Automating a repeatable task with defined input and output
-- Chaining multiple actions together (fetch data, process it, send an email)
-- When you need the platform to handle execution, retries, and logging
-
-### When NOT to Use a Workflow
-
-- One-off tasks you will only do once
-- Tasks that need constant human judgment at every step
-
----
-
-## Understanding Schemas (Zod)
-
-### What Schemas Do
-
-Schemas describe and validate the shape of data your workflow expects and produces. If someone sends the wrong data, the platform rejects it before your code runs. This prevents confusing errors deep inside your handler.
-
-The Elevasis SDK uses [Zod](https://zod.dev) for schema definition. Zod is a TypeScript-first validation library. Every workflow has an `inputSchema` and an `outputSchema`.
-
-### Common Zod Types
-
-| Zod Type | What It Means | Example |
-| --- | --- | --- |
-| `z.string()` | Text | `"hello"`, `"user@email.com"` |
-| `z.number()` | A number | `42`, `3.14` |
-| `z.boolean()` | True or false | `true`, `false` |
-| `z.array(z.string())` | A list of text values | `["a", "b", "c"]` |
-| `z.object({ name: z.string() })` | A group of named fields | `{ "name": "Jane" }` |
-| `z.string().optional()` | Text that might be missing | `"hello"` or not provided |
-| `z.enum(['a', 'b', 'c'])` | One of a specific set of values | `"a"` |
-| `z.string().email()` | Text that must be a valid email | `"user@example.com"` |
-
-### Why `z.infer` Exists
-
-`z.infer` creates a TypeScript type from a schema so the type system can check your code. You define the schema once and get both runtime validation and compile-time checking. Without it, you would have to define the same shape twice -- once as a Zod schema and once as a TypeScript type.
-
-```ts
-const myInput = z.object({ name: z.string(), age: z.number() });
-type MyInput = z.infer<typeof myInput>;
-// MyInput is now: { name: string; age: number }
-```
-
-### Common Schema Mistakes
-
-- Forgetting `.optional()` on fields that might be missing -- the platform will reject valid input that omits those fields
-- Returning data from a handler that does not match the output schema -- causes `outputSchema validation failed`
-- Misspelling field names -- the schema says `companyName`, but the handler returns `company_name`
-
----
-
-## The Execution Model
-
-### What Happens When You Run a Workflow
-
-1. A request arrives at the Elevasis platform (someone runs `elevasis-sdk exec` or a schedule triggers)
-2. The platform creates a temporary server just for this execution
-3. Your code runs on that server
-4. The result is sent back
-5. The temporary server is deleted
-
-### Practical Implications
-
-| What You Might Expect | What Actually Happens | Why |
-| --- | --- | --- |
-| Files I create persist | Files disappear after execution | The server is temporary |
-| I can see logs in real-time | Logs appear after execution completes | No streaming from workers |
-| My code runs on my computer | Your code runs on Elevasis servers | That is what "deploy" means |
-| I can use unlimited memory | 256MB memory limit per execution | Prevents runaway processes |
-| Executions share state | Each execution is independent | No shared memory between runs |
-| I can call external APIs | Yes, outbound network is unrestricted | Workers have internet access |
-
-### What "completed" vs "failed" Means
-
-- **completed** -- Your code ran successfully and returned output
-- **failed** -- Something went wrong: your code threw an error, timed out (300s default), or ran out of memory
-
----
-
-## Platform Tools Overview
-
-Platform tools are pre-built integrations the platform provides. You call them from inside workflow steps using `platform.call()` without managing API keys in your code.
-
-### Tool Categories
-
-| Category | Tools | Example Use |
-| --- | --- | --- |
-| Communication | Gmail, Resend, email | Send transactional emails, notifications |
-| CRM | Attio (11 methods) | Create leads, update records, search contacts |
-| Documents | PDF, Google Sheets, Notion | Generate invoices, read spreadsheets, update pages |
-| AI | LLM (GPT, Gemini, Claude) | Classify text, extract data, generate content |
-| Storage | Dropbox, platform storage | Upload files, create signed URLs |
-| Scheduling | Scheduler | Run workflows on a schedule or after a delay |
-| Approvals | Approval gates | Pause workflow until a human approves |
-| Verification | Mailso | Verify email addresses |
-| E-Signatures | SignatureAPI | Create and manage document envelopes |
-| Marketing | Instantly | Send email campaigns |
-| Payments | Stripe | Create payment links, checkout sessions |
-| Automation | Apify | Run web scraping actors |
-
-### How Credentials Work
-
-1. Create a credential in the Elevasis platform (API key, OAuth token, etc.) via the command center UI
-2. Give it a name (e.g., `my-gmail`, `production-attio`)
-3. In your code, pass that name: `platform.call({ credential: 'my-gmail', ... })`
-4. The platform injects the actual API key at runtime -- it never appears in your code
-
-### What Happens When a Credential Name is Wrong
-
-You will see a `PlatformToolError` with the message "credential not found". Check for typos -- credential names are case-sensitive.
-
----
-
-## Common Errors and Fixes
-
-| Error | What It Means | How to Fix |
-| --- | --- | --- |
-| `ELEVASIS_API_KEY not set` | Your `.env` file is missing the API key | Add `ELEVASIS_API_KEY=sk_...` to `.env` |
-| `Schema validation failed` | The input data does not match your Zod schema | Compare the error's field names to your schema definition. Check types (string vs number) and required vs optional fields. |
-| `Cannot find module '@elevasis/sdk'` | Dependencies are not installed | Run `pnpm install` |
-| `PlatformToolError: credential not found` | The credential name in your code does not match any stored credential | Check spelling and case. Verify the credential name in the command center UI. |
-| `Execution timeout (300s)` | Your workflow took too long | Optimize your handler or break it into smaller steps. Check for infinite loops. |
-| `Cannot find name 'z'` | Missing Zod import | Add `import { z } from 'zod'` at the top of your file |
-| `Type 'X' is not assignable to type 'Y'` | Your handler returns data that does not match the output schema | Compare what your handler returns to what `outputSchema` expects. Field names and types must match exactly. |
-| `outputSchema validation failed` | Handler returned data but it does not match the output schema | Check field names, types, and required fields against your output schema. |
-| `Duplicate resource ID` | Two resources have the same `resourceId` | Each resource needs a unique ID within your organization. Rename one. |
-| `NODE_ENV=development` in .env | SDK is trying to connect to a local API server | Remove `NODE_ENV` from your `.env` file. The SDK connects to the hosted platform by default. |
-
----
-
-## Design Decisions Guide
-
-### Single-Step vs Multi-Step
-
-Use a single step when the workflow does one thing -- validate an email, format a message, call one API.
-
-Use multiple steps when you have distinct phases (fetch data, process it, send a notification) or when you want separate error handling per phase. Each step failure is logged independently, making it easier to identify where something went wrong.
-
-### dev vs production Status
-
-- **dev** -- Resource is visible in the dashboard and can be triggered manually, but will not auto-trigger from schedules or webhooks. Use while building and testing.
-- **production** -- Resource is fully live. All trigger sources work. Use when you are confident it works correctly.
-
-You can switch between them by changing `status` in the workflow config and redeploying.
-
-### When to Use Conditional Routing
-
-Use `StepType.CONDITIONAL` when different inputs should follow different processing paths.
-
-Example: score >= 80 goes to the approve path, score >= 50 goes to the review path, everything else goes to the reject path. Each path can have its own steps and logic.
-
-Always include a `defaultTarget` fallback for inputs that do not match any condition. Without a fallback, an unmatched execution will fail.
-
-### When to Use Platform Tools vs Custom Code
-
-Use platform tools when the integration exists in the tool catalog -- they handle auth, retries, and error normalization for you.
-
-Write custom code (e.g., using `fetch` directly) only when you need a service or API method that is not in the catalog, or when you need fine-grained control over the HTTP request.
-
----
-
-**Last Updated:** 2026-02-26