@elevasis/sdk 0.5.11 → 0.5.13

package/reference/framework/index.mdx

@@ -1,103 +1,182 @@
----
-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-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               # autoCompact: false
-├── commands/
-│   ├── meta.md                 # Project lifecycle (init, fix, deploy, health)
-│   ├── docs.md                 # Browse, create, and verify permanent docs
-│   ├── tutorial.md             # Progressive learning path (3 tracks)
-│   └── work.md                 # Task tracking
-├── hooks/
-│   └── enforce-sdk-boundary.mjs  # Blocks destructive git, gh CLI, external writes
-├── skills/
-│   └── creds/SKILL.md          # Credential management (auto-triggers)
-└── rules/
-    ├── sdk-patterns.md         # SDK patterns (auto-loaded for src/ files)
-    ├── docs-authoring.md       # MDX conventions (auto-loaded for docs/ files)
-    ├── memory-conventions.md   # Memory 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 (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: `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 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](../developer/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.
-
-`/meta init` runs a 6-question assessment: 3 identity questions, 2 competency questions, and 1 communication preference. Platform Navigation and Automation are assessed directly. API & Integration is inferred from the automation level and tools the user already uses. Domain Expertise is inferred from how specifically the user describes their goals.
-
-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.
-
----
-
-**Last Updated:** 2026-03-03
+---
+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               # autoCompact: false
+├── commands/
+│   ├── meta.md                 # Project lifecycle (init, fix, deploy, health)
+│   ├── docs.md                 # Browse, create, and verify permanent docs
+│   ├── tutorial.md             # Progressive learning path (3 tracks)
+│   └── work.md                 # Task tracking
+├── hooks/
+│   └── enforce-sdk-boundary.mjs  # Blocks destructive git, gh CLI, external writes
+├── skills/
+│   └── creds/SKILL.md          # Credential management (auto-triggers)
+└── rules/
+    ├── sdk-patterns.md         # SDK patterns (auto-loaded for src/ files)
+    ├── docs-authoring.md       # MDX conventions (auto-loaded for docs/ files)
+    ├── memory-conventions.md   # Memory 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 (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: `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.
+
+## 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.
+
+`/meta init` runs a 6-question assessment: 3 identity questions, 2 competency questions, and 1 communication preference. Platform Navigation and Automation are assessed directly. API & Integration is inferred from the automation level and tools the user already uses. Domain Expertise is inferred from how specifically the user describes their goals.
+
+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.mdx` 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 create` |
+| Resuming yesterday's work               | `/work resume` |
+| 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` |
+
+---
+
+**Last Updated:** 2026-03-06