@elevasis/sdk 0.5.12 → 0.5.13

package/dist/templates.js

@@ -31,26 +31,30 @@ ui/dist/
 
 // src/cli/commands/templates/core/claude.ts
 function claudeSettingsTemplate() {
-  return JSON.stringify({
-    autoCompact: false,
-    statusLine: {
-      type: "command",
-      command: "node .claude/scripts/statusline-command.js"
+  return JSON.stringify(
+    {
+      autoCompact: false,
+      statusLine: {
+        type: "command",
+        command: "node .claude/scripts/statusline-command.js"
+      },
+      hooks: {
+        PreToolUse: [
+          {
+            matcher: "Write|Edit|MultiEdit|Bash",
+            hooks: [
+              {
+                type: "command",
+                command: "node .claude/hooks/enforce-sdk-boundary.mjs"
+              }
+            ]
+          }
+        ]
+      }
     },
-    hooks: {
-      PreToolUse: [
-        {
-          matcher: "Write|Edit|MultiEdit|Bash",
-          hooks: [
-            {
-              type: "command",
-              command: "node .claude/hooks/enforce-sdk-boundary.mjs"
-            }
-          ]
-        }
-      ]
-    }
-  }, null, 2) + "\n";
+    null,
+    2
+  ) + "\n";
 }
 function claudeStatuslineScriptTemplate() {
   return `#!/usr/bin/env node
@@ -313,7 +317,8 @@ When an error occurs:
 - Import from \`@elevasis/sdk-ui\`, never from \`@elevasis/sdk\` or \`@repo/ui\`
 - Dev server runs on port 5100: \`cd ui && pnpm dev\`
 - Set \`VITE_WORKOS_CLIENT_ID\` in \`ui/.env\` before running
-- \`ElevasisProvider\` is pre-configured in \`ui/src/App.tsx\` (oauth mode, redirectUri \`http://localhost:5100/auth-redirect\`, apiUrl \`http://localhost:5170\`)
+- \`ElevasisCoreProvider\` (headless, no Mantine dependency) is pre-configured in \`ui/src/App.tsx\` with \`auth={{ mode: 'oauth', clientId, redirectUri }}\`, \`apiUrl="http://localhost:5170"\`, and \`theme={{ colorScheme: 'dark', preset: 'default' }}\`
+- To use pre-built Mantine components from \`@elevasis/sdk-ui\`, switch to \`ElevasisUIProvider\` and install \`@mantine/core\` and \`@mantine/hooks\`
 - OAuth redirect is handled by the \`AuthRedirect\` component at \`/auth-redirect\` -- it uses \`useAuthContext()\` from \`@elevasis/sdk-ui/auth\` and navigates home once \`user\` is set
 - API must be running on port 5170 for the UI to work (\`pnpm --filter api dev\` from the platform monorepo)` : ""}
 
@@ -1495,7 +1500,6 @@ Your \`ELEVASIS_PLATFORM_KEY\` in \`.env\` determines the organization.
 | --- | --- | --- |
 | \`api-key\` | \`{"apiKey": "sk-..."}\` | Stripe, Resend, Apify, Attio, Instantly |
 | \`webhook-secret\` | \`{"signingSecret": "whsec_..."}\` | Cal.com, Stripe webhooks |
-| \`trello\` | \`{"apiKey": "...", "token": "..."}\` | Trello |
 | \`oauth\` | N/A (browser flow only) | Notion, Google Sheets, Dropbox |
 
 OAuth credentials **cannot** be created via CLI. Redirect the user to the Command Center UI.
@@ -1518,12 +1522,11 @@ elevasis-sdk creds list
 Display the output. Note which are \`oauth\` (not modifiable via CLI).
 
 **\`create\`:** Guided credential creation flow:
-1. Ask credential type (\`api-key\`, \`webhook-secret\`, or \`trello\`). Not \`oauth\`.
+1. Ask credential type (\`api-key\` or \`webhook-secret\`). Not \`oauth\`.
 2. Ask credential name. Validate naming rules before proceeding.
 3. Ask the user to paste the credential value directly in chat.
    - For \`api-key\`: ask for the API key, construct \`{"apiKey": "..."}\`
    - For \`webhook-secret\`: ask for the signing secret, construct \`{"signingSecret": "..."}\`
-   - For \`trello\`: ask for API key AND user token, construct \`{"apiKey": "...", "token": "..."}\`
 4. Pipe to CLI: \`echo '{"apiKey":"..."}' | elevasis-sdk creds create --name {name} --type {type}\`
 5. Confirm success. **NEVER echo the credential value back.**
 

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

@@ -17,7 +17,6 @@ export { createNotionAdapter } from './notion.js';
 export { createResendAdapter } from './resend.js';
 export { createSignatureApiAdapter } from './signature-api.js';
 export { createStripeAdapter } from './stripe.js';
-export { createTrelloAdapter } from './trello.js';
 export { scheduler } from './scheduler.js';
 export { llm } from './llm.js';
 export { storage } from './storage.js';

package/dist/worker/index.js

@@ -2464,7 +2464,6 @@ You have control over session memory. Use memoryOps to manage critical informati
 **IMPORTANT - System-Managed Memory:**
 Do NOT update these keys via memoryOps (managed automatically by tools/actions):
 - notion-pages-cache (managed by Notion tools)
-- trello-boards-cache (managed by Trello tools)
 - knowledge-map-state (managed by navigate-knowledge)
 
 Attempting to update system-managed keys will be rejected. Use tools to update their caches.
@@ -2877,6 +2876,14 @@ var AgentCancellationError = class extends ExecutionError {
     super(message, context);
   }
 };
+var AgentStalledError = class extends ExecutionError {
+  type = "agent_stalled_error";
+  severity = "critical";
+  category = "agent";
+  constructor(message, context) {
+    super(message, context);
+  }
+};
 var AgentMemoryValidationError = class extends ExecutionError {
   type = "agent_memory_validation_error";
   severity = "info";
@@ -3142,10 +3149,8 @@ var MEMORY_DOMAINS = {
     // Notion tools manage page hierarchy
     "github-repo-cache",
     // GitHub tools manage repository structure
-    "slack-channel-cache",
+    "slack-channel-cache"
     // Slack tools manage channel data
-    "trello-boards-cache"
-    // Trello tools manage boards/lists/cards
   ],
   /**
    * Action-owned keys
@@ -3972,9 +3977,7 @@ async function reloadKnowledgeMapTools(knowledgeMap, memory, context) {
 function initializeKnowledgeMap(knowledgeMap) {
   if (!knowledgeMap) return void 0;
   return {
-    nodes: Object.fromEntries(
-      Object.entries(knowledgeMap.nodes).map(([id, node]) => [id, { ...node }])
-    )
+    nodes: Object.fromEntries(Object.entries(knowledgeMap.nodes).map(([id, node]) => [id, { ...node }]))
   };
 }
 var Agent = class {
@@ -4213,13 +4216,20 @@ var Agent = class {
     while (iteration <= maxIterations) {
       if (context.signal?.aborted) {
         if (context.signal.reason === "timeout") {
-          throw new AgentTimeoutError(
-            `Agent execution exceeded timeout (${this.config.constraints?.timeout}ms)`,
-            { timeout: this.config.constraints?.timeout ?? 0, iteration }
-          );
+          throw new AgentTimeoutError(`Agent execution exceeded timeout (${this.config.constraints?.timeout}ms)`, {
+            timeout: this.config.constraints?.timeout ?? 0,
+            iteration
+          });
+        }
+        if (context.signal.reason === "stalled") {
+          throw new AgentStalledError("Execution stalled: no heartbeat received within threshold", { iteration });
         }
         throw new AgentCancellationError("Execution cancelled by user", { iteration });
       }
+      try {
+        await context.onHeartbeat?.();
+      } catch {
+      }
       const result = await this.runIteration(iteration, context);
       if (result.shouldComplete) {
         return;
@@ -4372,14 +4382,11 @@ var Agent = class {
       const finalOutput = this.contract.outputSchema.parse(retryOutput);
       return { output: finalOutput, attempts: 2 };
     } catch (error) {
-      throw new AgentOutputValidationError(
-        "Agent output validation failed after retry",
-        {
-          agentId: this.config.resourceId,
-          attempts: 2,
-          zodError: error instanceof ZodError ? error.format() : error
-        }
-      );
+      throw new AgentOutputValidationError("Agent output validation failed after retry", {
+        agentId: this.config.resourceId,
+        attempts: 2,
+        zodError: error instanceof ZodError ? error.format() : error
+      });
     }
   }
   /**
@@ -4397,12 +4404,17 @@ var Agent = class {
     try {
       this.logger.action(actionType, `${actionType} started`, 0, generationStartTime, generationStartTime, 0);
       const attempt = actionType === "output-generation" ? 1 : 2;
-      const adapter = this.adapterFactory(this.modelConfig, this.executionContext?.aiUsageCollector, "agent-completion", {
-        type: "agent-completion",
-        attempt,
-        sessionId: this.executionContext?.sessionId,
-        turnNumber: this.executionContext?.sessionTurnNumber
-      });
+      const adapter = this.adapterFactory(
+        this.modelConfig,
+        this.executionContext?.aiUsageCollector,
+        "agent-completion",
+        {
+          type: "agent-completion",
+          attempt,
+          sessionId: this.executionContext?.sessionId,
+          turnNumber: this.executionContext?.sessionTurnNumber
+        }
+      );
       const structuredOutput = await callLLMForAgentCompletion(adapter, {
         systemPrompt,
         memoryContext: this.memoryManager.toContext(this.iterationNumber, this.executionContext?.sessionTurnNumber),
@@ -4885,23 +4897,6 @@ function createStripeAdapter(credential) {
   return createAdapter("stripe", METHODS11, credential);
 }
 
-// src/worker/adapters/trello.ts
-var METHODS12 = [
-  "getBoard",
-  "getLists",
-  "getCards",
-  "createCard",
-  "updateCard",
-  "createList",
-  "createChecklist",
-  "addChecklistItem",
-  "updateChecklistItem",
-  "getCardChecklists"
-];
-function createTrelloAdapter(credential) {
-  return createAdapter("trello", METHODS12, credential);
-}
-
 // src/worker/adapters/scheduler.ts
 var scheduler = createAdapter("scheduler", [
   "createSchedule",
@@ -5150,19 +5145,12 @@ function buildWorkerExecutionContext(params) {
   };
 }
 function startWorker(org) {
-  const workflows = new Map(
-    (org.workflows ?? []).map((w) => [w.config.resourceId, w])
-  );
-  const agents = new Map(
-    (org.agents ?? []).map((a) => [a.config.resourceId, a])
-  );
+  const workflows = new Map((org.workflows ?? []).map((w) => [w.config.resourceId, w]));
+  const agents = new Map((org.agents ?? []).map((a) => [a.config.resourceId, a]));
   let localAbortController = new AbortController();
   console.log(`[SDK-WORKER] Worker started with ${workflows.size} workflow(s), ${agents.size} agent(s)`);
   parentPort.on("message", async (msg) => {
     if (msg.type === "manifest") {
-      const workflowList = (org.workflows ?? []).map((w) => w.config.resourceId);
-      const agentList = (org.agents ?? []).map((a) => a.config.resourceId);
-      console.log(`[SDK-WORKER] Manifest requested: workflows=[${workflowList.join(", ")}], agents=[${agentList.join(", ")}]`);
       parentPort.postMessage({
         type: "manifest",
         workflows: (org.workflows ?? []).map((w) => ({
@@ -5244,7 +5232,13 @@ function startWorker(org) {
         } catch (err) {
           const durationMs = Date.now() - startTime;
           console.error(`[SDK-WORKER] Workflow '${resourceId}' failed (${durationMs}ms): ${String(err)}`);
-          parentPort.postMessage({ type: "result", status: "failed", error: String(err), logs: [], metrics: { durationMs } });
+          parentPort.postMessage({
+            type: "result",
+            status: "failed",
+            error: String(err),
+            logs: [],
+            metrics: { durationMs }
+          });
         }
         return;
       }
@@ -5321,4 +5315,4 @@ function startWorker(org) {
   });
 }
 
-export { PlatformToolError, approval, createAdapter, createApifyAdapter, createAttioAdapter, createDropboxAdapter, createGmailAdapter, createGoogleSheetsAdapter, createInstantlyAdapter, createMailsoAdapter, createNotionAdapter, createResendAdapter, createSignatureApiAdapter, createStripeAdapter, createTrelloAdapter, email, execution, lead, llm, notifications, pdf, platform, scheduler, startWorker, storage };
+export { PlatformToolError, approval, createAdapter, createApifyAdapter, createAttioAdapter, createDropboxAdapter, createGmailAdapter, createGoogleSheetsAdapter, createInstantlyAdapter, createMailsoAdapter, createNotionAdapter, createResendAdapter, createSignatureApiAdapter, createStripeAdapter, email, execution, lead, llm, notifications, pdf, platform, scheduler, startWorker, storage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "0.5.12",
+  "version": "0.5.13",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {

package/reference/_navigation.md

@@ -1,6 +1,6 @@
 # SDK Reference Navigation
 
-Auto-generated from reference file frontmatter. 32 files indexed.
+Auto-generated from reference file frontmatter. 28 files indexed.
 
 All paths are relative to `node_modules/@elevasis/sdk/reference/`.
 
@@ -8,58 +8,39 @@ All paths are relative to `node_modules/@elevasis/sdk/reference/`.
 
 | Resource | Location | Description | When to Load |
 | --- | --- | --- | --- |
+| CLI Reference | `cli.mdx` | Full reference for every elevasis-sdk CLI command -- scaffold, validate, deploy, execute, and inspect resources | Running CLI operations |
+| Concepts Reference | `concepts.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 |
+| Getting Started | `getting-started.mdx` | Install the Elevasis SDK, scaffold a project, and run your first deployment | Setting up a new project or onboarding |
 | 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 | Description | When to Load |
-| --- | --- | --- | --- |
-| CLI Reference | `cli/index.mdx` | Full reference for every elevasis-sdk CLI command -- scaffold, validate, deploy, execute, and inspect resources | Running CLI operations |
-
-## Concepts
-
-| 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 |
+| Roadmap | `roadmap.mdx` | Planned SDK features -- error taxonomy, retry semantics, circuit breaker, metrics, alerting, and resource lifecycle extensions | Asking about future features or planned capabilities |
+| Execution Runtime | `runtime.mdx` | How your code runs on the Elevasis platform -- execution lifecycle, concurrency, timeouts, cancellation, error handling, observability, resource limits, and v1 limitations | Debugging execution behavior or understanding the runtime model |
+| Common Errors | `troubleshooting.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 |
 
 ## Deployment
 
 | 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 Center UI | `deployment/command-center-ui.mdx` | Reference for the Elevasis Command Center -- what each page does, when to use it post-deployment, and how SDK concepts map to UI actions | User asks about the Command Center UI, post-deployment workflow, or monitoring deployed resources |
-| 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 |
+| Command Center | `deployment/command-center.mdx` | Post-deployment UI reference -- what each page does, the resource graph model, relationships, validation, and how SDK concepts map to Command Center actions | User asks about the Command Center UI, post-deployment workflow, monitoring, or the resource graph |
 | Deploying Resources | `deployment/index.mdx` | How to deploy your Elevasis SDK resources to the platform using elevasis-sdk deploy, including configuration, validation, and environment setup | Preparing to deploy or debugging deploy failures |
 
-## Developer
-
-| Resource | Location | Description | When to Load |
-| --- | --- | --- | --- |
-| Interaction Guidance | `developer/interaction-guidance.mdx` | Full dimensional adaptation rules per skill axis -- platform navigation, API integration, automation concepts, domain expertise -- with growth tracking protocol | Unsure how to adapt for a skill combination |
-
 ## Framework
 
 | 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 |
+| Development Framework | `framework/index.mdx` | The SDK scaffolds a complete development environment for Claude Code -- project instructions, slash commands, cross-session memory, template versioning, and resource documentation | Understanding the agent framework structure |
+| Interaction Guidance | `framework/interaction-guidance.mdx` | Full dimensional adaptation rules per skill axis -- platform navigation, API integration, automation concepts, domain expertise -- with growth tracking protocol | Unsure how to adapt for a skill combination |
 | 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-sdk init and its purpose in the development workflow | Understanding scaffolded files or project layout |
-
-## Getting-started
-
-| 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 |
+| Tutorial System | `framework/tutorial-system.mdx` | Reference for the SDK tutorial system -- 21-item menu across 4 sections, skill-level adaptation rules, progress tracking format, and per-lesson module contents | (not specified) |
 
 ## Platform-tools
 
 | 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 |
+| Typed Adapters | `platform-tools/adapters.mdx` | Type-safe wrappers over platform.call() for all integrations and platform tools -- Attio, Stripe, Notion, Google Sheets, 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 |
+| Platform Tools | `platform-tools/index.mdx` | Access 70+ tools across integration adapters and platform services from your SDK workflows -- typed adapters, credential security model, and working code examples | Connecting to external services |
 
 ## Resources
 
@@ -69,25 +50,6 @@ All paths are relative to `node_modules/@elevasis/sdk/reference/`.
 | 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 | 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 | 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 | 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 | Description | When to Load |
@@ -99,9 +61,3 @@ All paths are relative to `node_modules/@elevasis/sdk/reference/`.
 | 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 | 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/concepts.mdx

@@ -0,0 +1,203 @@
+---
+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 (Quick Reference)
+
+| Error                                     | How to Fix                                                                      |
+| ----------------------------------------- | ------------------------------------------------------------------------------- |
+| `ELEVASIS_API_KEY not set`                | Add `ELEVASIS_API_KEY=sk_...` to `.env`                                         |
+| `Schema validation failed`                | Compare error field names to your schema. Check types and required vs optional. |
+| `Cannot find module '@elevasis/sdk'`      | Run `pnpm install`                                                              |
+| `PlatformToolError: credential not found` | Check spelling and case in the command center UI                                |
+| `Execution timeout (300s)`                | Optimize handler or break into smaller steps                                    |
+| `Cannot find name 'z'`                    | Add `import { z } from 'zod'`                                                   |
+| `outputSchema validation failed`          | Check field names, types, and required fields against output schema             |
+| `NODE_ENV=development` in .env            | Remove `NODE_ENV` from `.env`                                                   |
+
+For the full error catalog with detailed diagnostic steps, see [Troubleshooting](troubleshooting.mdx).
+
+---
+
+## 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