@elevasis/sdk 0.4.5 → 0.4.7

package/reference/framework/memory.mdx

@@ -0,0 +1,337 @@
+---
+title: Memory System
+description: Cross-session project knowledge stored in .claude/memory/ -- deployment state, environment, decisions, and error patterns that persist between Claude Code sessions
+loadWhen: "Working with agent memory or session state"
+---
+
+The memory system gives Claude Code a structured knowledge base for your project that survives across sessions. Deployment history, discovered credentials, architectural decisions, and error patterns are all written to `.claude/memory/` as the project evolves -- so the agent never starts from scratch.
+
+The `memory/` directory is gitignored and personal to each developer. The `profile/` subdirectory is created by `/meta init` during first-run setup. All other topics are created by the agent as the project evolves.
+
+## Purpose
+
+Without project memory, the agent starts every session with only the context of the current conversation. It cannot remember that you already deployed yesterday, that a particular credential is configured, or that you encountered and solved a specific TypeScript error last week.
+
+With project memory, the agent loads a root index at session start, sees what has been recorded, and can retrieve detail on demand. Error patterns are matched before diagnosis. Deployment state is available before deploying again. The agent can say "I've seen this before -- here's the fix" instead of repeating the same diagnostic process.
+
+## Architecture
+
+Memory is organized as a hierarchical index tree. Every directory has an `index.md` that maps to its children -- either content files or subdirectories with their own indexes.
+
+**The invariant:** A reader always starts at the root index and drills down. The agent reads `memory/index.md` at session start. It reads individual topic files on demand when the user asks about that topic or the agent is about to perform an action in that domain.
+
+**The scaling rule:** When a content file outgrows a single document, it graduates into a subdirectory:
+
+1. `topic.md` becomes `topic/index.md` + sub-files
+2. The parent index updates its link from `topic.md` to `topic/index.md`
+3. The new sub-index maps to the sub-files
+
+This pattern is recursive. Subdirectories can split further as needed. The agent applies its own judgment about when a file has grown past usefulness as a single document.
+
+### Starting Structure
+
+After `/meta init` and a first deployment, the structure looks like this:
+
+```
+.claude/memory/
+├── index.md                    # Root index -- read at session start
+├── profile/                    # Developer profile (created by /meta init)
+│   ├── index.md                # Profile summary with links to sub-files
+│   ├── identity.md             # Organization, industry, goals, integrations
+│   ├── skills.md               # TypeScript level, automation experience, growth
+│   └── preferences.md          # Verbosity, guidance style, interaction patterns
+├── deployment-state.md         # Deploy IDs, resource inventory, org info
+├── environment.md              # Credentials, API keys, env vars
+├── decisions.md                # Architectural decisions and patterns
+└── errors/                     # Subdirectory -- multiple categories
+    ├── index.md                # Error category summary with counts
+    ├── deploy.md               # Deployment error patterns
+    ├── runtime.md              # Runtime execution error patterns
+    └── typescript.md           # Type and build error patterns
+```
+
+Profile tracking starts as a subdirectory because it has natural sub-topics from day one (identity, skills, preferences). Error tracking starts as a subdirectory because it naturally spans multiple categories. Other topics start as flat files.
+
+### Grown Structure
+
+As a project matures, other topics may split:
+
+```
+.claude/memory/
+├── index.md
+├── environment.md
+├── decisions.md
+├── deployment-state/           # Grew large enough to split
+│   ├── index.md
+│   ├── resources.md
+│   └── history.md
+└── errors/
+    ├── index.md
+    ├── deploy.md
+    ├── typescript.md
+    └── runtime/                # Runtime errors grew further
+        ├── index.md
+        ├── lead-scorer.md
+        └── email-sender.md
+```
+
+## Memory Topics
+
+### Developer Profile
+
+The `profile/` directory stores the developer's personal context -- organization details, skill levels, goals, and interaction preferences. It is created during `/meta init` guided setup and is the first thing the root index links to.
+
+```
+.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. Example:
+
+```markdown
+# Identity
+
+| Field | Value |
+| --- | --- |
+| Organization | Acme Corp |
+| Industry | E-commerce |
+| Size | 10-50 |
+
+## Project Goals
+
+- Automate lead scoring from Attio CRM
+- Send follow-up emails via Resend
+- Weekly pipeline reports
+
+## Known Integrations
+
+- Attio (CRM)
+- Resend (email)
+- Google Sheets (reporting)
+```
+
+**`skills.md`** stores skill levels as structured values so the Adaptive Guidance rules can apply them consistently. It also tracks a growth history table so the agent can detect when a level upgrade is warranted. Example:
+
+```markdown
+# Skills
+
+| Skill | Level | Since |
+| --- | --- | --- |
+| TypeScript | beginner | 2026-02-25 |
+| AI automation | new | 2026-02-25 |
+
+## Growth History
+
+| Date | Change | Evidence |
+| --- | --- | --- |
+```
+
+**`preferences.md`** stores verbosity and proactive guidance settings. Example:
+
+```markdown
+# Preferences
+
+| Setting | Value |
+| --- | --- |
+| Verbosity | detailed |
+| Proactive guidance | yes |
+```
+
+#### What Profile-as-Memory Eliminates
+
+Storing profile data in the memory system instead of a separate JSON file removes:
+
+- The `.claude/profile.json` file entirely
+- A separate JSON schema to maintain
+- A separate read path at session start -- profile and memory index are unified under `memory/index.md`
+- Onboarding questions baked into `CLAUDE.md` that write JSON -- `/meta init` writes markdown instead
+
+### Root Index
+
+`memory/index.md` is the only file read at session start. It lists all topics with their last-updated dates, giving the agent enough context to know what has been recorded without loading any detail.
+
+```markdown
+# Project Memory
+
+Agent-maintained cross-session knowledge base. Updated automatically.
+
+| Entry | Topic | Last Updated |
+| --- | --- | --- |
+| [profile/](profile/index.md) | Developer profile (skills, identity, preferences) | 2026-02-25 |
+| [deployment-state.md](deployment-state.md) | Deploy history, resource inventory, org info | 2026-02-25 |
+| [environment.md](environment.md) | Credentials, API keys, env vars | 2026-02-25 |
+| [decisions.md](decisions.md) | Architectural decisions and patterns | 2026-02-26 |
+| [errors/](errors/index.md) | Error patterns by category | 2026-02-26 |
+```
+
+Subdirectory entries link to their `index.md` rather than the directory itself.
+
+### Deployment State
+
+`deployment-state.md` tracks the most recent deploy and resource inventory. The agent updates it after every successful deployment.
+
+```markdown
+# Deployment State
+
+## Latest Deploy
+
+| Field | Value |
+| --- | --- |
+| Date | 2026-02-26 |
+| Deploy ID | dep_abc123 |
+| Resource count | 2 |
+| Organization | acme-corp |
+
+## Resources
+
+- `echo` (workflow, dev) -- echoes input, starter resource
+- `lead-scorer` (workflow, production) -- scores leads from Attio
+
+## Deploy History
+
+| Date | Deploy ID | Resources | Status |
+| --- | --- | --- | --- |
+| 2026-02-26 | dep_abc123 | 2 | success |
+| 2026-02-25 | dep_xyz789 | 1 | success |
+```
+
+### Environment
+
+`environment.md` records discovered credentials and environment variable status. The agent updates it when credentials are confirmed via the command center or deployment output.
+
+### Decisions
+
+`decisions.md` captures architectural choices as a table: which tools were chosen, what patterns were established, and why. The agent adds a row when the user makes a significant decision during development.
+
+## Error Tracking
+
+Error tracking is the first memory topic to outgrow a flat file. It starts as a subdirectory with one file per error category.
+
+### Error Index
+
+`errors/index.md` provides a high-level summary of known error patterns by category. The agent reads this file (via the root index) at session start.
+
+```markdown
+# Error Patterns
+
+Error pattern tracking by category. Updated when errors are diagnosed and resolved.
+
+| Entry | Category | Patterns | Total Occurrences | Last Seen |
+| --- | --- | --- | --- | --- |
+| [deploy.md](deploy.md) | Deployment | 2 | 3 | 2026-02-26 |
+| [runtime.md](runtime.md) | Runtime | 1 | 1 | 2026-02-26 |
+| [typescript.md](typescript.md) | TypeScript | 1 | 2 | 2026-02-25 |
+```
+
+- **Patterns** -- count of unique error patterns in the category file
+- **Total Occurrences** -- sum of all occurrences across patterns
+- **Last Seen** -- most recent date any error in this category was seen
+
+### Category Files
+
+Each category file is a table of known error patterns with resolutions:
+
+```markdown
+# Deploy Errors
+
+| Last Seen | Error | Resolution | Occurrences |
+| --- | --- | --- | --- |
+| 2026-02-25 | `ELEVASIS_API_KEY not set` | Added key to `.env` | 2 |
+| 2026-02-26 | `Schema validation: missing outputSchema` | Added Zod output schema to workflow | 1 |
+```
+
+Runtime errors include the resource name since the same error in different resources may have different causes:
+
+```markdown
+# Runtime Errors
+
+| Last Seen | Resource | Error | Resolution | Occurrences |
+| --- | --- | --- | --- | --- |
+| 2026-02-26 | lead-scorer | `PlatformToolError: credential not found` | Set credential via `elevasis env set` | 1 |
+```
+
+### Error Resolution Flow
+
+When the agent encounters an error, it follows this sequence:
+
+1. Checks `memory/errors/index.md` (already loaded via root index) for a matching category
+2. If the relevant category has known patterns, reads the category file
+3. If a match exists, applies the known resolution immediately -- "I've seen this before, here's the fix"
+4. If no match exists, diagnoses normally, then logs the new pattern
+
+When the agent logs a resolved error:
+
+1. Reads the relevant category file (e.g., `memory/errors/deploy.md`)
+2. If the pattern already exists, increments `Occurrences` and updates `Last Seen`
+3. If it is a new pattern, adds a new row
+4. Updates the error index: recalculates `Patterns`, `Total Occurrences`, and `Last Seen`
+5. If the category file does not exist yet, creates it and adds a row to the error index
+
+## Scaling Rule
+
+When a file has grown past usefulness as a single document -- too many rows to scan, too many unrelated concerns, or too much context to load for a targeted lookup -- split it into a subdirectory.
+
+**Before split:**
+
+```
+memory/
+├── index.md
+└── deployment-state.md         # entry: deployment-state.md
+```
+
+**After split:**
+
+```
+memory/
+├── index.md                    # entry updated: deployment-state/ -> deployment-state/index.md
+└── deployment-state/
+    ├── index.md
+    ├── resources.md
+    └── history.md
+```
+
+The parent index link changes from `deployment-state.md` to `deployment-state/index.md`. The new sub-index maps to the sub-files. The agent applies this pattern at every depth level.
+
+## Maintenance
+
+### Pruning
+
+Keep content useful, not exhaustive:
+
+- Keep the most recent ~20 entries in tables that grow over time (deploy history, error patterns)
+- Drop patterns that have not recurred in 30 or more days unless the resolution was non-obvious
+- Summarize if patterns are worth preserving but detail is not
+
+### Index Hygiene
+
+- If a file exists but is not in its parent index, add it
+- If an index references a missing file, remove the row
+
+The agent self-heals on read. Index hygiene is applied as part of normal session operation.
+
+### Promotion
+
+If an error pattern recurs 3 or more times, promote it to a rule in the `CLAUDE.md` Rules section. Rules prevent errors rather than diagnosing them.
+
+## Relationship to Claude Code Auto-Memory
+
+Claude Code maintains its own auto-memory at `~/.claude/projects/{hash}/memory/MEMORY.md`. Project memory is complementary, not a replacement.
+
+| Aspect | Auto-Memory (`MEMORY.md`) | Project Memory (`.claude/memory/`) |
+| --- | --- | --- |
+| Maintained by | Claude Code platform | CLAUDE.md instructions |
+| Scope | Organic discoveries | Explicit project state |
+| Portability | Machine-specific | Gitignored (personal to each developer) |
+| Content | General patterns | Deployment state, resources, credentials, errors |
+| User control | Implicit | Explicit (can read, edit, delete) |
+| Session load cost | Full file (truncated at 200 lines) | Root index only (~5 lines); detail on-demand |
+| Scaling | Single file, truncated | Hierarchical tree, unlimited depth |
+
+Both should be active. Auto-memory captures things the agent notices organically. Project memory captures structured project state that `CLAUDE.md` explicitly instructs the agent to record.
+
+---
+
+**Last Updated:** 2026-02-25

package/reference/framework/project-structure.mdx

@@ -0,0 +1,294 @@
+---
+title: Project Structure
+description: Each file scaffolded by elevasis init and its purpose in the development workflow
+loadWhen: "Understanding scaffolded files or project layout"
+---
+
+`elevasis init` creates a complete workspace structure. This page explains what each file does and when you will interact with it.
+
+---
+
+## Source Files
+
+### `src/index.ts`
+
+The registry entry point for your workspace. This file imports and re-exports all resources from `src/workflows/` as an `OrganizationResources` default export. It does not contain workflow logic itself -- its sole job is aggregation:
+
+```ts
+import type { OrganizationResources } from '@elevasis/sdk'
+import { echo } from './workflows/echo.js'
+
+const org: OrganizationResources = {
+  workflows: [echo],
+}
+export default org
+```
+
+Every resource you add is wired into this file. The `/resource workflow` command updates it automatically.
+
+### `src/workflows/echo.ts`
+
+The starter workflow, scaffolded to demonstrate the per-file pattern: one workflow per file with its own Zod input/output schemas, config object, contract, and step handler. When you add new workflows, each one gets its own file in `src/workflows/` and is imported into `src/index.ts`.
+
+### `elevasis.config.ts`
+
+Project-level configuration. The scaffolded file includes `templateVersion`, which tracks which template generation your project uses, plus commented-out options (`defaultStatus`, `dev.port`) so you can discover available settings without looking them up:
+
+```ts
+import type { ElevasConfig } from '@elevasis/sdk'
+
+export default {
+  templateVersion: 4,
+  // defaultStatus: 'dev',     // Default status for new resources ('dev' | 'production')
+  // dev: { port: 5170 },      // Local API port (internal development only)
+} satisfies ElevasConfig
+```
+
+Leave this file minimal -- the platform provides sensible defaults. Do not remove `templateVersion`; it is read by `elevasis update` to determine which template changes need to be applied to your project.
+
+---
+
+## Documentation
+
+### `docs/index.mdx`
+
+The entry point for your workspace's documentation. Documentation files in `docs/` are deployed alongside your code during `elevasis deploy` and rendered in the Elevasis platform UI.
+
+Use MDX frontmatter to set page metadata:
+
+```yaml
+---
+title: Overview
+description: Documentation for this project
+order: 0
+---
+```
+
+Add more pages by creating additional `.mdx` files in `docs/`. Nested directories create sections: `docs/guides/setup.mdx` becomes a `guides/setup` page under your deployment's documentation.
+
+### `docs/navigation.mdx`
+
+Auto-generated on the first `/meta deploy` and regenerated after each subsequent deploy. Contains a table of all deployed resources (resourceId, name, tools used, schema fields) and an index of all documentation pages. The agent reads this file during navigation to understand the current state of your workspace. You can also read it for a quick project overview.
+
+This file is MANAGED -- `elevasis update` ensures it exists but does not overwrite it. The actual content is generated by `/meta deploy`.
+
+### `docs/priorities.mdx`
+
+Created by the agent during your first goal discussion. Records current goals, priorities, and next steps for the workspace. Updated as goals change across sessions.
+
+This file is NOT scaffolded by default. The agent creates it the first time you discuss project goals or priorities in a session.
+
+### `docs/in-progress/`
+
+Work-in-progress documentation created by `/docs checkpoint`. Each file represents an active work item with current state, decisions made, and remaining tasks. `/docs cleanup` moves completed items to their final location in `docs/`. `/docs resume` reviews these files at session start.
+
+This directory is NOT deployed -- it is filtered out during the doc scan in `elevasis deploy`.
+
+---
+
+## Progressive Disclosure Directories
+
+Only `src/` and `docs/` are scaffolded by `elevasis init`. The following directories are NOT created by default -- they appear when a specific need arises:
+
+| Directory | Created by | When |
+|-----------|-----------|------|
+| `src/workflows/` | `elevasis init` (default) | Always -- starter workflow `echo.ts` lives here |
+| `docs/` | `elevasis init` (default) | Always |
+| `docs/in-progress/` | Agent (on first `/docs checkpoint`) | When you save work-in-progress across sessions |
+| `docs/navigation.mdx` | Agent (on first `/meta deploy`) | Auto-generated and updated on each deploy |
+| `docs/priorities.mdx` | Agent (on first goal discussion) | When you discuss project goals or priorities |
+| `data/` | `/database init` command | When you connect a database |
+| `scripts/` | Agent (on demand) | When you need local scripts not deployed to the platform |
+| `src/lib/` | Agent (on demand) | When shared code exists between two or more workflows |
+
+This structure keeps the initial workspace minimal and adds directories only when they earn their place.
+
+### `src/lib/`
+
+Shared TypeScript utilities, types, and helpers used by multiple workflows. The agent creates this directory when you have code shared between two or more workflow files -- for example, retry logic, formatters, or shared types. Included in the esbuild bundle alongside workflow code. Not scaffolded by default to avoid premature abstraction.
+
+### `data/`
+
+Created by `/database init`. Contains `schema.ts` which documents your database schema as TypeScript types. The agent reads this file to understand your data model when writing workflow steps that call the Supabase tool. Not deployed -- it is local documentation for the agent.
+
+### `scripts/`
+
+Local utility scripts for tasks that do not run on the platform: database seeds, data migrations, one-off transformations, local testing helpers. Created on demand when you need a local script. Not deployed, not bundled.
+
+---
+
+## `elevasis deploy` Scope
+
+`elevasis deploy` touches only two directories:
+
+| Directory | Action | Deployed? |
+|-----------|--------|-----------|
+| `src/` | Bundle into `dist/bundle.js` via esbuild (includes `src/lib/` if present) | Yes |
+| `docs/` | Scan `.mdx` files, upload as documentation | Yes |
+| `docs/in-progress/` | Ignored -- work-in-progress, not deployed | No |
+| `data/` | Ignored -- local documentation for the agent | No |
+| `scripts/` | Ignored -- local scripts, not deployed | No |
+| `.claude/` | Ignored -- local development only | No |
+
+---
+
+## Configuration Files
+
+### `.env`
+
+Contains your `ELEVASIS_API_KEY`. This file is gitignored. Never commit it.
+
+### `.env.example`
+
+A git-safe template showing which variables are needed:
+
+```
+ELEVASIS_API_KEY=sk_your_key_here
+```
+
+Commit this file so collaborators know what to configure.
+
+### `.npmrc`
+
+Sets `auto-install-peers = true`. The SDK uses Zod as a peer dependency, so this ensures Zod installs automatically.
+
+### `tsconfig.json`
+
+App-focused TypeScript configuration. It does not include `declaration` or `declarationMap` settings because your project is a deployable application, not a library.
+
+### `.gitignore`
+
+Pre-configured to exclude:
+- `node_modules/` -- installed packages
+- `.env` -- API key
+- `dist/` -- generated by deploy, never commit
+- `__elevasis_worker.ts` -- temporary file generated during deployment
+- `.claude/settings.local.json` -- local Claude Code overrides
+- `.claude/memory/` -- your personal cross-session project memory (profile, errors, decisions)
+
+---
+
+## Claude Code Integration
+
+The `.claude/` directory and `CLAUDE.md` give Claude Code full awareness of the SDK, CLI, and your project structure from the first session.
+
+### `CLAUDE.md`
+
+The most important file for AI-assisted development. It provides Claude Code with:
+
+- **Project orientation** -- what an Elevasis SDK project is and how it works
+- **Project structure** -- which files contain resources, documentation, and configuration
+- **SDK patterns** -- working code examples for resource definitions, Zod schemas, and the `OrganizationResources` export
+- **CLI reference** -- all commands with flags (`check`, `deploy`, `exec`, `resources`, `executions`, `execution`, `deployments`, `env list/set/remove`)
+- **Development rules** -- conventions the agent should enforce (source in `src/`, docs in `docs/`, use `@elevasis/sdk` types only)
+
+Do not remove or heavily edit `CLAUDE.md`. It is the primary context source that makes the slash commands work well.
+
+### `.claude/settings.json`
+
+Sets `autoCompact: false`. This prevents Claude Code from automatically compacting context during long sessions, which can lose important earlier context about your project.
+
+### `.claude/memory/`
+
+Created when you run `/meta init` in Claude Code. The agent asks six onboarding questions about your organization, project goals, integrations, and experience level. Answers are stored here as markdown files and used to personalize subsequent sessions.
+
+```
+.claude/memory/
+├── index.md                    # Root index linking all memory topics
+├── profile/                    # Developer profile (created by /meta init)
+│   ├── index.md
+│   ├── identity.md             # Organization, goals, integrations
+│   ├── skills.md               # TypeScript level, automation experience
+│   └── preferences.md          # Verbosity and guidance style
+├── deployment-state.md         # Latest deployment outcomes
+├── decisions.md                # Architecture decisions recorded over time
+└── errors/                     # Error patterns and resolutions
+```
+
+This directory is gitignored -- it is personal to you and not shared with collaborators. All cross-session knowledge (profile, errors, deployment state, decisions) lives here as plain markdown.
+
+---
+
+## Slash Commands
+
+The `.claude/commands/` directory contains nine commands covering the core development loop. Invoke them in Claude Code with `/docs`, `/resource`, `/profile`, `/meta`, `/help`, `/database`, `/agent`, `/templates`, and `/tutorial`.
+
+### `/docs` -- Documentation Lifecycle
+
+Manages documentation creation and maintenance for `docs/`. Six operations:
+
+- **No arguments** -- Show current documentation status: pages in progress, recent changes, and stale entries flagged for review
+- **`create <page-name>`** -- Scaffold a new documentation page with correct frontmatter, populated from your resource definitions
+- **`checkpoint`** -- Save current work progress for session resume. Creates or updates `docs/in-progress/` with current state, decisions made, remaining work, and blockers
+- **`cleanup`** -- Move completed documents from `docs/in-progress/` to their final location. Rebuilds `docs/navigation.mdx`
+- **`resume`** -- Start-of-session review of in-progress docs, priorities, and recent deployment state
+- **`verify`** -- Cross-reference documentation with the codebase. Reports discrepancies against actual resource IDs, schema fields, and platform tools
+
+### `/resource` -- Resource Scaffolding
+
+Scaffolds new workflow definitions with proper types, Zod schemas, and step structure. Three operations:
+
+- **`workflow <name>`** -- Single-step workflow with Zod input/output schemas, config object, contract, step handler, and addition to the `OrganizationResources` export
+- **`multi-step <name>`** -- Multi-step workflow with `StepType.LINEAR` or `StepType.CONDITIONAL`, connected steps, and per-step schemas
+- **`tool-step <name>`** -- Step that calls a platform tool via `platform.call()` with `PlatformToolError` error handling and a credential note
+
+### `/meta` -- Project Lifecycle
+
+Manages the full lifecycle of your workspace. Seven operations:
+
+- **`init`** -- First-run guided setup: installs dependencies, configures `.env`, runs onboarding to build your developer profile in `.claude/memory/`, and optionally deploys the starter workflow. Run this once after `elevasis init`
+- **No arguments** -- Project health status: shows template version, SDK version, profile summary, and a quick drift check for missing files
+- **`update`** -- Full upgrade flow: runs `pnpm update @elevasis/sdk`, then `elevasis update` to add missing files, then reviews and merges any flagged template changes with your customizations intact
+- **`fix`** -- Repairs drift without a version upgrade: restores missing command files, appends missing `.gitignore` entries, verifies CLAUDE.md sections, and checks memory structure consistency
+- **`deploy`** -- Full 9-step deploy pipeline: validate, type-check, verify docs, commit, deploy, bump version, verify platform, update deployment state, and optionally push
+- **`health`** -- Execution debugging and resource status; shows recent executions, analyzes failures, and checks environment connectivity
+- **`develop`** -- Development navigation hub that loads the resource map, SDK reference, and project state
+
+### `/templates` -- Workflow Templates
+
+Applies pre-built workflow templates to your workspace. Three operations:
+
+- **No arguments** -- List available template categories (Data Collection, Data Processing, Communication, CRM, Documents, AI, Scheduling)
+- **`<category>`** -- Show templates in a category with descriptions
+- **`apply <name>`** -- Generate a workflow from a template: writes to `src/workflows/`, wires into `src/index.ts`, prompts for credential setup if needed, and runs `elevasis check` to validate
+
+Templates are documentation files bundled with the SDK, not rigid copy-paste code. The agent reads the template and generates a workflow adapted to your existing schemas, credentials, and naming conventions.
+
+---
+
+## File Classification
+
+Not all scaffolded files participate in template updates. Files fall into two categories:
+
+**SCAFFOLD_FILES total: 23**
+
+**INIT_ONLY** (10 files) -- Written once during `elevasis init`, never updated by `elevasis update`:
+- `package.json`, `pnpm-workspace.yaml`, `tsconfig.json`
+- `.env`, `.env.example`, `.npmrc`
+- `src/index.ts`, `src/workflows/echo.ts`, `docs/index.mdx`, `.claude/settings.json`
+
+**MANAGED** (13 files) -- Written during `elevasis init` and checked/updatable by `elevasis update`:
+- `elevasis.config.ts`, `.gitignore`, `CLAUDE.md`, `docs/navigation.mdx`
+- All nine command files: `docs.md`, `resource.md`, `profile.md`, `meta.md`, `help.md`, `database.md`, `agent.md`, `templates.md`, `tutorial.md`
+
+Run `elevasis update` after installing a new SDK version to bring managed files up to date. The command adds missing files directly and flags files that differ from the new template for agent-assisted review via `/meta update`.
+
+---
+
+## File Reference
+
+| File | When You Edit It |
+|------|-----------------|
+| `src/index.ts` | Adding or removing resources (the `/resource` command does this automatically) |
+| `src/workflows/*.ts` | Writing and modifying workflow logic |
+| `docs/index.mdx` | Updating project documentation |
+| `docs/navigation.mdx` | Never -- auto-generated by `/meta deploy` |
+| `docs/priorities.mdx` | When goals or priorities change |
+| `elevasis.config.ts` | Changing project-level settings |
+| `.env` | Adding environment variables |
+| `CLAUDE.md` | Rarely -- only to add project-specific context |
+| `.claude/commands/*.md` | Rarely -- commands work well as scaffolded |
+
+---
+
+**Last Updated:** 2026-02-26