@elevasis/sdk 0.5.12 → 0.5.14

package/reference/framework/tutorial-system.mdx

@@ -0,0 +1,222 @@
+---
+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
+---
+
+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`.
+
+---
+
+## Menu System
+
+`/tutorial` always shows the full 21-item menu table on invocation. All items are visible at once with progress indicators. No track gating -- any item is available at any time.
+
+```
+Elevasis Tutorial
+==================
+
+INTRODUCTION                                       0/4
+  1  Welcome & Orientation                         [ ]
+  2  How This Workspace Works                      [ ]
+  3  The /meta Command                             [ ]
+  4  /work and /docs                               [ ]
+
+CORE CONCEPTS                                      0/6
+  5  Your First Custom Workflow                    [ ]
+  6  Understanding Data (Schemas)                  [ ]
+  7  Using Platform Tools                          [ ]
+  8  Multi-Step Workflows                          [ ]
+  9  Decision Points                               [ ]
+ 10  Going to Production                           [ ]
+
+ADVANCED MODULES                                   0/9
+ 11  Human-in-the-Loop                             [ ]
+ 12  Task Scheduling                               [ ]
+ 13  Notification System                           [ ]
+ 14  Real-World Integrations                       [ ]
+ 15  Error Handling Mastery                        [ ]
+ 16  Advanced Workflows                            [ ]
+ 17  Resource Composition                          [ ]
+ 18  LLM Integration                               [ ]
+ 19  AI Agents                                     [ ]
+
+ADVANCED WORKSPACE                                 0/2
+ 20  Rules, Memory, and Customization              [ ]
+ 21  Template Lifecycle                            [ ]
+
+Pick a number to start.
+```
+
+**Progress indicators:** `[ ]` not started, `[>]` in progress, `[x] YYYY-MM-DD` complete.
+
+User picks a number to start or resume any item. `"status"` shows the same table.
+
+---
+
+## 4 Sections
+
+- **INTRODUCTION (1-4):** Welcome + workspace orientation (workspace framework, /meta, /work and /docs) -- taught before building
+- **CORE CONCEPTS (5-10):** Orchestration lessons (workflows, schemas, tools, multi-step, conditions, production)
+- **ADVANCED MODULES (11-19):** Hands-on feature modules (hitl, schedules, notifications, integrations, error-handling, workflows, composition, llm, agents)
+- **ADVANCED WORKSPACE (20-21):** Power-user customization (rules/memory, template lifecycle)
+
+---
+
+## Skill-Level Adaptation
+
+Assessed during `/meta init`. Two independent dimensions.
+
+### automation dimension
+
+| Level      | Context Loading                                                                                         | Delivery                                                            | Verification                                                      |
+| ---------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `none`     | Glossary, Workflow overview, Platform Tools Overview only. Skip Zod, Execution Model, Design Decisions. | Agent writes all code. No code shown to user. Analogies throughout. | CLI primary. Agent runs `elevasis-sdk exec` and narrates results. |
+| `low-code` | All concept sections. Zapier/Make mapping. `adapters.mdx` on-demand.                                    | Map to Zapier/Make equivalents. Show code with explanations.        | CLI primary.                                                      |
+| `custom`   | All docs listed per-lesson and per-module.                                                              | Full technical content, code-first.                                 | CLI primary.                                                      |
+
+### platformNavigation dimension
+
+| Level         | Behavior                                                                                                               |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `none`        | Walk through pages step by step with exact navigation paths. Explain each page before asking user to interact with it. |
+| `oriented`    | Reference pages by name; briefly remind purpose on first mention.                                                      |
+| `comfortable` | Reference by name only; focus on advanced filtering and schedule types.                                                |
+
+**General rules (all levels):** Fast users: acknowledge, offer to skip ahead. Level change observed: note in `skills.md` Growth Log. After lesson/module: update progress file.
+
+---
+
+## Progress Logic
+
+```
+1. Read .claude/memory/tutorial-progress.md
+2. Show the full menu table with progress indicators filled in
+3. User picks a number -> start or resume that item directly
+4. After completion: mark done in progress file, show updated menu table
+5. All 21 items complete -> congratulate, suggest docs/ or /work
+```
+
+---
+
+## Introduction: Items 1-4
+
+Items 1-4 orient the user to the platform and workspace before any building.
+
+**Item 1 -- Welcome & Orientation:** Platform tour, deploy echo workflow, Command Center orientation.
+
+**Item 2 -- How This Workspace Works:** CLAUDE.md as instruction sheet, four commands, creds skill, memory system overview.
+
+**Item 3 -- The /meta Command:** Project dashboard, /meta fix, /meta deploy, /meta health.
+
+**Item 4 -- /work and /docs:** Cross-session task tracking, documentation lifecycle, /work vs /docs boundary.
+
+---
+
+## Core Path: Lessons 5-10
+
+Each lesson: (1) announce title and goal, (2) explain concept per skill level, (3) build or modify something, (4) verify it works, (5) record observations, ask "ready for next?"
+
+**Lesson 5 -- Your First Custom Workflow**
+
+- `automation: none` -- "A recipe." Agent writes all code. Agent runs `elevasis-sdk exec` and narrates result.
+- `automation: low-code or custom` -- Modify echo workflow. Walk through `config`, `contract`, `steps`, `entryPoint`. Deploy with `elevasis-sdk check` then `elevasis-sdk deploy`.
+
+**Lesson 6 -- Understanding Data (Schemas)**
+
+- `automation: none` -- "What information does your automation need?" No Zod, no code shown. Agent reads identity.md goals and writes the schema.
+- `automation: low-code` -- "Field mapping like Zapier, but with validation." Show Zod types briefly.
+- `automation: custom` -- Full Zod explanation. `z.infer`. Show how schema fields define CLI input structure.
+
+**Lesson 7 -- Using Platform Tools**
+
+- `automation: none` -- Agent makes all code edits. Credential creation guided via Command Center UI.
+- `automation: low-code or custom` -- Explain adapter pattern: `createAttioAdapter('cred')`. Show singleton pattern: `import { scheduler, llm } from '@elevasis/sdk/worker'`.
+
+**Lesson 8 -- Multi-Step Workflows**
+
+- `automation: none` -- "Step 1 passes its result to Step 2, like a relay race." Command View is PRIMARY teaching tool.
+- `automation: low-code or custom` -- Chain steps with `StepType.LINEAR`. Show relationship edges in Command View.
+
+**Lesson 9 -- Decision Points**
+
+- `automation: none` -- "If the customer is VIP, do this -- otherwise, do that." Agent runs both paths. Open Execution Logs.
+- `automation: low-code or custom` -- Conditional routing with `StepType.CONDITIONAL`. Show step trace in Execution Logs.
+
+**Lesson 10 -- Going to Production**
+
+- `automation: none` -- "Draft vs live." Create Recurring schedule in Task Scheduler.
+- `automation: low-code or custom` -- Change `status: dev` -> `prod`. Cover `try/catch`, `ExecutionError`, `PlatformToolError`. CLI monitoring: `elevasis-sdk executions`.
+
+---
+
+## Module System: Items 11-19
+
+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.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               |
+
+---
+
+## Advanced Workspace: Items 20-21
+
+**Item 20 -- Rules, Memory, and Customization**
+
+- `none` -- "Sticky notes the agent reads automatically." Show `.claude/rules/workspace-patterns.md` without technical detail.
+- `low-code` -- Show `.claude/rules/` directory. Explain MANAGED (`sdk-patterns.md`) vs INIT_ONLY (`workspace-patterns.md`). Explain error promotion: 3+ recurrences -> add a rule.
+- `custom` -- Read both rules files. Walk through memory layout: `index.md`, `profile/`, `errors/`, `tutorial-progress.md`. Walk through adding a new rule.
+
+**Item 21 -- Template Lifecycle**
+
+- `none` -- "SDK releases automatically update your workspace." Explain `/meta fix` as the update command.
+- `low-code` -- Explain MANAGED vs INIT_ONLY file types. Show how `/meta fix` handles conflicts.
+- `custom` -- Full template lifecycle: init (writes all files), update (applies MANAGED changes, flags conflicts, preserves INIT_ONLY), fix (drift repair + SDK upgrade offer). Conflict resolution reads current + template from `@elevasis/sdk/templates`, merges preserving customizations.
+
+---
+
+## Progress File Format
+
+Stored at `.claude/memory/tutorial-progress.md`.
+
+```markdown
+# Tutorial Progress
+
+Current: <free-form, e.g. "4: /work and /docs" or "M:integrations">
+Started: YYYY-MM-DD
+Last Session: YYYY-MM-DD
+
+## Completed Lessons
+
+| Item | Title | Completed | Duration |
+| --- | --- | --- | --- |
+| 1 | Welcome & Orientation | 2026-03-01 | 25 min |
+
+## Completed Modules
+
+| Module | Title | Completed | Duration |
+| --- | --- | --- | --- |
+| hitl | Human-in-the-Loop | 2026-03-03 | 40 min |
+
+## Capability Observations
+
+| Source | Observation |
+| --- | --- |
+| 1 | Navigated Command View without guidance |
+
+## Assessment Notes
+
+- Strong automation background, slow on TypeScript syntax
+```
+
+---
+
+**Last Updated:** 2026-03-05

package/reference/{getting-started/index.mdx → 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/index.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