@elevasis/sdk 0.4.5 → 0.4.6

package/dist/cli.cjs

@@ -43808,7 +43808,7 @@ async function apiDelete(endpoint, apiUrl = resolveApiUrl()) {
 }
 
 // src/cli/version.ts
-var SDK_VERSION = "0.4.5";
+var SDK_VERSION = "0.4.6";
 
 // src/cli/commands/deploy.ts
 var import_meta2 = {};
@@ -44476,7 +44476,8 @@ var SCAFFOLD_FILES = [
   ".claude/commands/resource.md",
   ".claude/commands/deploy.md",
   ".claude/commands/inspect.md",
-  ".claude/commands/env.md"
+  ".claude/commands/env.md",
+  ".claude/commands/sdk-docs.md"
 ];
 function registerInitCommand(program3) {
   program3.command("init [directory]").description("Scaffold a new Elevasis project\n  Example: elevasis init my-project").option("--force", "Overwrite existing files").action(wrapAction("init", async (directory, options2) => {
@@ -44520,7 +44521,8 @@ function registerInitCommand(program3) {
       ".claude/commands/resource.md": claudeResourceCommandTemplate(),
       ".claude/commands/deploy.md": claudeDeployCommandTemplate(),
       ".claude/commands/inspect.md": claudeInspectCommandTemplate(),
-      ".claude/commands/env.md": claudeEnvCommandTemplate()
+      ".claude/commands/env.md": claudeEnvCommandTemplate(),
+      ".claude/commands/sdk-docs.md": claudeSdkDocsCommandTemplate()
     };
     for (const [filePath, content] of Object.entries(files)) {
       await (0, import_promises2.writeFile)((0, import_path3.resolve)(targetDir, filePath), content, "utf-8");
@@ -44881,6 +44883,22 @@ at deploy time via \`z.toJSONSchema()\`.
 - Documentation goes in \`docs/\` as \`.mdx\` files
 - \`dist/\` is generated by deploy -- never commit it
 - \`resourceId\` must be lowercase with hyphens, unique per organization
+
+## SDK Reference Documentation
+
+Complete SDK documentation is bundled with the package at:
+
+  node_modules/@elevasis/sdk/reference/
+
+Read \`node_modules/@elevasis/sdk/reference/_index.md\` for a manifest of all
+available pages. Key references:
+
+- \`reference/platform-tools/index.mdx\` -- Complete platform.call() tool catalog
+- \`reference/resources/types.mdx\` -- All SDK types and exports
+- \`reference/runtime/limits.mdx\` -- Resource limits and quotas
+- \`reference/cli/index.mdx\` -- Full CLI command reference
+
+Use the \`/sdk-docs\` command to browse reference documentation.
 `;
 }
 function claudeDocsCommandTemplate() {
@@ -45030,6 +45048,41 @@ Read .env for local environment variables.
 5. Remind user to redeploy after syncing
 `;
 }
+function claudeSdkDocsCommandTemplate() {
+  return `# /sdk-docs command
+
+You are an SDK documentation browser for this Elevasis SDK project.
+
+## Context
+
+Reference documentation is bundled with the SDK package at:
+
+  node_modules/@elevasis/sdk/reference/
+
+Read \`node_modules/@elevasis/sdk/reference/_index.md\` for the full manifest
+of available pages with titles and descriptions.
+
+## Operations
+
+**No arguments (default):** Read and display the manifest at
+\`node_modules/@elevasis/sdk/reference/_index.md\`. Present the available
+documentation pages as a browsable list.
+
+**\`<topic>\`:** Find and read the most relevant page(s) for the given topic.
+Match against the manifest entries. Examples:
+
+- \`/sdk-docs platform-tools\` -- Read \`reference/platform-tools/index.mdx\`
+- \`/sdk-docs types\` -- Read \`reference/resources/types.mdx\`
+- \`/sdk-docs limits\` -- Read \`reference/runtime/limits.mdx\`
+- \`/sdk-docs cli\` -- Read \`reference/cli/index.mdx\`
+- \`/sdk-docs deployment\` -- Read \`reference/deployment/index.mdx\`
+
+If the topic is ambiguous, show matching pages and ask which to read.
+
+**\`all\`:** Read and summarize all reference pages. Provide a concise overview
+of the full SDK documentation.
+`;
+}
 function starterTemplate() {
   return `import type { WorkflowDefinition, OrganizationResources } from '@elevasis/sdk'
 import { z } from 'zod'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "SDK for building Elevasis organization resources",
   "comment:bin": "IMPORTANT: This package shares the 'elevasis' binary name with @repo/cli. They never conflict because @elevasis/sdk must NEVER be added as a dependency of any workspace package (apps/*, packages/*, organizations/*). Workspace projects use @repo/cli for the 'elevasis' binary. External developers (outside the workspace) get this SDK's binary via npm install.",
   "type": "module",
@@ -24,13 +24,9 @@
     "dist/worker/index.js",
     "dist/types/worker/index.d.ts",
     "dist/types/worker/platform.d.ts",
-    "dist/cli.cjs"
+    "dist/cli.cjs",
+    "reference/"
   ],
-  "scripts": {
-    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.core-dts.json && tsc -p tsconfig.build.json && tsup && rollup -c rollup.dts.config.mjs && esbuild src/cli/index.ts --bundle --platform=node --outfile=dist/cli.cjs --format=cjs --external:esbuild --external:jiti --banner:js=\"#!/usr/bin/env node\"",
-    "check-types": "tsc --noEmit",
-    "test:bundle": "pnpm build && vitest run --config vitest.bundle.config.ts"
-  },
   "dependencies": {
     "esbuild": "^0.25.0",
     "jiti": "^2.0.0"
@@ -39,8 +35,6 @@
     "zod": "^4.1.0"
   },
   "devDependencies": {
-    "@repo/core": "workspace:*",
-    "@repo/typescript-config": "workspace:*",
     "@types/node": "^22.0.0",
     "chalk": "^5.3.0",
     "commander": "^11.0.0",
@@ -51,6 +45,13 @@
     "rollup-plugin-dts": "^6.3.0",
     "tsup": "^8.0.0",
     "typescript": "5.9.2",
-    "zod": "^4.1.0"
+    "zod": "^4.1.0",
+    "@repo/core": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.core-dts.json && tsc -p tsconfig.build.json && tsup && rollup -c rollup.dts.config.mjs && esbuild src/cli/index.ts --bundle --platform=node --outfile=dist/cli.cjs --format=cjs --external:esbuild --external:jiti --banner:js=\"#!/usr/bin/env node\" && node scripts/copy-reference-docs.mjs",
+    "check-types": "tsc --noEmit",
+    "test:bundle": "pnpm build && vitest run --config vitest.bundle.config.ts"
   }
-}
+}

package/reference/_index.md

@@ -0,0 +1,53 @@
+# SDK Reference Documentation
+
+15 pages bundled from the Elevasis documentation site.
+
+Browse these files for complete SDK reference including platform tools catalog,
+resource types, runtime limits, deployment details, and CLI commands.
+
+## Pages
+
+- **CLI Reference** -- `cli/index.mdx`
+  Full reference for every elevasis CLI command -- scaffold, validate, deploy, execute, and inspect resources
+
+- **Execution API** -- `deployment/api.mdx`
+  REST endpoints for executing resources, querying execution history, and managing deployments via the Elevasis external API
+
+- **Deploying Resources** -- `deployment/index.mdx`
+  How to deploy your Elevasis SDK resources to the platform using elevasis deploy, including configuration, validation, and environment setup
+
+- **Resource Documentation** -- `documentation/index.mdx`
+  Write and deploy MDX documentation alongside your Elevasis resources
+
+- **Getting Started** -- `getting-started/index.mdx`
+  Install the Elevasis SDK, scaffold a project, and run your first deployment
+
+- **Project Structure** -- `getting-started/project-structure.mdx`
+  Each file scaffolded by elevasis init and its purpose in the development workflow
+
+- **Elevasis SDK** -- `index.mdx`
+  Build and deploy workflows, agents, and resources with the Elevasis SDK
+
+- **Integration Examples** -- `platform-tools/examples.mdx`
+  Common platform.call() patterns for email, CRM, PDF, LLM inference, resource triggering, and storage
+
+- **Platform Tools** -- `platform-tools/index.mdx`
+  Access 70+ integration adapters and platform services from your SDK workflows via platform.call()
+
+- **Writing Resources** -- `resources/index.mdx`
+  Guide to creating workflows and agents using WorkflowDefinition, AgentDefinition, and OrganizationResources with the Elevasis SDK
+
+- **Common Patterns** -- `resources/patterns.mdx`
+  Common resource patterns for Elevasis SDK developers -- sequential steps, conditional branching, platform tools, error handling, and resource status management
+
+- **SDK Types** -- `resources/types.mdx`
+  Complete type reference for @elevasis/sdk -- package exports, re-exported platform types, ElevasConfig interface, StepHandler context, and runtime values
+
+- **Roadmap** -- `roadmap/index.mdx`
+  Planned SDK features -- error taxonomy, retry semantics, circuit breaker, metrics, alerting, and resource lifecycle extensions
+
+- **Execution Runtime** -- `runtime/index.mdx`
+  How your code runs on the Elevasis platform -- execution lifecycle, concurrency, timeouts, cancellation, error handling, and observability
+
+- **Resource Limits & Quotas** -- `runtime/limits.mdx`
+  Memory limits, execution timeouts, scale quotas, networking constraints, and v1 platform limitations for SDK resources

package/reference/cli/index.mdx

@@ -0,0 +1,496 @@
+---
+title: CLI Reference
+description: Full reference for every elevasis CLI command -- scaffold, validate, deploy, execute, and inspect resources
+---
+
+The `elevasis` CLI is the primary interface for working with your Elevasis SDK project. Install it as part of `@elevasis/sdk` and use it to scaffold projects, validate resource definitions, deploy to the platform, and inspect execution history.
+
+**Installation:**
+
+```bash
+npm install @elevasis/sdk
+```
+
+After installation, the `elevasis` binary is available in your project's `node_modules/.bin/`. Most commands require `ELEVASIS_API_KEY` to be set in your environment or a `.env` file.
+
+---
+
+## elevasis init
+
+Scaffold a new Elevasis SDK project in the specified directory.
+
+**Synopsis:**
+
+```
+elevasis init [directory]
+```
+
+**Behavior:**
+
+- Derives the organization slug from the directory name
+- Checks for file conflicts before writing any files
+- Scaffolds project structure including `src/index.ts`, `elevasis.config.ts`, `package.json`, `tsconfig.json`, and a `CLAUDE.md` with CLI reference and SDK patterns
+- Non-interactive: all values are derived automatically
+
+**Flags:**
+
+| Flag | Description |
+| ---- | ----------- |
+| (none) | Uses current directory if no argument is provided |
+
+**Example:**
+
+```bash
+elevasis init my-project
+```
+
+```
+  Scaffolding my-project/...
+
+  Created 18 files.
+
+  Next steps:
+    cd my-project
+    npm install
+    elevasis check
+```
+
+---
+
+## elevasis check
+
+Validate all resource definitions in your project without deploying.
+
+**Synopsis:**
+
+```
+elevasis check
+```
+
+**Behavior:**
+
+- Imports your `src/index.ts` and runs it through `ResourceRegistry` validation
+- Catches the same errors that the platform catches at deploy time:
+  - Duplicate `resourceId` within the organization
+  - Invalid model configuration (temperature and token bounds)
+  - `ExecutionInterface` form fields not matching `inputSchema`
+  - Broken workflow step chains (`next` referencing non-existent steps)
+  - Relationship declarations referencing non-existent resources
+- Exits with code 0 on success, code 1 on validation failure
+
+**Flags:**
+
+| Flag | Description |
+| ---- | ----------- |
+| `--api-url <url>` | Override the API base URL |
+
+**Example output (success):**
+
+```
+$ elevasis check
+
+  Validating...    done (4 resources, 0 errors)
+```
+
+**Example output (failure):**
+
+```
+$ elevasis check
+
+  Validating...
+    ERROR  Duplicate resource ID 'onboard-client' in organization 'Acme Corp'
+    ERROR  Workflow step 'send-email' references non-existent next step 'notify'
+
+  2 errors.
+```
+
+---
+
+## elevasis deploy
+
+Bundle your project with esbuild and deploy it to the Elevasis platform.
+
+**Synopsis:**
+
+```
+elevasis deploy
+```
+
+**Behavior:**
+
+- Authenticates with `ELEVASIS_API_KEY` and resolves your organization name
+- Runs the same `ResourceRegistry` validation as `elevasis check`
+- Bundles your `src/index.ts` and all dependencies into a single self-contained JS file (`dist/bundle.js`, approximately 50-200 KB)
+- Uploads the bundle plus resource metadata to `POST /api/external/deploy`
+- Streams deploy status and prints the result
+- Resources are live immediately after a successful deploy
+
+**Flags:**
+
+| Flag | Description |
+| ---- | ----------- |
+| `--api-url <url>` | Override the API base URL (default: production) |
+
+**Environment variables:**
+
+| Variable | Description |
+| -------- | ----------- |
+| `ELEVASIS_API_KEY` | Required. Your `sk_...` API key |
+| `ELEVASIS_API_URL` | Optional. Override the API base URL |
+
+**Example output (success):**
+
+```
+$ elevasis deploy
+
+  Authenticating...          done (acme-corp)
+  Validating...              done (4 resources, 0 errors)
+  Bundling...                done (142 KB)
+  Uploading...               done
+
+  Deployed! 4 resources live.
+  Deployment: deploy_abc123
+```
+
+**Example output (validation failure):**
+
+```
+$ elevasis deploy
+
+  Authenticating...          done (acme-corp)
+  Validating...
+    ERROR  Duplicate resource ID 'onboard-client' in organization 'Acme Corp'
+    ERROR  Workflow step 'send-email' references non-existent next step 'notify'
+
+  2 errors. Deploy aborted.
+```
+
+---
+
+## elevasis exec
+
+Execute a deployed resource by ID.
+
+**Synopsis:**
+
+```
+elevasis exec <resource> --input '{...}'
+```
+
+**Behavior:**
+
+- Executes the named resource synchronously by default and streams the result
+- Use `--async` to return an `executionId` immediately and poll for completion
+- `--input` accepts a JSON string matching the resource's `inputSchema`
+- Organization is derived from your API key -- no org prefix needed
+
+**Flags:**
+
+| Flag | Description |
+| ---- | ----------- |
+| `--input <json>` | JSON input matching the resource's input schema |
+| `--async` | Execute asynchronously, return execution ID immediately |
+| `--json` | Output raw JSON instead of formatted display |
+| `--api-url <url>` | Override the API base URL |
+
+**Example:**
+
+```bash
+elevasis exec onboard-client --input '{"clientName": "Jane", "email": "jane@example.com"}'
+```
+
+```
+  Executing onboard-client...
+
+  Status:   completed
+  Duration: 1.4s
+
+  Output:
+  {
+    "success": true,
+    "clientId": "client_1708521600000",
+    "welcomeEmailSent": true
+  }
+```
+
+**Async example:**
+
+```bash
+elevasis exec onboard-client --input '{"clientName": "Jane"}' --async
+```
+
+```
+  Execution started: exec_550e8400
+  Poll with: elevasis execution onboard-client exec_550e8400
+```
+
+---
+
+## elevasis resources
+
+List all deployed resources for your organization.
+
+**Synopsis:**
+
+```
+elevasis resources
+```
+
+**Behavior:**
+
+- Lists all resources registered to your organization on the platform
+- In production, only `status: 'prod'` resources are shown
+- Displays resource ID, type, name, and status
+
+**Flags:**
+
+| Flag | Description |
+| ---- | ----------- |
+| `--json` | Output raw JSON |
+| `--api-url <url>` | Override the API base URL |
+
+**Example output:**
+
+```
+$ elevasis resources
+
+  onboard-client    workflow   Onboard Client       prod
+  send-report       workflow   Send Weekly Report   prod
+  email-assistant   agent      Email Assistant      prod
+  support-bot       agent      Support Bot          dev
+```
+
+---
+
+## elevasis executions
+
+View execution history for a resource.
+
+**Synopsis:**
+
+```
+elevasis executions [resource]
+```
+
+**Behavior:**
+
+- Lists recent executions for the specified resource
+- If `resource` is omitted, lists executions across all resources
+- Supports filtering by status and limiting result count
+
+**Flags:**
+
+| Flag | Description |
+| ---- | ----------- |
+| `--limit <n>` | Maximum number of executions to return (default: 20) |
+| `--status <status>` | Filter by status: `running`, `completed`, `failed`, `cancelled` |
+| `--json` | Output raw JSON |
+| `--api-url <url>` | Override the API base URL |
+
+**Example:**
+
+```bash
+elevasis executions onboard-client --limit 5
+```
+
+```
+  exec_abc001   completed   2026-02-25 14:32:01   1.2s
+  exec_abc002   completed   2026-02-25 13:18:44   0.9s
+  exec_abc003   failed      2026-02-25 12:05:22   0.3s
+  exec_abc004   completed   2026-02-24 17:51:09   1.8s
+  exec_abc005   completed   2026-02-24 16:30:55   1.1s
+```
+
+---
+
+## elevasis execution
+
+View full detail for a single execution.
+
+**Synopsis:**
+
+```
+elevasis execution <resource> <id>
+```
+
+**Behavior:**
+
+- Shows the complete execution record: input, output, logs, duration, and error (if any)
+- Use `--json` to get the raw JSON response for programmatic use
+
+**Flags:**
+
+| Flag | Description |
+| ---- | ----------- |
+| `--json` | Output raw JSON |
+| `--api-url <url>` | Override the API base URL |
+
+**Example:**
+
+```bash
+elevasis execution onboard-client exec_abc001
+```
+
+```
+  Resource:   onboard-client
+  Status:     completed
+  Started:    2026-02-25 14:32:01
+  Duration:   1.2s
+
+  Input:
+  {
+    "clientName": "Jane",
+    "email": "jane@example.com"
+  }
+
+  Output:
+  {
+    "success": true,
+    "clientId": "client_1708521600000",
+    "welcomeEmailSent": true
+  }
+
+  Logs:
+  [14:32:01.123]  Starting onboard-client workflow
+  [14:32:01.456]  Created client record
+  [14:32:01.891]  Welcome email sent to jane@example.com
+```
+
+---
+
+## elevasis deployments
+
+List all deployments for your organization.
+
+**Synopsis:**
+
+```
+elevasis deployments
+```
+
+**Behavior:**
+
+- Shows deployment history with status, timestamp, and resource count
+- Active deployment is marked; previous deployments show as `stopped`
+
+**Flags:**
+
+| Flag | Description |
+| ---- | ----------- |
+| `--json` | Output raw JSON |
+| `--api-url <url>` | Override the API base URL |
+
+**Example output:**
+
+```
+$ elevasis deployments
+
+  deploy_abc123   active    2026-02-25 14:00:00   4 resources
+  deploy_abc122   stopped   2026-02-24 09:30:00   3 resources
+  deploy_abc121   stopped   2026-02-23 11:15:00   3 resources
+```
+
+---
+
+## elevasis describe
+
+Show the definition of a deployed resource.
+
+**Synopsis:**
+
+```
+elevasis describe <resource>
+```
+
+**Behavior:**
+
+- Displays resource metadata: name, type, description, status, and domains
+- Shows the full `inputSchema` and `outputSchema` as JSON
+- Type is color-coded: yellow for workflows, magenta for agents
+
+**Flags:**
+
+| Flag | Description |
+| ---- | ----------- |
+| `--json` | Output raw JSON response |
+| `--api-url <url>` | Override the API base URL |
+
+**Example:**
+
+```bash
+elevasis describe onboard-client
+```
+
+```
+  onboard-client  [workflow]
+
+  Name:         Onboard Client
+  Description:  Creates a client record and sends a welcome email
+  Status:       prod
+  Domains:      crm, email
+
+  Input Schema:
+  {
+    "type": "object",
+    "properties": {
+      "clientName": { "type": "string" },
+      "email": { "type": "string", "format": "email" }
+    },
+    "required": ["clientName", "email"]
+  }
+```
+
+---
+
+## elevasis env
+
+Manage environment variables for your project.
+
+**Synopsis:**
+
+```
+elevasis env list
+elevasis env set <key> <value>
+elevasis env remove <key>
+```
+
+**Behavior:**
+
+- `list` -- display all environment variables configured for the project
+- `set` -- add or update an environment variable
+- `remove` -- delete an environment variable
+
+**Flags:**
+
+| Flag | Description |
+| ---- | ----------- |
+| `--api-url <url>` | Override the API base URL |
+
+**Examples:**
+
+```bash
+elevasis env list
+elevasis env set OPENAI_API_KEY sk-proj-***
+elevasis env remove OPENAI_API_KEY
+```
+
+---
+
+## Global Flags
+
+These flags are accepted by all commands:
+
+| Flag | Description |
+| ---- | ----------- |
+| `--api-url <url>` | Override the API base URL. Priority: flag > `ELEVASIS_API_URL` env var > `NODE_ENV`-based default |
+| `--json` | Output raw JSON (available on most commands) |
+
+**API base URL resolution:**
+
+- Production (default): `https://api.elevasis.io`
+- Development (`NODE_ENV=development`): `http://localhost:<port>`
+- Override: set `ELEVASIS_API_URL` or pass `--api-url`
+
+---
+
+**Last Updated:** 2026-02-25