@elevasis/sdk 0.4.5 → 0.4.7

package/reference/framework/agent.mdx

@@ -0,0 +1,175 @@
+---
+title: Agent System
+description: CLAUDE.md drives all agent behavior -- project instructions, slash commands, memory-based developer profile, and three-tier adaptive guidance
+loadWhen: "Configuring agent behavior or capabilities"
+---
+
+The agent system is the set of files that shape how Claude Code behaves in your SDK project. It consists of four parts: `CLAUDE.md` (the instruction file), slash commands (structured task entry points), the developer profile stored in `memory/profile/`, and the adaptive guidance rules that translate profile data into concrete agent behavior.
+
+Nothing here requires configuration. The agent reads these files at session start and adapts automatically.
+
+## CLAUDE.md
+
+`CLAUDE.md` is the project instruction file for Claude Code. It is read at the start of every session and governs all agent behavior. In an Elevasis SDK project, it is generated by `elevasis init` and lives at the project root.
+
+The file is instruction-driven by design. Non-technical developers should never need to edit it. When the agent learns a new rule worth preserving -- such as an error pattern that recurs three times -- it promotes that rule into `CLAUDE.md` automatically.
+
+### Sections
+
+The generated `CLAUDE.md` contains these sections:
+
+- **Session Initialization** -- Instructs the agent to read `memory/index.md` silently at session start, drill into `memory/profile/skills.md` for adaptive behavior, suggest `/meta init` if memory does not exist, and notify the user if the template version is outdated.
+- **What This Is** -- Project orientation: what an Elevasis SDK project is and how it deploys to the platform.
+- **Project Structure** -- Which files contain resources, documentation, and configuration.
+- **CLI Reference** -- All `elevasis` commands with flags, including deploy, exec, env, and execution inspection.
+- **SDK Patterns** -- Working code examples for resource definitions, Zod schemas, multi-step workflows, platform tools, and execution context.
+- **Rules** -- Project-specific constraints. Starts empty; grows as the agent promotes recurring error patterns.
+- **Maintaining Memory** -- Hierarchical scaling pattern, pruning rules, and promotion criteria for the `memory/` directory.
+- **SDK Reference Documentation** -- Paths to bundled SDK reference docs in `node_modules/@elevasis/sdk/reference/`.
+- **Adaptive Guidance** -- Behavior rules for Beginner, Intermediate, and Advanced tiers based on skill levels read from `memory/profile/skills.md`.
+
+### Session Initialization
+
+At the start of every session the agent runs these steps silently before responding:
+
+1. Read `.claude/memory/index.md` if it exists -- scan what project context has been recorded, including profile, error patterns, deployment state, and decisions. Drill into `memory/profile/skills.md` to personalize responses based on experience level.
+2. If `.claude/memory/` does not exist, suggest running `/meta init` to set up the project.
+3. Check the installed `@elevasis/sdk` template version against `templateVersion` in `elevasis.config.ts`. If the SDK has a newer version, notify the user and suggest running `/meta update`.
+
+## Slash Commands
+
+Slash commands are short Markdown instruction files in `.claude/commands/`. When you type `/command-name` in a Claude Code session, the agent reads the corresponding file and follows its instructions.
+
+All nine commands are scaffolded by `elevasis init` and committed to version control so collaborators get the same experience:
+
+| Command | File | Purpose |
+| --- | --- | --- |
+| `/meta` | `meta.md` | Project lifecycle management -- init, status, update, fix, deploy, health, develop |
+| `/docs` | `docs.md` | Documentation lifecycle -- create, checkpoint, cleanup, resume, verify |
+| `/database` | `database.md` | Database operations -- init, status, add, browse, schema, import |
+| `/resource` | `resource.md` | Scaffolds a new workflow or agent resource in `src/` |
+| `/templates` | `templates.md` | Workflow template discovery and scaffolding |
+| `/agent` | `agent.md` | Agent development (placeholder for future agent runtime) |
+| `/tutorial` | `tutorial.md` | Progressive learning path for new developers |
+| `/help` | `help.md` | Displays the full command tree and navigation map |
+| `/profile` | `profile.md` | Views and updates the developer profile in `memory/profile/` |
+
+### `/meta` Command
+
+The `/meta` command namespace manages the full project lifecycle. It has seven operations:
+
+- **`/meta init`** -- First-run guided setup. Runs after `elevasis init` to install dependencies, configure `.env`, run the 6-question onboarding flow, seed `memory/profile/`, verify the project, and optionally do a first deploy.
+- **`/meta`** (no arguments) -- Project health status. Shows current template version, SDK version, profile summary, and a quick drift check.
+- **`/meta update`** -- Upgrade the SDK and merge template changes. Runs `pnpm update @elevasis/sdk`, then `elevasis update`, then intelligently merges flagged files and reports what changed.
+- **`/meta fix`** -- Repair drift without a version upgrade. Checks for missing commands, missing gitignore entries, missing CLAUDE.md sections, broken memory links, and broken doc cross-references.
+- **`/meta deploy`** -- Full 9-step deploy pipeline: validate, type-check, verify docs, commit, deploy, bump version, verify platform, update deployment state, and optionally push.
+- **`/meta health`** -- Execution debugging and resource status; shows recent executions, analyzes failures, and checks environment connectivity.
+- **`/meta develop`** -- Development navigation hub that loads the resource map, SDK reference, and project state; replaces the old standalone `/workflow`, `/tools`, and `/examples` commands.
+
+### `/docs` Command
+
+The `/docs` command manages the full documentation lifecycle. It has six operations:
+
+- **`/docs`** (no arguments) -- Show current documentation status: pages in progress, recent changes, and any stale entries flagged for review.
+- **`/docs create`** -- Create a new documentation page. Prompts for title, description, and location, then scaffolds an MDX file with proper frontmatter.
+- **`/docs checkpoint`** -- Save current work progress for session resume. Creates or updates `docs/in-progress/<topic>.mdx` with current state, decisions made, remaining work, and blockers. Also updates `docs/priorities.mdx`.
+- **`/docs cleanup`** -- Move completed documents from `docs/in-progress/` to their final location. Reviews each in-progress doc, relocates complete ones, and rebuilds `docs/navigation.mdx`.
+- **`/docs resume`** -- Start-of-session review of in-progress docs, priorities, and recent deployment state. Offers to continue work on the highest-priority item.
+- **`/docs verify`** -- Cross-reference documentation with the codebase. Reads the specified doc (or all docs if no path provided) and reports discrepancies against actual resource IDs, schema fields, and platform tools.
+
+### `/database` Command
+
+The `/database` command handles all database operations for projects that connect a Supabase project. It has six operations:
+
+- **`/database init`** -- Connect a Supabase project. Prompts for project URL and anon key, writes connection config, and verifies connectivity.
+- **`/database`** (no arguments) -- Show database status: connection health, migration count, and a summary of tables.
+- **`/database add`** -- Create a migration script for a new table. Prompts for table name and columns, generates a typed migration, and updates schema documentation.
+- **`/database browse`** -- Query and display table contents in a readable format for quick inspection during development.
+- **`/database schema`** -- View or compare schema documentation against the live database. Highlights drift between documented schema and actual columns.
+- **`/database import`** -- Import CSV or JSON data into a table. Validates column mapping before writing.
+
+### `/help` Command
+
+The `/help` command displays the complete command tree with one-line descriptions for every command and subcommand, plus navigation pointers to key project files (`docs/navigation.mdx`, `docs/priorities.mdx`, `memory/index.md`). It is the "I'm lost, what can I do?" entry point for command discovery and navigation.
+
+### `/profile` Command
+
+The profile command reads from and writes to `memory/profile/`. It has three modes:
+
+- **No arguments** -- Displays the current profile in readable format (organization, industry, experience levels, goals, known integrations, preferences) and asks if anything needs updating.
+- **`/profile update`** -- Walks through each profile section, shows current values, and updates only the fields the user wants to change. Writes changes to the appropriate `memory/profile/` file.
+- **`/profile level`** -- Assesses the user's current skill level based on project history (resources created, successful deploys, error handling patterns) and suggests updating `memory/profile/skills.md` if the assessment differs from the stored level.
+
+## Developer Profile
+
+The developer profile is stored in `.claude/memory/profile/` as a set of markdown files. It is gitignored -- personal to each developer, not shared with collaborators. Profile data lives in the memory system alongside error patterns, deployment state, and decisions.
+
+### Onboarding Flow
+
+Profile data is created during `/meta init`. The command runs a 6-question onboarding conversation and writes the responses to `memory/profile/`:
+
+1. What kind of business or team is this for? (industry, size)
+2. What are the main goals for this project? (automation goals)
+3. Which external tools or services will workflows integrate with? (integrations)
+4. How would you describe your experience with TypeScript? (beginner / intermediate / advanced)
+5. How familiar are you with AI automation and workflow concepts? (new / some experience / experienced)
+6. Do you prefer detailed explanations or concise responses? (detailed / concise)
+
+### Profile Structure
+
+```
+.claude/memory/profile/
+├── index.md          # Profile summary with links to sub-files
+├── identity.md       # Organization, industry, goals, integrations
+├── skills.md         # TypeScript level, automation experience, growth history
+└── preferences.md    # Verbosity, guidance style, interaction patterns
+```
+
+`identity.md` records the organization name, industry, size, project goals, and known tool integrations. `skills.md` stores the TypeScript and automation skill levels as structured values (`beginner / intermediate / advanced`, `new / some-experience / experienced`) along with a growth history table. `preferences.md` stores verbosity (`detailed / concise`) and proactive guidance preference.
+
+### Auto-Update Triggers
+
+The agent updates `memory/profile/` files when it observes:
+
+- The user successfully completes an advanced task (level upgrade candidate in `skills.md`)
+- The user mentions new tools or integrations not in `identity.md`
+- The user explicitly asks to change preferences
+
+The agent does not prompt for confirmation on minor updates. Major changes (level upgrades) are surfaced to the user before writing.
+
+## Adaptive Guidance
+
+The `CLAUDE.md` Adaptive Guidance section translates the skill levels from `memory/profile/skills.md` into concrete behavior rules. The agent checks the TypeScript level and automation level and applies the matching tier.
+
+### Beginner
+
+Applies when TypeScript level is `beginner` or automation level is `new`:
+
+- Always show complete, working code -- never fragments
+- Explain every new concept the first time it appears (TypeScript types, Zod schemas, async/await)
+- After creating a resource, walk through deployment step by step
+- Proactively suggest next steps ("Now let's deploy this" or "Want to test it?")
+- When errors occur, explain both the fix and why it happened
+- Use `/help` to navigate to the relevant SDK reference before suggesting platform tools
+
+### Intermediate
+
+Applies when TypeScript level is `intermediate` and automation level is `some-experience`:
+
+- Show code with brief inline comments for non-obvious parts
+- Explain new concepts but not basics (Zod, async/await, TypeScript types)
+- Suggest deployment after resource creation but do not walk through it
+- When errors occur, provide the fix with a one-line explanation
+
+### Advanced
+
+Applies when TypeScript level is `advanced` and automation level is `experienced`:
+
+- Concise code, minimal explanation
+- Focus on edge cases and performance
+- Trust the user to deploy and test independently
+- When errors occur, provide the fix
+
+---
+
+**Last Updated:** 2026-02-26

package/reference/framework/documentation.mdx

@@ -0,0 +1,92 @@
+---
+title: Resource Documentation
+description: Write and deploy MDX documentation alongside your Elevasis resources
+loadWhen: "Writing or updating project documentation"
+---
+
+`elevasis 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 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
+
+Every documentation file supports a frontmatter block at the top:
+
+```yaml
+---
+title: string       # Page title (required)
+description: string # Short description (optional)
+order: number       # Sort order within directory (optional, default: 0)
+---
+```
+
+## Naming Conventions
+
+- `docs/index.mdx` is the root documentation 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 -- there is 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.
+
+## Starter Template
+
+`elevasis init` writes this starter file to `docs/index.mdx`:
+
+```mdx
+---
+title: Overview
+description: Documentation for this Elevasis project
+---
+
+# Overview
+
+Welcome to the documentation for this project.
+
+## Resources
+
+Describe your workflows and agents here. This documentation is deployed alongside your
+code and rendered in the Elevasis platform UI.
+
+## Getting Started
+
+\`\`\`bash
+elevasis check    # Validate resources
+elevasis deploy   # Deploy to platform
+elevasis exec <resourceId> --input '{"key": "value"}'
+\`\`\`
+```
+
+## Deploy Behavior
+
+When you run `elevasis 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.
+
+---
+
+**Last Updated:** 2026-02-25

package/reference/framework/index.mdx

@@ -0,0 +1,95 @@
+---
+title: Development Framework
+description: The SDK scaffolds a complete development environment for Claude Code -- project instructions, slash commands, cross-session memory, and template versioning
+loadWhen: "Understanding the agent framework structure"
+---
+
+`elevasis 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 init my-project` produces the following agent infrastructure alongside your source files:
+
+```
+.claude/
+├── CLAUDE.md                   # Project instructions for Claude Code
+├── settings.json               # autoCompact: false
+└── commands/
+    ├── docs.md                 # Documentation assistant
+    ├── resource.md             # Resource scaffolding assistant
+    ├── profile.md              # View and update developer profile
+    ├── meta.md                 # Project lifecycle (init, status, update, fix)
+    ├── help.md                 # Contextual help and concept explanations
+    ├── database.md             # Database schema and query assistant
+    ├── agent.md                # Agent scaffolding and configuration
+    ├── templates.md            # Template browsing and generation
+    └── tutorial.md             # Progressive 7-lesson learning path
+```
+
+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 `/profile` slash command lets developers view and update their profile in `memory/profile/`. The `/meta` command manages the project lifecycle: `/meta init` for guided setup, `/meta update` for SDK upgrades, `/meta fix` for drift repair. Other commands give the agent structured entry points for common tasks: `/meta deploy` for deployments, `/resource` for scaffolding new resources, `/meta health` for debugging executions.
+
+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: `src/` for resources, `docs/` for platform documentation, `.claude/` for agent infrastructure, and config files at the root. 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.
+
+### Documentation
+
+Every SDK project ships its own MDX documentation alongside its resources. The `docs/` directory is bundled into each deployment and served from the platform. This is where you document what your resources do, how to use them, and what inputs they expect.
+
+See [Documentation](documentation.mdx) for writing MDX docs, file limits, and the deploy pipeline.
+
+## Adaptive Guidance
+
+The agent adapts its communication based on five independent skill dimensions stored in `memory/profile/skills.md`:
+
+- **Programming Fundamentals** -- none / minimal / comfortable / advanced
+- **TypeScript** -- none / exposure / proficient
+- **API & Integration** -- none / basic / proficient
+- **Automation Concepts** -- none / low-code / custom
+- **Data Management** -- none / spreadsheets / databases
+
+Each dimension is assessed separately during `/meta init` via 5-6 conditional questions. A user who has deep Zapier experience but no TypeScript knowledge will receive Zod explanations every time while getting automation concepts treated as familiar ground. The questions use conditional skipping to minimize friction: beginners answer 5 questions, developers answer 6.
+
+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. The `/profile` command lets developers view their current levels and trigger a fresh assessment at any time.
+
+---
+
+**Last Updated:** 2026-02-25