@elevasis/sdk 0.5.12 → 0.5.14

package/reference/index.mdx

@@ -1,114 +1,131 @@
----
-title: Elevasis SDK
-description: Build and deploy workflows, agents, and resources with the Elevasis SDK
-loadWhen: "First session or new to the SDK"
----
-
-`@elevasis/sdk` lets you build workflows, agents, and resources in TypeScript and deploy them to the Elevasis platform with a single command. The developer experience is Vercel-style: write TypeScript, validate locally, deploy -- the platform handles execution, tool access, and observability. You never manage infrastructure. Zod 4.1 is the only peer dependency.
-
-## Quick Start
-
-```bash
-pnpm dlx @elevasis/sdk init my-project
-cd my-project
-pnpm install
-elevasis-sdk deploy
-```
-
-After `pnpm dlx @elevasis/sdk init`, your project is scaffolded with a working echo workflow, config file, TypeScript setup, and a `CLAUDE.md` that gives Claude Code full awareness of the SDK. After `elevasis-sdk deploy`, your resources appear in AI Studio and are available to run immediately.
-
-Here is a minimal workflow definition:
-
-```ts
-import { WorkflowDefinition, OrganizationResources } from '@elevasis/sdk';
-import { z } from 'zod';
-
-const greetInput = z.object({ name: z.string() });
-const greetOutput = z.object({ message: z.string() });
-
-type GreetInput = z.infer<typeof greetInput>;
-type GreetOutput = z.infer<typeof greetOutput>;
-
-const greetWorkflow: WorkflowDefinition = {
-  id: 'greet',
-  name: 'Greet',
-  inputSchema: greetInput,
-  outputSchema: greetOutput,
-  steps: [
-    {
-      id: 'greet-step',
-      name: 'Build greeting',
-      handler: async (input: GreetInput): Promise<GreetOutput> => {
-        return { message: `Hello, ${input.name}!` };
-      },
-      next: null,
-    },
-  ],
-};
-
-export const resources: OrganizationResources = {
-  workflows: [greetWorkflow],
-};
-```
-
-## What You Can Build
-
-- **Workflows** -- Step-based automation with typed inputs and outputs. Steps can be linear, conditional, or branching. Each step is a plain async function. Workflows are the primary resource type and are fully supported.
-- **Agents** -- Autonomous AI resources with access to platform tools. Agents run in the worker runtime with full LLM access and platform tool support. Use `--async` when executing agents to avoid HTTP timeout limits on long-running runs.
-
-## Platform Tools
-
-Inside any workflow step, import `platform` from `@elevasis/sdk/worker` to call platform tools:
-
-```ts
-import { platform } from '@elevasis/sdk/worker';
-
-const result = await platform.call({
-  tool: 'gmail',
-  method: 'send',
-  params: { to: 'user@example.com', subject: 'Hello', body: 'World' },
-  credential: 'my-gmail-credential',
-});
-```
-
-The platform exposes 70+ tools across 13 integration adapters -- Gmail, Stripe, Google Sheets, Notion, and more. Credentials are managed server-side; API keys never cross the execution boundary. LLM calls are also available via `platform.call({ tool: 'llm', ... })` with API keys resolved from platform environment variables.
-
-See [Platform Tools](platform-tools/index.mdx) for the full catalog.
-
-## Known Limitations
-
-- **No streaming logs** -- Execution logs are returned in the response body after completion. Real-time log streaming is not available.
-- **Agent HTTP timeouts** -- Use `elevasis-sdk exec --async` for agent executions. Agents can run for minutes; the synchronous endpoint will time out for long-running runs. The `--async` flag returns an execution ID immediately and polls for the result.
-
-## Documentation
-
-### Getting Started
-
-- [Getting Started](getting-started/index.mdx) - Installation, authentication, first workflow, and project structure
-
-### Core Concepts
-
-- [Resources](resources/index.mdx) - Workflow and agent definition patterns, Zod schemas, step types, and routing
-- [Platform Tools](platform-tools/index.mdx) - Full catalog of 70+ tools, integration adapters, and credential management
-- [Security](security/credentials.mdx) - Three-layer credential model, HTTP tool patterns, and credential management
-
-### Reference
-
-- [Concepts](concepts/index.mdx) - Plain-English concept explanations, glossary, Zod guide, execution model, and common errors
-- [Templates](templates/index.mdx) - 7 workflow templates: web-scraper, data-enrichment, email-sender, lead-scorer, and more
-- [CLI Reference](cli/index.mdx) - All CLI commands: check, deploy, exec, resources, executions, env, and more
-- [Deployment](deployment/index.mdx) - Deploy pipeline, versioning, bundle upload, and registry registration
-- [Runtime](runtime/index.mdx) - Worker execution model, concurrency, timeouts, cancellation, and resource limits
-
-### Framework
-
-- [Development Framework](framework/index.mdx) - How Claude Code helps you build: project structure, agent integration, memory, and documentation
-
-### Developer Tools
-
-- [Documentation](framework/documentation.mdx) - Writing and deploying MDX documentation alongside your resources
-- [Roadmap](roadmap/index.mdx) - Planned features including agent execution, streaming logs, and SDK testing utilities
-
----
-
-**Last Updated:** 2026-02-25
+---
+title: Elevasis SDK
+description: Build and deploy workflows, agents, and resources with the Elevasis SDK
+loadWhen: "First session or new to the SDK"
+---
+
+`@elevasis/sdk` lets you build workflows, agents, and resources in TypeScript and deploy them to the Elevasis platform with a single command. The developer experience is Vercel-style: write TypeScript, validate locally, deploy -- the platform handles execution, tool access, and observability. You never manage infrastructure. Zod 4.1 is the only peer dependency.
+
+## Quick Start
+
+```bash
+pnpm dlx @elevasis/sdk init my-project
+cd my-project
+pnpm install
+elevasis-sdk deploy
+```
+
+After `pnpm dlx @elevasis/sdk init`, your project is scaffolded with a working echo workflow, config file, TypeScript setup, and a `CLAUDE.md` that gives Claude Code full awareness of the SDK. After `elevasis-sdk deploy`, your resources appear in AI Studio and are available to run immediately.
+
+Here is a minimal workflow definition:
+
+```ts
+import type { WorkflowDefinition, OrganizationResources } from '@elevasis/sdk';
+import { z } from 'zod';
+
+const greetInput = z.object({ name: z.string() });
+const greetOutput = z.object({ message: z.string() });
+
+type GreetInput = z.infer<typeof greetInput>;
+
+const greetWorkflow: WorkflowDefinition = {
+  config: {
+    resourceId: 'greet',
+    name: 'Greet',
+    type: 'workflow',
+    description: 'Returns a greeting for the given name',
+    version: '1.0.0',
+    status: 'dev',
+  },
+  contract: {
+    inputSchema: greetInput,
+    outputSchema: greetOutput,
+  },
+  steps: {
+    greet: {
+      id: 'greet',
+      name: 'Build greeting',
+      description: 'Returns a greeting message',
+      handler: async (input) => {
+        const { name } = input as GreetInput;
+        return { message: `Hello, ${name}!` };
+      },
+      inputSchema: greetInput,
+      outputSchema: greetOutput,
+      next: null,
+    },
+  },
+  entryPoint: 'greet',
+};
+
+const org: OrganizationResources = {
+  workflows: [greetWorkflow],
+};
+
+export default org;
+```
+
+## What You Can Build
+
+- **Workflows** -- Step-based automation with typed inputs and outputs. Steps can be linear, conditional, or branching. Each step is a plain async function. Workflows are the primary resource type and are fully supported.
+- **Agents** -- Autonomous AI resources with access to platform tools. Agents run in the worker runtime with full LLM access and platform tool support. Use `--async` when executing agents to avoid HTTP timeout limits on long-running runs.
+
+## Platform Tools
+
+Inside any workflow step, import `platform` from `@elevasis/sdk/worker` to call platform tools:
+
+```ts
+import { platform } from '@elevasis/sdk/worker';
+
+const result = await platform.call({
+  tool: 'gmail',
+  method: 'send',
+  params: { to: 'user@example.com', subject: 'Hello', body: 'World' },
+  credential: 'my-gmail-credential',
+});
+```
+
+The platform exposes 70+ tools across 12 integration adapters -- Gmail, Stripe, Google Sheets, Notion, and more. Credentials are managed server-side; API keys never cross the execution boundary. LLM calls are also available via `platform.call({ tool: 'llm', ... })` with API keys resolved from platform environment variables.
+
+See [Platform Tools](platform-tools/index.mdx) for the full catalog.
+
+## Known Limitations
+
+- **No streaming logs** -- Execution logs are returned in the response body after completion. Real-time log streaming is not available.
+- **Agent HTTP timeouts** -- Use `elevasis-sdk exec --async` for agent executions. Agents can run for minutes; the synchronous endpoint will time out for long-running runs. The `--async` flag returns an execution ID immediately and polls for the result.
+
+## Documentation
+
+### Getting Started
+
+- [Getting Started](getting-started.mdx) - Installation, authentication, first workflow, and project structure
+
+### Core Concepts
+
+- [Resources](resources/index.mdx) - Workflow and agent definition patterns, Zod schemas, step types, and routing
+- [Platform Tools](platform-tools/index.mdx) - Full catalog of 70+ tools, integration adapters, and credential management
+- [Platform Tools](platform-tools/index.mdx#credential-security) - Three-layer credential model, HTTP tool patterns, and credential management
+
+### Reference
+
+- [Concepts](concepts.mdx) - Plain-English concept explanations, glossary, Zod guide, execution model, and common errors
+- [Templates](templates/index.mdx) - 7 workflow templates: web-scraper, data-enrichment, email-sender, lead-scorer, and more
+- [CLI Reference](cli.mdx) - All CLI commands: check, deploy, exec, resources, executions, env, and more
+- [Deployment](deployment/index.mdx) - Deploy pipeline, versioning, bundle upload, and registry registration
+- [Runtime](runtime.mdx) - Worker execution model, concurrency, timeouts, cancellation, resource limits, and v1 limitations
+
+### Framework
+
+- [Development Framework](framework/index.mdx) - How Claude Code helps you build: project structure, agent integration, memory, and documentation
+- [Interaction Guidance](framework/interaction-guidance.mdx) - Skill dimension adaptation rules for platform navigation, API integration, and automation concepts
+- [Tutorial System](framework/tutorial-system.mdx) - 21-item tutorial menu, skill-adaptive lesson variants, progress tracking, and module contents
+
+### More
+
+- [Documentation](framework/index.mdx#resource-documentation) - Writing and deploying MDX documentation alongside your resources
+- [Troubleshooting](troubleshooting.mdx) - Static error catalog for CLI, deployment, schema, and runtime failures
+- [Roadmap](roadmap.mdx) - Planned features including agent execution, streaming logs, and SDK testing utilities
+
+---
+
+**Last Updated:** 2026-02-25