@elevasis/sdk 1.25.0 → 1.26.0

package/reference/framework/tutorial-system.mdx

@@ -1,135 +1,135 @@
----
-title: Tutorial System
-description: The /tutorial skill in the external project scaffold -- two-track onboarding (vibe-coder and technical), gate question, track persistence, and escape hatch
----
-
-The `/tutorial` skill is included in every scaffolded external project. Run it from Claude Code inside a project to start interactive onboarding. It forks into two tracks on first invocation and adapts agent tone project-wide based on your choice.
-
----
-
-## Getting Started
-
-Open a scaffolded external project in Claude Code and run:
-
-```
-/tutorial
-```
-
-On first invocation in a fresh project, the skill asks one gate question:
-
-> "Are you here to **build automations by describing what you want** (and I handle the technical side), or are you a **developer** who'll edit code directly?"
-
-Your answer selects a track. The choice is saved to `.claude/memory/profile.md` and shapes agent vocabulary, tool-call visibility, and verbosity for every conversation in the project -- not just `/tutorial` sessions.
-
-Subsequent `/tutorial` invocations skip the gate question and resume your progress.
-
----
-
-## Tracks at a Glance
-
-### Vibe-Coder Track (8 lessons)
-
-For users who want to describe what they want and have the agent handle the implementation. The agent never uses technical vocabulary -- no TypeScript, no pnpm, no CLI commands shown, no schemas explained. Everything is narrated in plain language.
-
-```
-Your Tutorial
-==============
-1  Welcome -- what this place does for you             [ ]
-2  How to talk to me                                   [ ]
-3  Your business profile                               [ ]
-4  Your first automation                               [ ]
-5  Your dashboard -- where everything lives            [ ]
-6  Your approval queue -- signing off on things        [ ]
-7  Changing things later                               [ ]
-8  When things go wrong                                [ ]
-
-Pick a number to start.
-```
-
-**What each lesson covers:**
-
-- **1. Welcome** -- Plain analogy for the platform. Shows a real automation already running before any building.
-- **2. How to talk to me** -- Conversation patterns for making requests, asking questions, and describing changes. No technical vocabulary introduced.
-- **3. Your business profile** -- Conversational walk through org identity. Agent handles all edits silently; user answers questions.
-- **4. Your first automation** -- User describes what they want. Agent builds, runs, and narrates. User never sees code.
-- **5. Your dashboard** -- Tour of Command Center. Where automations live and how to read the visual map.
-- **6. Your approval queue** -- Show a pending approval, approve it, see the automation continue.
-- **7. Changing things later** -- Plain-language change requests. Agent handles implementation.
-- **8. When things go wrong** -- "Tell me what looks wrong. I'll figure it out and tell you what I did." No error traces shown.
-
-**Vocabulary rules in this track:** The agent never says workflow, schema, deploy, credential, TypeScript, or pnpm. "Automation" replaces all SDK resource terms. "Make it live" replaces "deploy." "Account connection" replaces "credential." "Your approval queue" replaces HITL.
-
-### Technical Track (19 lessons, 5 sections)
-
-For developers who will read and edit code directly. Lessons are code-first. All SDK concepts, CLI commands, and file structures are covered.
-
-```
-SECTION A -- The workspace                              (3 items)
-  1  What is this workspace                              [ ]
-  2  The skill layer -- slash commands you'll use        [ ]
-  3  The vibe layer -- ambient intent classification     [ ]
-
-SECTION B -- Build your first thing                     (5 items)
-  4  Echo workflow tour                                  [ ]
-  5  Custom workflow with schemas                        [ ]
-  6  Platform tools and credentials                      [ ]
-  7  Multi-step and conditionals                         [ ]
-  8  Going to production                                 [ ]
-
-SECTION C -- The Organization Model                     (3 items)
-  9  /knowledge ceremony -- identity, customers,         [ ]
-     offerings via the layered flow
- 10  Features and labels                                 [ ]
- 11  Entity extensions -- BaseProject, BaseDeal          [ ]
-
-SECTION D -- Modules (load on demand)                   (~6 items)
- 12  HITL                                                [ ]
- 13  Schedules                                           [ ]
- 14  Notifications + integrations                        [ ]
- 15  Error handling                                      [ ]
- 16  LLM and agents                                      [ ]
- 17  Composition (execution.trigger)                     [ ]
-
-SECTION E -- Power user                                 (2 items)
- 18  Rules, memory, scaffold registry                    [ ]
- 19  Template lifecycle and /git-sync                    [ ]
-```
-
-Section D modules are available any time -- no section order prerequisite. Sections A-C are designed to be completed in order on a first pass, though any item can be picked directly.
-
----
-
-## Track Persistence
-
-The track choice is saved to `.claude/memory/profile.md` on selection. The agent reads this file at session start alongside `agent-start-here.md`. This means:
-
-- Agent vocabulary and tone adjust for every conversation in the project, not just `/tutorial`
-- The vibe-coder track suppresses all technical surface globally until switched
-- Progress is tracked separately in `.claude/memory/tutorial-progress.md`
-
----
-
-## Switching Tracks
-
-Run `/tutorial switch` at any time to flip tracks and restart the menu. Progress from the previous track is preserved in the progress file for reference but the active lesson resets.
-
----
-
-## Progress Indicators
-
-The menu uses three states:
-
-- `[ ]` -- not started
-- `[>]` -- in progress
-- `[x] YYYY-MM-DD` -- complete
-
-Run `/tutorial` with no argument at any time to see the current menu with progress filled in. Run `/tutorial status` for the same view.
-
----
-
-## Related Docs
-
-- [SDK Concepts](../concepts.mdx) -- full technical reference for workflows, schemas, adapters, and the org model
-- [Getting Started](../getting-started.mdx) -- scaffold setup and first deploy
-- [CLI Reference](../cli.mdx) -- `elevasis-sdk` commands referenced in the technical track
-- [Framework Overview](index.mdx) -- skill layer, memory system, and interaction guidance
+---
+title: Tutorial System
+description: The /tutorial skill in the external project scaffold -- two-track onboarding (vibe-coder and technical), gate question, track persistence, and escape hatch
+---
+
+The `/tutorial` skill is included in every scaffolded external project. Run it from Claude Code inside a project to start interactive onboarding. It forks into two tracks on first invocation and adapts agent tone project-wide based on your choice.
+
+---
+
+## Getting Started
+
+Open a scaffolded external project in Claude Code and run:
+
+```
+/tutorial
+```
+
+On first invocation in a fresh project, the skill asks one gate question:
+
+> "Are you here to **build automations by describing what you want** (and I handle the technical side), or are you a **developer** who'll edit code directly?"
+
+Your answer selects a track. The choice is saved to `.claude/memory/profile.md` and shapes agent vocabulary, tool-call visibility, and verbosity for every conversation in the project -- not just `/tutorial` sessions.
+
+Subsequent `/tutorial` invocations skip the gate question and resume your progress.
+
+---
+
+## Tracks at a Glance
+
+### Vibe-Coder Track (8 lessons)
+
+For users who want to describe what they want and have the agent handle the implementation. The agent never uses technical vocabulary -- no TypeScript, no pnpm, no CLI commands shown, no schemas explained. Everything is narrated in plain language.
+
+```
+Your Tutorial
+==============
+1  Welcome -- what this place does for you             [ ]
+2  How to talk to me                                   [ ]
+3  Your business profile                               [ ]
+4  Your first automation                               [ ]
+5  Your dashboard -- where everything lives            [ ]
+6  Your approval queue -- signing off on things        [ ]
+7  Changing things later                               [ ]
+8  When things go wrong                                [ ]
+
+Pick a number to start.
+```
+
+**What each lesson covers:**
+
+- **1. Welcome** -- Plain analogy for the platform. Shows a real automation already running before any building.
+- **2. How to talk to me** -- Conversation patterns for making requests, asking questions, and describing changes. No technical vocabulary introduced.
+- **3. Your business profile** -- Conversational walk through org identity. Agent handles all edits silently; user answers questions.
+- **4. Your first automation** -- User describes what they want. Agent builds, runs, and narrates. User never sees code.
+- **5. Your dashboard** -- Tour of Command Center. Where automations live and how to read the visual map.
+- **6. Your approval queue** -- Show a pending approval, approve it, see the automation continue.
+- **7. Changing things later** -- Plain-language change requests. Agent handles implementation.
+- **8. When things go wrong** -- "Tell me what looks wrong. I'll figure it out and tell you what I did." No error traces shown.
+
+**Vocabulary rules in this track:** The agent never says workflow, schema, deploy, credential, TypeScript, or pnpm. "Automation" replaces all SDK resource terms. "Make it live" replaces "deploy." "Account connection" replaces "credential." "Your approval queue" replaces HITL.
+
+### Technical Track (19 lessons, 5 sections)
+
+For developers who will read and edit code directly. Lessons are code-first. All SDK concepts, CLI commands, and file structures are covered.
+
+```
+SECTION A -- The workspace                              (3 items)
+  1  What is this workspace                              [ ]
+  2  The skill layer -- slash commands you'll use        [ ]
+  3  The vibe layer -- ambient intent classification     [ ]
+
+SECTION B -- Build your first thing                     (5 items)
+  4  Echo workflow tour                                  [ ]
+  5  Custom workflow with schemas                        [ ]
+  6  Platform tools and credentials                      [ ]
+  7  Multi-step and conditionals                         [ ]
+  8  Going to production                                 [ ]
+
+SECTION C -- The Organization Model                     (3 items)
+  9  /knowledge ceremony -- identity, customers,         [ ]
+     offerings via the layered flow
+ 10  Features and labels                                 [ ]
+ 11  Entity extensions -- BaseProject, BaseDeal          [ ]
+
+SECTION D -- Modules (load on demand)                   (~6 items)
+ 12  HITL                                                [ ]
+ 13  Schedules                                           [ ]
+ 14  Notifications + integrations                        [ ]
+ 15  Error handling                                      [ ]
+ 16  LLM and agents                                      [ ]
+ 17  Composition (execution.trigger)                     [ ]
+
+SECTION E -- Power user                                 (2 items)
+ 18  Rules, memory, scaffold registry                    [ ]
+ 19  Template lifecycle and /git-sync                    [ ]
+```
+
+Section D modules are available any time -- no section order prerequisite. Sections A-C are designed to be completed in order on a first pass, though any item can be picked directly.
+
+---
+
+## Track Persistence
+
+The track choice is saved to `.claude/memory/profile.md` on selection. The agent reads this file at session start alongside `agent-start-here.md`. This means:
+
+- Agent vocabulary and tone adjust for every conversation in the project, not just `/tutorial`
+- The vibe-coder track suppresses all technical surface globally until switched
+- Progress is tracked separately in `.claude/memory/tutorial-progress.md`
+
+---
+
+## Switching Tracks
+
+Run `/tutorial switch` at any time to flip tracks and restart the menu. Progress from the previous track is preserved in the progress file for reference but the active lesson resets.
+
+---
+
+## Progress Indicators
+
+The menu uses three states:
+
+- `[ ]` -- not started
+- `[>]` -- in progress
+- `[x] YYYY-MM-DD` -- complete
+
+Run `/tutorial` with no argument at any time to see the current menu with progress filled in. Run `/tutorial status` for the same view.
+
+---
+
+## Documentation
+
+- [SDK Concepts](../concepts.mdx) - Full technical reference for workflows, schemas, adapters, and the org model
+- [Getting Started](../getting-started.mdx) - Scaffold setup and first deploy
+- [CLI Reference](../cli.mdx) - `elevasis-sdk` commands referenced in the technical track
+- [Framework Overview](index.mdx) - Skill layer, memory system, and interaction guidance

package/reference/getting-started.mdx

@@ -1,142 +1,141 @@
----
-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 file modifications outside project (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 workspace 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
-```
-
-### 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
+---
+title: Getting Started
+description: Install the Elevasis SDK, scaffold a project, and run your first deployment
+---
+
+**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 file modifications outside project (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 workspace 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
+```
+
+### 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