@elevasis/sdk 0.5.13 → 0.5.15

package/reference/framework/tutorial-system.mdx

@@ -3,11 +3,7 @@ title: Tutorial System
 description: Reference for the SDK tutorial system -- 21-item menu across 4 sections, skill-level adaptation rules, progress tracking format, and per-lesson module contents
 ---
 
-**Implementation:** `packages/sdk/src/cli/commands/templates/core/claude.ts` (`claudeTutorialCommandTemplate()`)
-
-**Template Version:** 27
-
-The tutorial system is emitted to `external/<project>/.claude/commands/tutorial.md` during `elevasis-sdk init` or `elevasis-sdk update`. Users invoke it with `/tutorial` from Claude Code.
+The tutorial system is available via the `/tutorial` slash command in Claude Code. It is scaffolded by `elevasis-sdk init` and updated by `elevasis-sdk update`.
 
 ---
 
@@ -149,7 +145,7 @@ Each lesson: (1) announce title and goal, (2) explain concept per skill level, (
 **Lesson 10 -- Going to Production**
 
 - `automation: none` -- "Draft vs live." Create Recurring schedule in Task Scheduler.
-- `automation: low-code or custom` -- Change `status: dev` -> `production`. Cover `try/catch`, `ExecutionError`, `PlatformToolError`. CLI monitoring: `elevasis-sdk executions`.
+- `automation: low-code or custom` -- Change `status: dev` -> `prod`. Cover `try/catch`, `ExecutionError`, `PlatformToolError`. CLI monitoring: `elevasis-sdk executions`.
 
 ---
 
@@ -157,17 +153,17 @@ Each lesson: (1) announce title and goal, (2) explain concept per skill level, (
 
 Modules are available any time -- no core path prerequisite. After completing a module the full menu table is shown again.
 
-| #   | Module           | Reference Docs                                                   | Build                                                                                                                  | Key Concepts                                                       |
-| --- | ---------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| 11  | `hitl`           | `command-center.mdx` (Command Queue)                             | Approval gate with `approval.requestApproval()`. Full lifecycle: trigger -> Command Queue -> approve/reject -> resume. | `approval` adapter, pending state, Command Queue UI                |
-| 12  | `schedules`      | `command-center.mdx` (Task Scheduler)                            | All three schedule types: Recurring, Relative, Absolute. `scheduler` adapter for in-workflow.                          | Cron syntax, schedule types, Task Scheduler UI                     |
-| 13  | `notifications`  | `adapters.mdx` (notifications, email)                            | Notification + email steps. Alerts on completion.                                                                      | `notifications` singleton, `email` singleton                       |
-| 14  | `integrations`   | `platform-tools/index.mdx` (Credential Security), `adapters.mdx` | Real adapter from `identity.md`. Full end-to-end with OAuth or API key credential.                                     | Adapter pattern, credential scoping, external call error handling  |
-| 15  | `error-handling` | `patterns.mdx` (error handling), `troubleshooting.mdx`           | Workflow demonstrating all three error types. `try/catch`, `context.logger`, recovery.                                 | `ExecutionError`, `PlatformToolError`, `ToolingError`              |
-| 16  | `workflows`      | `patterns.mdx` (store, logging, organization)                    | Refactor with `context.store`, `context.logger`, domain directories. Advanced schema patterns.                         | `context.store`, `context.logger`, schema depth                    |
-| 17  | `composition`    | `command-center.mdx` (Command View), `patterns.mdx`              | Two workflows: first triggers second with `execution.trigger()`. Declare relationship.                                 | `execution.trigger`, relationship declarations, Command View edges |
-| 18  | `llm`            | `adapters.mdx` (llm singleton)                                   | `llm.generate()` with structured output. Model selection and temperature.                                              | `llm` singleton, structured output, temperature                    |
-| 19  | `agents`         | `reference/framework/agent.mdx`                                  | Agent definition with tools. LLM tool calling. Agent vs workflow comparison.                                           | Agent definition, tool registration, execution trace               |
+| #   | Module           | Reference Docs                                                   | Build                                                                                                         | Key Concepts                                                       |
+| --- | ---------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| 11  | `hitl`           | `command-center.mdx` (Command Queue)                             | Approval gate with `approval.create()`. Full lifecycle: trigger -> Command Queue -> approve/reject -> resume. | `approval` adapter, pending state, Command Queue UI                |
+| 12  | `schedules`      | `command-center.mdx` (Task Scheduler)                            | All three schedule types: Recurring, Relative, Absolute. `scheduler` adapter for in-workflow.                 | Cron syntax, schedule types, Task Scheduler UI                     |
+| 13  | `notifications`  | `adapters.mdx` (notifications, email)                            | Notification + email steps. Alerts on completion.                                                             | `notifications` singleton, `email` singleton                       |
+| 14  | `integrations`   | `platform-tools/index.mdx` (Credential Security), `adapters.mdx` | Real adapter from `identity.md`. Full end-to-end with OAuth or API key credential.                            | Adapter pattern, credential scoping, external call error handling  |
+| 15  | `error-handling` | `patterns.mdx` (error handling), `troubleshooting.mdx`           | Workflow demonstrating all three error types. `try/catch`, `context.logger`, recovery.                        | `ExecutionError`, `PlatformToolError`, `ToolingError`              |
+| 16  | `workflows`      | `patterns.mdx` (store, logging, organization)                    | Refactor with `context.store`, `context.logger`, domain directories. Advanced schema patterns.                | `context.store`, `context.logger`, schema depth                    |
+| 17  | `composition`    | `command-center.mdx` (Command View), `patterns.mdx`              | Two workflows: first triggers second with `execution.trigger()`. Declare relationship.                        | `execution.trigger`, relationship declarations, Command View edges |
+| 18  | `llm`            | `adapters.mdx` (llm singleton)                                   | `llm.generate()` with structured output. Model selection and temperature.                                     | `llm` singleton, structured output, temperature                    |
+| 19  | `agents`         | `framework/agent.mdx`                                            | Agent definition with tools. LLM tool calling. Agent vs workflow comparison.                                  | Agent definition, tool registration, execution trace               |
 
 ---
 
@@ -221,33 +217,6 @@ Last Session: YYYY-MM-DD
 - Strong automation background, slow on TypeScript syntax
 ```
 
-**Backward compatibility:** Missing `Completed Modules` section treated as empty. Old files with `Completed MF Lessons` map entries to items 2-4 and 20-21 by title match.
-
----
-
-## Implementation Files
-
-| File                                                            | Role                                                                                                                                                                    |
-| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `packages/sdk/src/cli/commands/templates/core/claude.ts`        | `claudeTutorialCommandTemplate()` -- full tutorial prompt; `claudeMdTemplate()` -- Platform Navigation guidance; `claudeMetaCommandTemplate()` -- onboarding assessment |
-| `packages/sdk/src/cli/commands/templates/core/workspace.ts`     | `TEMPLATE_VERSION = 27`                                                                                                                                                 |
-| `packages/sdk/src/cli/commands/init.ts`                         | `TEMPLATE_CHANGELOG` -- version history (v1-v27)                                                                                                                        |
-| `apps/docs/content/docs/sdk/framework/interaction-guidance.mdx` | Skill dimensions: automation, platformNavigation                                                                                                                        |
-
----
-
-## Template Version History (Recent)
-
-| Version | Change                                                                                                                                                       |
-| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 27      | 4-section menu redesign: INTRODUCTION (1-4), CORE CONCEPTS (5-10), ADVANCED MODULES (11-19), ADVANCED WORKSPACE (20-21); MF1-MF3 moved to front as items 2-4 |
-| 23      | Flat 21-item menu table; module gating removed; error-handling moved to position 12                                                                          |
-| 22      | `/docs` command re-introduced; MF3 covers `/work` and `/docs` together                                                                                       |
-| 20      | `/work` comprehensive rewrite -- list-then-pick, interview-based create, intelligent placement                                                               |
-| 19      | Menu-driven entry; Meta-Framework track (MF1-MF5) with skill-adaptive variants                                                                               |
-| 18      | Skill-adaptive lesson variants; Command Center UI integrated; Platform Navigation dimension                                                                  |
-| 16      | Module system; single `/tutorial` invocation; phase tracking                                                                                                 |
-
 ---
 
 **Last Updated:** 2026-03-05

package/reference/getting-started.mdx

@@ -1,148 +1,152 @@
----
-title: Getting Started
-description: Install the Elevasis SDK, scaffold a project, and run your first deployment
-loadWhen: "Setting up a new project or onboarding"
----
-
-**Prerequisites:** Node.js 20+ and pnpm (`npm install -g pnpm`).
-
-## Create a Project
-
-Scaffold a new project and install dependencies:
-
-```bash
-pnpm dlx @elevasis/sdk init my-project
-cd my-project
-pnpm install
-```
-
-`pnpm dlx` downloads the SDK temporarily to run `elevasis-sdk init`, which scaffolds your project with a working echo workflow, TypeScript config, and Claude Code integration. `pnpm install` then installs the SDK and its dependencies locally -- after that, all `elevasis-sdk` commands work directly via the scripts in `package.json` or `pnpm exec elevasis-sdk <command>`.
-
-The command scaffolds 28 files covering configuration, source, documentation, and Claude Code integration:
-
-```
-my-project/
-├── CLAUDE.md                       # Project instructions for Claude Code
-├── .claude/
-│   ├── settings.json               # autoCompact: false
-│   ├── commands/
-│   │   ├── docs.md                 # Documentation lifecycle
-│   │   ├── meta.md                 # Project lifecycle (init, fix, deploy, health)
-│   │   ├── tutorial.md             # Progressive learning
-│   │   └── work.md                 # Task tracking
-│   ├── skills/
-│   │   └── creds/SKILL.md          # Credential management (auto-triggers)
-│   └── rules/
-│       ├── sdk-patterns.md         # SDK imports, structure, runtime (auto-loaded)
-│       ├── docs-authoring.md       # MDX conventions (auto-loaded)
-│       ├── memory-conventions.md   # Memory system conventions (auto-loaded)
-│       ├── project-map.md          # Project map conventions (auto-loaded)
-│       ├── task-tracking.md        # Task tracking conventions (auto-loaded)
-│       └── workspace-patterns.md   # Project-specific patterns (you add these)
-├── src/
-│   ├── index.ts                    # Registry entry point (aggregates domain barrels)
-│   ├── operations/
-│   │   ├── index.ts                # Domain barrel (exports workflows + agents)
-│   │   └── platform-status.ts     # Platform status workflow (real API example)
-│   ├── example/
-│   │   ├── index.ts                # Domain barrel (exports workflows + agents)
-│   │   └── echo.ts                 # Starter workflow (replace with your own)
-│   └── shared/
-│       └── .gitkeep                # Cross-domain shared utilities
-├── docs/
-│   ├── index.mdx                   # Starter documentation page
-│   └── in-progress/
-│       └── .gitkeep                # Work-in-progress docs directory
-├── elevasis.config.ts              # Config with templateVersion and options
-├── package.json                    # check-types + deploy scripts
-├── tsconfig.json                   # TypeScript config (app-focused)
-├── pnpm-workspace.yaml             # Standalone project workspace
-├── .env                            # API key only
-├── .npmrc                          # auto-install-peers
-└── .gitignore                      # Excludes worker temp file, claude files
-```
-
-The scaffolded `elevasis.config.ts` includes a `templateVersion` field that tracks which template generation your project uses. Leave it as-is -- it is managed automatically by `elevasis-sdk update`:
-
-```ts
-import type { ElevasConfig } from '@elevasis/sdk'
-
-export default {
-  templateVersion: 14,
-} satisfies ElevasConfig
-```
-
-### Set Up Your API Key
-
-Open `.env` and set your API key:
-
-```
-ELEVASIS_API_KEY=sk_your_key_here
-```
-
-The `.env` file is gitignored -- never commit it.
-
-**Note:** Do not add `NODE_ENV` to your `.env`. The SDK treats `undefined` as production by default, which means your project connects to the hosted Elevasis API. Adding `NODE_ENV=development` is the most common setup mistake.
-
-### Guided Setup with Claude Code
-
-After scaffolding, open the project in Claude Code. The agent detects that the project is new and automatically walks you through setup: installing dependencies, configuring `.env`, creating your developer profile in `.claude/memory/`, and optionally running your first deploy. No commands needed -- just answer the questions.
-
-If the automatic setup doesn't trigger, you can start it manually with `/meta init`.
-
----
-
-## First Deployment
-
-Validate your resources and deploy:
-
-```bash
-elevasis-sdk check    # Validate resource definitions
-elevasis-sdk deploy   # Bundle and deploy to the platform
-```
-
-`elevasis-sdk check` runs validation without deploying. Fix any errors it reports before running `elevasis-sdk deploy`.
-
-`elevasis-sdk deploy` bundles your `src/` code and `docs/` documentation into a single deployment transaction. Both ship atomically -- there is no separate upload step for documentation.
-
-After a successful deploy, confirm the resources are live:
-
-```bash
-elevasis-sdk resources       # List deployed resources
-elevasis-sdk deployments     # Show deployment history
-```
-
----
-
-## First Execution
-
-Execute the scaffolded echo workflow to verify end-to-end connectivity:
-
-```bash
-elevasis-sdk exec echo --input '{"message": "hello"}'
-```
-
-View the execution result:
-
-```bash
-elevasis-sdk executions echo    # Execution history
-elevasis-sdk execution echo \<execution-id\>  # Full detail for one execution
-```
-
-Replace `<execution-id>` with the ID returned from the executions list.
-
----
-
-## Next Steps
-
-- **Open in Claude Code** -- Setup runs automatically on first session (installs deps, configures `.env`, creates your developer profile)
-- [Development Framework](framework/index.mdx) -- How Claude Code helps you build
-- [Resources](resources/index.mdx) -- Define workflows and agents
-- [CLI Reference](cli.mdx) -- Full command reference with flags
-- [Deployment](deployment/index.mdx) -- Deployment lifecycle and environment variables
-
-When a new SDK version is released, run `/meta fix` in Claude Code for an interactive upgrade that includes SDK update, drift repair, and documentation verification. Alternatively, run `elevasis-sdk update` from the terminal to update managed files (CLAUDE.md, slash commands, `.gitignore`) without agent interaction. To update the SDK package itself, run `pnpm update @elevasis/sdk`.
-
----
-
-**Last Updated:** 2026-02-27
+---
+title: Getting Started
+description: Install the Elevasis SDK, scaffold a project, and run your first deployment
+loadWhen: "Setting up a new project or onboarding"
+---
+
+**Prerequisites:** Node.js 20+ and pnpm (`npm install -g pnpm`).
+
+## Create a Project
+
+Scaffold a new project and install dependencies:
+
+```bash
+pnpm dlx @elevasis/sdk init my-project
+cd my-project
+pnpm install
+```
+
+`pnpm dlx` downloads the SDK temporarily to run `elevasis-sdk init`, which scaffolds your project with a working echo workflow, TypeScript config, and Claude Code integration. `pnpm install` then installs the SDK and its dependencies locally -- after that, all `elevasis-sdk` commands work directly via the scripts in `package.json` or `pnpm exec elevasis-sdk <command>`.
+
+The command scaffolds 30 files covering configuration, source, documentation, and Claude Code integration:
+
+```
+my-project/
+├── CLAUDE.md                       # Project instructions for Claude Code
+├── .claude/
+│   ├── settings.json               # autoCompact: false
+│   ├── commands/
+│   │   ├── docs.md                 # Documentation lifecycle
+│   │   ├── meta.md                 # Project lifecycle (init, fix, deploy, health)
+│   │   ├── tutorial.md             # Progressive learning
+│   │   └── work.md                 # Task tracking
+│   ├── hooks/
+│   │   └── enforce-sdk-boundary.mjs # Blocks destructive commands (auto-loaded)
+│   ├── scripts/
+│   │   └── statusline-command.js   # Dynamic status line script
+│   ├── skills/
+│   │   └── creds/SKILL.md          # Credential management (auto-triggers)
+│   └── rules/
+│       ├── sdk-patterns.md         # SDK imports, structure, runtime (auto-loaded)
+│       ├── docs-authoring.md       # MDX conventions (auto-loaded)
+│       ├── memory-conventions.md   # Memory system conventions (auto-loaded)
+│       ├── project-map.md          # Project map conventions (auto-loaded)
+│       ├── task-tracking.md        # Task tracking conventions (auto-loaded)
+│       └── workspace-patterns.md   # Project-specific patterns (you add these)
+├── src/
+│   ├── index.ts                    # Registry entry point (aggregates domain barrels)
+│   ├── operations/
+│   │   ├── index.ts                # Domain barrel (exports workflows + agents)
+│   │   └── platform-status.ts     # Platform status workflow (real API example)
+│   ├── example/
+│   │   ├── index.ts                # Domain barrel (exports workflows + agents)
+│   │   └── echo.ts                 # Starter workflow (replace with your own)
+│   └── shared/
+│       └── .gitkeep                # Cross-domain shared utilities
+├── docs/
+│   ├── index.mdx                   # Starter documentation page
+│   └── in-progress/
+│       └── .gitkeep                # Work-in-progress docs directory
+├── elevasis.config.ts              # Config with templateVersion and options
+├── package.json                    # check-types + deploy scripts
+├── tsconfig.json                   # TypeScript config (app-focused)
+├── pnpm-workspace.yaml             # Standalone project workspace
+├── .env                            # API key only
+├── .npmrc                          # auto-install-peers
+└── .gitignore                      # Excludes worker temp file, claude files
+```
+
+The scaffolded `elevasis.config.ts` includes a `templateVersion` field that tracks which template generation your project uses. Leave it as-is -- it is managed automatically by `elevasis-sdk update`:
+
+```ts
+import type { ElevasConfig } from '@elevasis/sdk'
+
+export default {
+  templateVersion: 27,
+} satisfies ElevasConfig
+```
+
+### Set Up Your API Key
+
+Open `.env` and set your API key:
+
+```
+ELEVASIS_PLATFORM_KEY=sk_your_key_here
+```
+
+The `.env` file is gitignored -- never commit it.
+
+**Note:** Do not add `NODE_ENV` to your `.env`. The SDK treats `undefined` as production by default, which means your project connects to the hosted Elevasis API. Adding `NODE_ENV=development` is the most common setup mistake.
+
+### Guided Setup with Claude Code
+
+After scaffolding, open the project in Claude Code. The agent detects that the project is new and automatically walks you through setup: installing dependencies, configuring `.env`, creating your developer profile in `.claude/memory/`, and optionally running your first deploy. No commands needed -- just answer the questions.
+
+If the automatic setup doesn't trigger, you can start it manually with `/meta init`.
+
+---
+
+## First Deployment
+
+Validate your resources and deploy:
+
+```bash
+elevasis-sdk check    # Validate resource definitions
+elevasis-sdk deploy   # Bundle and deploy to the platform
+```
+
+`elevasis-sdk check` runs validation without deploying. Fix any errors it reports before running `elevasis-sdk deploy`.
+
+`elevasis-sdk deploy` bundles your `src/` code and `docs/` documentation into a single deployment transaction. Both ship atomically -- there is no separate upload step for documentation.
+
+After a successful deploy, confirm the resources are live:
+
+```bash
+elevasis-sdk resources       # List deployed resources
+elevasis-sdk deployments     # Show deployment history
+```
+
+---
+
+## First Execution
+
+Execute the scaffolded echo workflow to verify end-to-end connectivity:
+
+```bash
+elevasis-sdk exec echo --input '{"message": "hello"}'
+```
+
+View the execution result:
+
+```bash
+elevasis-sdk executions echo    # Execution history
+elevasis-sdk execution echo \<execution-id\>  # Full detail for one execution
+```
+
+Replace `<execution-id>` with the ID returned from the executions list.
+
+---
+
+## Next Steps
+
+- **Open in Claude Code** -- Setup runs automatically on first session (installs deps, configures `.env`, creates your developer profile)
+- [Development Framework](framework/index.mdx) -- How Claude Code helps you build
+- [Resources](resources/index.mdx) -- Define workflows and agents
+- [CLI Reference](cli.mdx) -- Full command reference with flags
+- [Deployment](deployment/index.mdx) -- Deployment lifecycle and environment variables
+
+When a new SDK version is released, run `/meta fix` in Claude Code for an interactive upgrade that includes SDK update, drift repair, and documentation verification. Alternatively, run `elevasis-sdk update` from the terminal to update managed files (CLAUDE.md, slash commands, `.gitignore`) without agent interaction. To update the SDK package itself, run `pnpm update @elevasis/sdk`.
+
+---
+
+**Last Updated:** 2026-02-27

package/reference/index.mdx

@@ -20,35 +20,49 @@ After `pnpm dlx @elevasis/sdk init`, your project is scaffolded with a working e
 Here is a minimal workflow definition:
 
 ```ts
-import { WorkflowDefinition, OrganizationResources } from '@elevasis/sdk';
+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>;
-type GreetOutput = z.infer<typeof greetOutput>;
 
 const greetWorkflow: WorkflowDefinition = {
-  id: 'greet',
-  name: 'Greet',
-  inputSchema: greetInput,
-  outputSchema: greetOutput,
-  steps: [
-    {
-      id: 'greet-step',
+  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',
-      handler: async (input: GreetInput): Promise<GreetOutput> => {
-        return { message: `Hello, ${input.name}!` };
+      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',
 };
 
-export const resources: OrganizationResources = {
+const org: OrganizationResources = {
   workflows: [greetWorkflow],
 };
+
+export default org;
 ```
 
 ## What You Can Build
@@ -71,7 +85,7 @@ const result = await platform.call({
 });
 ```
 
-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.
+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.