@elevasis/sdk 1.20.2 → 1.22.0

package/reference/framework/index.mdx

@@ -1,195 +1,195 @@
----
-title: Development Framework
-description: The SDK scaffolds a complete development environment for Claude Code -- project instructions, slash commands, cross-session memory, template versioning, and resource documentation
-loadWhen: "Understanding the agent framework structure"
----
-
-`elevasis-sdk init` scaffolds more than code. It builds a development environment designed around Claude Code as the primary interface. Most external SDK developers are non-technical -- they write workflows through conversation, not by reading API docs. The framework gives the agent everything it needs to guide those users effectively from the first session onward.
-
-The framework lives entirely in `.claude/`. It is never deployed and never touches the `docs/` directory, which ships to the platform.
-
-## What Gets Scaffolded
-
-Running `elevasis-sdk init my-project` produces the following agent infrastructure alongside your source files:
-
-```
-.claude/
-├── settings.json               # Hook registrations (PostToolUse, PostToolUseFailure)
-├── hooks/
-│   ├── post-edit-validate.mjs    # Formatting/type-check hook (after Write/Edit/MultiEdit)
-│   └── tool-failure-recovery.mjs # Error recovery hook (after Bash failures)
-├── skills/
-│   ├── work/SKILL.md           # Task tracking across sessions
-│   ├── elevasis/SKILL.md       # SDK operations (check, deploy, exec)
-│   ├── deploy/skill.md         # Deploy pipeline
-│   ├── setup/SKILL.md          # First-time project setup
-│   ├── status/SKILL.md         # Project health check
-│   └── ...                     # Additional skills (dsp, continue, project, sync, explore, save)
-├── scripts/
-│   └── statusline-command.js   # Status line command
-└── rules/
-    ├── sdk-patterns.md         # SDK patterns (auto-loaded for src/ files)
-    ├── docs-authoring.md       # MDX conventions (auto-loaded for docs/ files)
-    ├── task-tracking.md        # Task tracking conventions (auto-loaded)
-    ├── platform.md             # Platform tool patterns
-    ├── error-handling.md       # Error handling patterns
-    └── workspace-patterns.md   # Project-specific patterns (grows over time)
-```
-
-The `memory/` directory is gitignored -- it is personal to each developer and not shared with collaborators. Everything else in `.claude/` is committed.
-
-CLAUDE.md is scaffolded with an `<!-- initialized: false -->` HTML comment at the very top. When the agent reads this flag on session start and finds it false, it automatically runs the `/meta init` flow -- no slash command knowledge required from the user. After initialization completes the agent changes the flag to `<!-- initialized: true -->`, so subsequent sessions proceed normally.
-
-## Why It Works This Way
-
-The agent needs three things to guide a non-technical developer well:
-
-- **Who the user is** -- their TypeScript experience, automation background, and project goals, stored in `.claude/memory/profile/` as markdown files and created during `/meta init`
-- **What has happened in this project** -- deployment state, credentials, errors encountered, and architectural decisions, stored in `.claude/memory/` and loaded on demand
-- **How to behave** -- adaptive guidance rules in `CLAUDE.md` that translate experience levels into concrete behaviors: complete code examples for beginners, concise fixes for advanced users
-
-The agent reads `memory/index.md` at session start and drills into `memory/profile/skills.md` for adaptive behavior. It adjusts its tone, explanation depth, and proactivity based on what it finds. This happens silently -- the developer sees a helpful response, not a loading message.
-
-## The Framework Components
-
-### Agent System
-
-The `CLAUDE.md` file drives all agent behavior. It contains the session initialization instructions, adaptive guidance tiers, memory maintenance rules, and slash command definitions. No hooks, no code enforcement -- everything is instruction-driven so non-technical users never need to configure anything.
-
-The `/meta` command manages the project lifecycle: `/meta init` for guided setup, `/meta fix` for SDK upgrades, drift repair, and documentation verification, `/meta deploy` for deployments, `/meta health` for debugging executions. `/docs` browses, creates, and verifies permanent documentation in `docs/`. `/work` tracks tasks across sessions, and `/tutorial` guides new developers through a menu-driven multi-track learning path. A `creds` skill auto-triggers when credential setup is needed.
-
-See [Agent System](agent.mdx) for CLAUDE.md sections, slash command reference, developer profile, and adaptive guidance tiers.
-
-### Memory System
-
-The `memory/` directory follows a hierarchical index tree pattern: a root `index.md` maps to topic files and subdirectories, each subdirectory has its own index. The agent reads only the root index at session start and drills into detail files on demand. The `memory/profile/` subdirectory is seeded by `/meta init` during guided setup; other topics are created by the agent as needed.
-
-Topics include developer profile (identity, skills, preferences), deployment state, environment credentials, architectural decisions, and error patterns. Error tracking starts as a subdirectory because it naturally spans multiple categories. Other topics start as flat files and split when they outgrow a single document.
-
-See [Memory System](memory.mdx) for architecture, error tracking format, scaling rules, and maintenance guidelines.
-
-### Project Structure
-
-The scaffolded project separates concerns clearly: `operations/` for executable resources, `core/` for shared contracts and Organization Model configuration, `ui/` for the shell, `docs/` for platform documentation, and `.claude/` for agent infrastructure. Understanding which files are gitignored, which are committed, and why matters for collaborating on projects.
-
-See [Project Structure](project-structure.mdx) for a file-by-file walkthrough of the scaffolded project.
-
-## Adaptive Guidance
-
-The agent adapts its communication based on four independent skill dimensions stored in `memory/profile/skills.md`:
-
-| Dimension           | Levels                        | Assessment                       |
-| ------------------- | ----------------------------- | -------------------------------- |
-| Platform Navigation | none / oriented / comfortable | Direct question                  |
-| API & Integration   | none / basic / proficient     | Inferred from automation + tools |
-| Automation Concepts | none / low-code / custom      | Direct question                  |
-| Domain Expertise    | high / low                    | Inferred from identity answers   |
-
-Each dimension has its own adaptation rules in the [Interaction Guidance](interaction-guidance.mdx) reference. A user who has deep Zapier experience (automation: low-code) but has never called an API directly (apiIntegration: none) will get credential walkthroughs every time while having automation concepts treated as familiar ground.
-
-`/tutorial` runs the assessment via a single gate question on first invocation: are you here to build automations by describing what you want, or are you a developer who edits code directly. The choice persists to `.claude/memory/profile.md` and shapes the agent's tone, vocabulary, and tool-call visibility for the entire project, not just inside `/tutorial`. Within the chosen track, lessons adapt further -- senior devs in the technical track can mark Section A items complete to skip them.
-
-See [Agent System](agent.mdx) for the full assessment question set, dimensional interaction rules, and communication principles.
-
-### Skills Auto-Update
-
-The Growth Log in `memory/profile/skills.md` keeps approximately 20 recent entries. The agent adds an entry whenever it observes the user performing something they previously needed help with. When a consistent pattern of growth is observed -- typically after several independent successes -- the agent promotes the observation to a level change in the relevant dimension.
-
----
-
-## Resource Documentation
-
-`elevasis-sdk deploy` ships your code and your documentation atomically -- one command, no version drift. Documentation files live in a `docs/` directory at your project root and render in the Elevasis platform UI for operators using your resources.
-
-### Directory Structure
-
-Create `.mdx` files inside a `docs/` directory at your project root. `elevasis-sdk init` scaffolds a starter structure:
-
-```
-my-project/
-├── docs/
-│   └── index.mdx          # Resource overview (scaffolded by init)
-├── src/
-│   └── index.ts            # Resource definitions
-└── elevasis.config.ts
-```
-
-A missing `docs/` directory is silently ignored -- documentation is optional. If the directory exists, its contents are included in the deploy payload alongside resource schemas.
-
-### Frontmatter Schema
-
-```yaml
----
-title: string       # Page title (required)
-description: string # Short description (optional)
-order: number       # Sort order within directory (optional, default: 0)
----
-```
-
-### Naming Conventions
-
-- `docs/index.md` is the root page and is always rendered first
-- Nested directories create sections: `docs/guides/getting-started.mdx`
-- File names become URL slugs: `setup-guide.mdx` renders at `/docs/setup-guide`
-- Arbitrary nesting is supported -- no depth limit
-
-### Size Limits
-
-- 100KB per file
-- 1MB total across all files in a deployment
-
-These limits are enforced by the CLI before the deploy request is sent. Validation errors include the file name and size.
-
-### Deploy Behavior
-
-When you run `elevasis-sdk deploy`:
-
-1. The CLI scans `docs/` recursively for `.mdx` files
-2. Each file's frontmatter (title, description, order) is parsed and stripped from the content
-3. Total size is validated against the 1MB limit and individual files against 100KB
-4. The documentation array is included in the deploy metadata alongside your resource schemas
-
-Documentation and code ship in the same transaction. There is no separate upload step and no way for documentation to drift out of sync with the deployed version.
-
-### The /docs Command
-
-The `/docs` command manages the permanent `docs/` tree in your project. It operates on everything in `docs/` except `docs/in-progress/` (owned by `/work`) and auto-generated files (`project-map.mdx`, `resource-map.mdx`).
-
-**Browse (default):** Running `/docs` with no arguments scans `docs/` recursively and presents a numbered list of user-maintained docs. Pick a number to read and discuss the doc, or say "create" or "verify."
-
-**Create:** `/docs create [description]` runs an interview-driven flow. It asks what you want to document, determines placement, scans `src/` to pre-populate from code, and creates the file with appropriate sections.
-
-Section templates by doc type:
-
-- **Resource guide:** Overview, Input/Output, How It Works, Platform Tools Used, Configuration
-- **Integration guide:** Overview, Setup (credentials), Data Model, Usage Patterns, Troubleshooting
-- **Architecture notes:** Context, Decision, Consequences, Alternatives Considered
-- **Process doc:** Purpose, Prerequisites, Steps, Recovery
-
-**Verify:** `/docs verify [file?]` checks docs against current code interactively. Without an argument, it scans all user-maintained docs, cross-references resource IDs, schema fields, and platform tools against `src/`, and offers to fix or create docs for undocumented resources.
-
-**Command Routing Reference:**
-
-| Scenario                                | Command                                               |
-| --------------------------------------- | ----------------------------------------------------- |
-| Starting new work                       | `/work` (auto-detects new work from your description) |
-| Resuming yesterday's work               | `/work` (auto-resumes if one task is in-progress)     |
-| Browsing what docs exist                | `/docs`                                               |
-| Creating a reference doc (not a task)   | `/docs create`                                        |
-| Checking if docs match current code     | `/docs verify`                                        |
-| Full maintenance pipeline (8 steps)     | `/meta fix`                                           |
-| Deploying code and auto-generating maps | `/meta deploy`                                        |
-
----
-
-## Documentation
-
-- [Project Structure](project-structure.mdx) - File-by-file walkthrough of every scaffolded file and its purpose
-- [Agent System](agent.mdx) - CLAUDE.md sections, slash commands, developer profile, and adaptive guidance tiers
-- [Memory System](memory.mdx) - Architecture, error tracking format, scaling rules, and maintenance guidelines
-- [Interaction Guidance](interaction-guidance.mdx) - Dimensional adaptation rules per skill axis with growth tracking protocol
-- [Tutorial System](tutorial-system.mdx) - 21-item tutorial menu, skill-adaptive lesson variants, and progress tracking
-
----
-
-**Last Updated:** 2026-03-06
+---
+title: Development Framework
+description: The SDK scaffolds a complete development environment for Claude Code -- project instructions, slash commands, cross-session memory, template versioning, and resource documentation
+loadWhen: "Understanding the agent framework structure"
+---
+
+`elevasis-sdk init` scaffolds more than code. It builds a development environment designed around Claude Code as the primary interface. Most external SDK developers are non-technical -- they write workflows through conversation, not by reading API docs. The framework gives the agent everything it needs to guide those users effectively from the first session onward.
+
+The framework lives entirely in `.claude/`. It is never deployed and never touches the `docs/` directory, which ships to the platform.
+
+## What Gets Scaffolded
+
+Running `elevasis-sdk init my-project` produces the following agent infrastructure alongside your source files:
+
+```
+.claude/
+├── settings.json               # Hook registrations (PostToolUse, PostToolUseFailure)
+├── hooks/
+│   ├── post-edit-validate.mjs    # Formatting/type-check hook (after Write/Edit/MultiEdit)
+│   └── tool-failure-recovery.mjs # Error recovery hook (after Bash failures)
+├── skills/
+│   ├── work/SKILL.md           # Task tracking across sessions
+│   ├── elevasis/SKILL.md       # SDK operations (check, deploy, exec)
+│   ├── deploy/skill.md         # Deploy pipeline
+│   ├── setup/SKILL.md          # First-time project setup
+│   ├── status/SKILL.md         # Project health check
+│   └── ...                     # Additional skills (dsp, continue, project, sync, explore, save)
+├── scripts/
+│   └── statusline-command.js   # Status line command
+└── rules/
+    ├── sdk-patterns.md         # SDK patterns (auto-loaded for src/ files)
+    ├── docs-authoring.md       # MDX conventions (auto-loaded for docs/ files)
+    ├── task-tracking.md        # Task tracking conventions (auto-loaded)
+    ├── platform.md             # Platform tool patterns
+    ├── error-handling.md       # Error handling patterns
+    └── workspace-patterns.md   # Project-specific patterns (grows over time)
+```
+
+The `memory/` directory is gitignored -- it is personal to each developer and not shared with collaborators. Everything else in `.claude/` is committed.
+
+CLAUDE.md is scaffolded with an `<!-- initialized: false -->` HTML comment at the very top. When the agent reads this flag on session start and finds it false, it automatically runs the `/meta init` flow -- no slash command knowledge required from the user. After initialization completes the agent changes the flag to `<!-- initialized: true -->`, so subsequent sessions proceed normally.
+
+## Why It Works This Way
+
+The agent needs three things to guide a non-technical developer well:
+
+- **Who the user is** -- their TypeScript experience, automation background, and project goals, stored in `.claude/memory/profile/` as markdown files and created during `/meta init`
+- **What has happened in this project** -- deployment state, credentials, errors encountered, and architectural decisions, stored in `.claude/memory/` and loaded on demand
+- **How to behave** -- adaptive guidance rules in `CLAUDE.md` that translate experience levels into concrete behaviors: complete code examples for beginners, concise fixes for advanced users
+
+The agent reads `memory/index.md` at session start and drills into `memory/profile/skills.md` for adaptive behavior. It adjusts its tone, explanation depth, and proactivity based on what it finds. This happens silently -- the developer sees a helpful response, not a loading message.
+
+## The Framework Components
+
+### Agent System
+
+The `CLAUDE.md` file drives all agent behavior. It contains the session initialization instructions, adaptive guidance tiers, memory maintenance rules, and slash command definitions. No hooks, no code enforcement -- everything is instruction-driven so non-technical users never need to configure anything.
+
+The `/meta` command manages the project lifecycle: `/meta init` for guided setup, `/meta fix` for SDK upgrades, drift repair, and documentation verification, `/meta deploy` for deployments, `/meta health` for debugging executions. `/docs` browses, creates, and verifies permanent documentation in `docs/`. `/work` tracks tasks across sessions, and `/tutorial` guides new developers through a menu-driven multi-track learning path. A `creds` skill auto-triggers when credential setup is needed.
+
+See [Agent System](agent.mdx) for CLAUDE.md sections, slash command reference, developer profile, and adaptive guidance tiers.
+
+### Memory System
+
+The `memory/` directory follows a hierarchical index tree pattern: a root `index.md` maps to topic files and subdirectories, each subdirectory has its own index. The agent reads only the root index at session start and drills into detail files on demand. The `memory/profile/` subdirectory is seeded by `/meta init` during guided setup; other topics are created by the agent as needed.
+
+Topics include developer profile (identity, skills, preferences), deployment state, environment credentials, architectural decisions, and error patterns. Error tracking starts as a subdirectory because it naturally spans multiple categories. Other topics start as flat files and split when they outgrow a single document.
+
+See [Memory System](memory.mdx) for architecture, error tracking format, scaling rules, and maintenance guidelines.
+
+### Project Structure
+
+The scaffolded project separates concerns clearly: `operations/` for executable resources, `core/` for shared contracts and Organization Model configuration, `ui/` for the shell, `docs/` for platform documentation, and `.claude/` for agent infrastructure. Understanding which files are gitignored, which are committed, and why matters for collaborating on projects.
+
+See [Project Structure](project-structure.mdx) for a file-by-file walkthrough of the scaffolded project.
+
+## Adaptive Guidance
+
+The agent adapts its communication based on four independent skill dimensions stored in `memory/profile/skills.md`:
+
+| Dimension           | Levels                        | Assessment                       |
+| ------------------- | ----------------------------- | -------------------------------- |
+| Platform Navigation | none / oriented / comfortable | Direct question                  |
+| API & Integration   | none / basic / proficient     | Inferred from automation + tools |
+| Automation Concepts | none / low-code / custom      | Direct question                  |
+| Domain Expertise    | high / low                    | Inferred from identity answers   |
+
+Each dimension has its own adaptation rules in the [Interaction Guidance](interaction-guidance.mdx) reference. A user who has deep Zapier experience (automation: low-code) but has never called an API directly (apiIntegration: none) will get credential walkthroughs every time while having automation concepts treated as familiar ground.
+
+`/tutorial` runs the assessment via a single gate question on first invocation: are you here to build automations by describing what you want, or are you a developer who edits code directly. The choice persists to `.claude/memory/profile.md` and shapes the agent's tone, vocabulary, and tool-call visibility for the entire project, not just inside `/tutorial`. Within the chosen track, lessons adapt further -- senior devs in the technical track can mark Section A items complete to skip them.
+
+See [Agent System](agent.mdx) for the full assessment question set, dimensional interaction rules, and communication principles.
+
+### Skills Auto-Update
+
+The Growth Log in `memory/profile/skills.md` keeps approximately 20 recent entries. The agent adds an entry whenever it observes the user performing something they previously needed help with. When a consistent pattern of growth is observed -- typically after several independent successes -- the agent promotes the observation to a level change in the relevant dimension.
+
+---
+
+## Resource Documentation
+
+`elevasis-sdk deploy` ships your code and your documentation atomically -- one command, no version drift. Documentation files live in a `docs/` directory at your project root and render in the Elevasis platform UI for operators using your resources.
+
+### Directory Structure
+
+Create `.mdx` files inside a `docs/` directory at your project root. `elevasis-sdk init` scaffolds a starter structure:
+
+```
+my-project/
+├── docs/
+│   └── index.mdx          # Resource overview (scaffolded by init)
+├── src/
+│   └── index.ts            # Resource definitions
+└── elevasis.config.ts
+```
+
+A missing `docs/` directory is silently ignored -- documentation is optional. If the directory exists, its contents are included in the deploy payload alongside resource schemas.
+
+### Frontmatter Schema
+
+```yaml
+---
+title: string       # Page title (required)
+description: string # Short description (optional)
+order: number       # Sort order within directory (optional, default: 0)
+---
+```
+
+### Naming Conventions
+
+- `docs/index.md` is the root page and is always rendered first
+- Nested directories create sections: `docs/guides/getting-started.mdx`
+- File names become URL slugs: `setup-guide.mdx` renders at `/docs/setup-guide`
+- Arbitrary nesting is supported -- no depth limit
+
+### Size Limits
+
+- 100KB per file
+- 1MB total across all files in a deployment
+
+These limits are enforced by the CLI before the deploy request is sent. Validation errors include the file name and size.
+
+### Deploy Behavior
+
+When you run `elevasis-sdk deploy`:
+
+1. The CLI scans `docs/` recursively for `.mdx` files
+2. Each file's frontmatter (title, description, order) is parsed and stripped from the content
+3. Total size is validated against the 1MB limit and individual files against 100KB
+4. The documentation array is included in the deploy metadata alongside your resource schemas
+
+Documentation and code ship in the same transaction. There is no separate upload step and no way for documentation to drift out of sync with the deployed version.
+
+### The /docs Command
+
+The `/docs` command manages the permanent `docs/` tree in your project. It operates on everything in `docs/` except `docs/in-progress/` (owned by `/work`) and auto-generated files (`project-map.mdx`, `resource-map.mdx`).
+
+**Browse (default):** Running `/docs` with no arguments scans `docs/` recursively and presents a numbered list of user-maintained docs. Pick a number to read and discuss the doc, or say "create" or "verify."
+
+**Create:** `/docs create [description]` runs an interview-driven flow. It asks what you want to document, determines placement, scans `src/` to pre-populate from code, and creates the file with appropriate sections.
+
+Section templates by doc type:
+
+- **Resource guide:** Overview, Input/Output, How It Works, Platform Tools Used, Configuration
+- **Integration guide:** Overview, Setup (credentials), Data Model, Usage Patterns, Troubleshooting
+- **Architecture notes:** Context, Decision, Consequences, Alternatives Considered
+- **Process doc:** Purpose, Prerequisites, Steps, Recovery
+
+**Verify:** `/docs verify [file?]` checks docs against current code interactively. Without an argument, it scans all user-maintained docs, cross-references resource IDs, schema fields, and platform tools against `src/`, and offers to fix or create docs for undocumented resources.
+
+**Command Routing Reference:**
+
+| Scenario                                | Command                                               |
+| --------------------------------------- | ----------------------------------------------------- |
+| Starting new work                       | `/work` (auto-detects new work from your description) |
+| Resuming yesterday's work               | `/work` (auto-resumes if one task is in-progress)     |
+| Browsing what docs exist                | `/docs`                                               |
+| Creating a reference doc (not a task)   | `/docs create`                                        |
+| Checking if docs match current code     | `/docs verify`                                        |
+| Full maintenance pipeline (8 steps)     | `/meta fix`                                           |
+| Deploying code and auto-generating maps | `/meta deploy`                                        |
+
+---
+
+## Documentation
+
+- [Project Structure](project-structure.mdx) - File-by-file walkthrough of every scaffolded file and its purpose
+- [Agent System](agent.mdx) - CLAUDE.md sections, slash commands, developer profile, and adaptive guidance tiers
+- [Memory System](memory.mdx) - Architecture, error tracking format, scaling rules, and maintenance guidelines
+- [Interaction Guidance](interaction-guidance.mdx) - Dimensional adaptation rules per skill axis with growth tracking protocol
+- [Tutorial System](tutorial-system.mdx) - 21-item tutorial menu, skill-adaptive lesson variants, and progress tracking
+
+---
+
+**Last Updated:** 2026-03-06