@elevasis/sdk 1.30.2 → 1.32.0

package/reference/sdk/framework/project-structure.mdx

@@ -1,282 +1,282 @@
----
-title: Project Structure
-description: Each file scaffolded by elevasis-sdk init and its purpose in the development workflow
-loadWhen: "Understanding scaffolded files or project layout"
----
-
-`elevasis-sdk init` creates a complete workspace structure. This page explains what each file does and when you will interact with it.
-
-The current full-stack scaffold uses a workspace layout with `ui/`, `operations/`, `core/`, and a root `docs/` directory. When older examples refer to `src/shared/`, read that as the current `core/` package for cross-runtime types, schemas, and organization-model configuration.
-
----
-
-## Source Files
-
-### `operations/src/index.ts`
-
-The registry entry point for your workspace. This file imports OM resource governance from `core/config/organization-model.ts`, aggregates executable resources from domain barrel files, and re-exports them as a `DeploymentSpec` default export. It does not contain workflow logic itself -- its sole job is assembly:
-
-```ts
-import type { DeploymentSpec } from '@elevasis/sdk'
+---
+title: Project Structure
+description: Each file in an Elevasis SDK project and its purpose in the development workflow
+loadWhen: "Understanding scaffolded files or project layout"
+---
+
+Your Elevasis SDK project includes a complete workspace structure. This page explains what each file does and when you will interact with it.
+
+The current full-stack scaffold uses a workspace layout with `ui/`, `operations/`, `core/`, and a root `docs/` directory. When older examples refer to `src/shared/`, read that as the current `core/` package for cross-runtime types, schemas, and organization-model configuration.
+
+---
+
+## Source Files
+
+### `operations/src/index.ts`
+
+The registry entry point for your workspace. This file imports OM resource governance from `core/config/organization-model.ts`, aggregates executable resources from domain barrel files, and re-exports them as a `DeploymentSpec` default export. It does not contain workflow logic itself -- its sole job is assembly:
+
+```ts
+import type { DeploymentSpec } from '@elevasis/sdk'
 import { organizationModel } from '@core/config/organization-model'
-import * as example from './example/index.js'
-import * as emailNotification from './email-notification/exports.js'
-
-const org: DeploymentSpec = {
-  version: '0.1.0',
+import * as example from './example/index.js'
+import * as emailNotification from './email-notification/exports.js'
+
+const org: DeploymentSpec = {
+  version: '0.1.0',
   organizationModel,
-  workflows: [...example.workflows, ...emailNotification.workflows],
-  agents: [...example.agents, ...emailNotification.agents]
-}
-export default org
-```
-
-Each domain directory exports `workflows` and `agents` arrays via an `index.ts` barrel. When you add a new domain, import it here and spread its arrays.
-
-### `operations/src/email-notification/index.ts`
-
-A multi-step workflow demonstrating real platform API usage. Sends an email notification using the `notifications` adapter and chains steps with `StepType.LINEAR`. Shows the pattern for workflows that use platform tool adapters and pass data between steps.
-
-### `operations/src/example/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. Replace this domain with your own when you're ready.
-
-### `core/`
-
-Cross-runtime types, schemas, constants, and organization-model configuration shared between the UI and operations packages. Put contracts here when both runtimes need the same validation or labels without depending on app-specific code. Resource descriptors live in `core/config/organization-model.ts`.
-
-### `operations/elevasis.config.ts`
-
-Project-level configuration. The scaffolded file includes commented-out options (`defaultStatus`, `dev.port`):
-
-```ts
-import type { ElevasConfig } from '@elevasis/sdk'
-
-export default {
-  // defaultStatus: 'dev',     // Default status for new resources ('dev' | 'prod')
-  // dev: { port: 5170 },      // Local API port (internal development only)
-} satisfies ElevasConfig
-```
-
----
-
-## Documentation
-
-### `docs/index.md`
-
-The entry point for your workspace's documentation. Documentation files in `docs/` are deployed alongside your code during `elevasis-sdk 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/project-map.mdx`
-
-Auto-generated by `elevasis-sdk deploy` on every deploy and by `/meta fix` step 8. Contains a full project snapshot: organization, SDK version, template version, last deploy date, source domains, resource tables (workflows and agents), documentation index, SDK reference summary, commands/rules/skills, memory system listing, and configuration state. The agent reads this file at session start for project orientation.
-
-This file is fully auto-generated -- do not edit manually. Changes are overwritten on the next 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 task documents managed by `/work`. Each file represents an active work item with objective, plan, progress markers, and resume context. This is separate from the Projects data model exposed through `elevasis-sdk project:*`. When all steps are complete, the agent suggests finalizing the task, which moves finished items to their permanent location in `docs/`.
-
-This directory is NOT deployed -- it is filtered out during the doc scan in `elevasis-sdk deploy`.
-
----
-
-## Progressive Disclosure Directories
-
-The following directories are included in the scaffold:
-
-| Directory                            | Created by      | When                                                               |
-| ------------------------------------ | --------------- | ------------------------------------------------------------------ |
-| `operations/src/example/`            | Scaffold        | Always -- echo starter workflow lives here (replace with your own) |
-| `operations/src/email-notification/` | Scaffold        | Always -- multi-step notification workflow example                 |
-| `core/`                              | Scaffold        | Always -- cross-runtime contracts, schemas, and organization model |
-| `ui/`                                | Scaffold        | Always -- React frontend application                               |
-| `docs/`                              | Scaffold        | Always                                                             |
-| `docs/in-progress/`                  | Agent           | When you create a task doc for in-progress work                    |
-| `docs/resources.md`                  | `/deploy` skill | Auto-generated on every deploy                                     |
-| `data/`                              | Agent           | When you connect a database                                        |
-| `scripts/`                           | Agent           | When you need local scripts not deployed to the platform           |
-| `operations/src/lib/`                | Agent           | 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.
-
-### `operations/src/lib/`
-
-Shared code directory for utilities used by multiple workflows within the operations package. In the current workspace scaffold, prefer the top-level `core/` package for cross-runtime contracts. Included in the esbuild bundle alongside workflow code.
-
-### `data/`
-
-Created by the agent when you connect a database. 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-sdk deploy` Scope
-
-`elevasis-sdk deploy` touches only two directories:
-
-| Directory           | Action                                                                               | Deployed? |
-| ------------------- | ------------------------------------------------------------------------------------ | --------- |
-| `operations/src/`   | Bundle into `dist/bundle.js` via esbuild (includes `operations/src/lib/` if present) | Yes       |
-| `docs/`             | Scan `.md` and `.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        |
-| `ui/`               | Ignored -- frontend application, deployed separately                                 | No        |
-
----
-
-## Configuration Files
-
-### `.env`
-
-Contains your `ELEVASIS_PLATFORM_KEY`. This file is gitignored. Never commit it.
-
-### `.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 descriptor-backed resource definitions, Zod schemas, and the `DeploymentSpec` 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`
-
-Configures Claude Code for the workspace: registers a PostToolUse formatting/type-check hook (runs after Write, Edit, and MultiEdit) and a PostToolUseFailure error recovery hook (runs after Bash failures).
-
-### `.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               # Skill dimensions and Growth Log
-│   └── 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/skills/` directory contains skills covering the core development loop:
-
-- **`/setup`** -- First-time project setup: placeholder replacement, deps, verification
-- **`/deploy`** -- Full deploy pipeline: test, build, commit, push
-- **`/elevasis`** -- SDK operations: check, deploy, exec
-- **`/work`** -- Task tracking across sessions: auto-detects intent (create, save, resume); suggests complete
-- **`/status`** -- Quick project health check
-- **`/save`** -- Auto-manage docs from conversation context
-- **`/explore`** -- Codebase exploration anchored to docs
-- **`/continue`** -- Resume in-progress work from docs
-- **`/project`** -- Routes project management to the canonical `elevasis-sdk project:*` commands
-- **`/dsp`** -- Parallel agent dispatch for implementation tasks
-- **`/sync`** -- Pull latest, wipe caches, fresh reinstall
-
-Boundary summary:
-
-- `/project` updates shared project records
-- `/work` manages docs-backed work tracking
-- `/adev` handles implementation and execution work
-
-For detailed command documentation, see [Agent System](agent).
-
----
-
-## File Classification
-
-Not all scaffolded files participate in template updates. Files fall into two categories:
-
-**SCAFFOLD_FILES total: 32**
-
-**INIT_ONLY** -- Written once during initial scaffold, never overwritten by updates:
-
-- `package.json`, `pnpm-workspace.yaml`, `tsconfig.json`
-- `.env`, `.npmrc`
-- `operations/src/index.ts`, `operations/src/email-notification/index.ts`, `operations/src/email-notification/exports.ts`, `operations/src/example/echo.ts`, `operations/src/example/index.ts`, `core/`
-- `docs/index.md`, `docs/in-progress/.gitkeep`
-
-**MANAGED** -- Written during initial scaffold and updated when the template evolves:
-
-- `operations/elevasis.config.ts`, `.gitignore`, `CLAUDE.md`, `.claude/settings.json`
-- Two hooks: `.claude/hooks/post-edit-validate.mjs`, `.claude/hooks/tool-failure-recovery.mjs`
-- Skills: `.claude/skills/work/SKILL.md`, `.claude/skills/elevasis/SKILL.md`, `.claude/skills/deploy/skill.md`, `.claude/skills/setup/SKILL.md`
-- Rule files: `.claude/rules/task-tracking.md`, `.claude/rules/platform.md`, `.claude/rules/error-handling.md`, `.claude/rules/docs.md`, `.claude/rules/execution.md`, `.claude/rules/observability.md`
-- One script: `.claude/scripts/statusline-command.js`
-
----
-
-## File Reference
-
-| File                            | When You Edit It                                                    |
-| ------------------------------- | ------------------------------------------------------------------- |
-| `operations/src/index.ts`       | Adding or removing resources                                        |
-| `operations/src/<domain>/*.ts`  | Writing and modifying workflow logic (organized by business domain) |
-| `docs/index.md`                 | Updating project documentation                                      |
-| `docs/resources.md`             | Never -- auto-generated by `/deploy` and `/elevasis deploy`         |
-| `operations/elevasis.config.ts` | Changing project-level settings                                     |
-| `.env`                          | Adding environment variables                                        |
-| `CLAUDE.md`                     | Rarely -- only to add project-specific context                      |
-| `.claude/skills/*/SKILL.md`     | Rarely -- skills work well as scaffolded                            |
-
----
-
-**Last Updated:** 2026-04-17
+  workflows: [...example.workflows, ...emailNotification.workflows],
+  agents: [...example.agents, ...emailNotification.agents]
+}
+export default org
+```
+
+Each domain directory exports `workflows` and `agents` arrays via an `index.ts` barrel. When you add a new domain, import it here and spread its arrays.
+
+### `operations/src/email-notification/index.ts`
+
+A multi-step workflow demonstrating real platform API usage. Sends an email notification using the `notifications` adapter and chains steps with `StepType.LINEAR`. Shows the pattern for workflows that use platform tool adapters and pass data between steps.
+
+### `operations/src/example/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. Replace this domain with your own when you're ready.
+
+### `core/`
+
+Cross-runtime types, schemas, constants, and organization-model configuration shared between the UI and operations packages. Put contracts here when both runtimes need the same validation or labels without depending on app-specific code. Resource descriptors live in `core/config/organization-model.ts`.
+
+### `operations/elevasis.config.ts`
+
+Project-level configuration. The scaffolded file includes commented-out options (`defaultStatus`, `dev.port`):
+
+```ts
+import type { ElevasConfig } from '@elevasis/sdk'
+
+export default {
+  // defaultStatus: 'dev',     // Default status for new resources ('dev' | 'prod')
+  // dev: { port: 5170 },      // Local API port (internal development only)
+} satisfies ElevasConfig
+```
+
+---
+
+## Documentation
+
+### `docs/index.md`
+
+The entry point for your workspace's documentation. Documentation files in `docs/` are deployed alongside your code during `elevasis-sdk 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/project-map.mdx`
+
+Auto-generated by `elevasis-sdk deploy` on every deploy and by `/meta fix` step 8. Contains a full project snapshot: organization, SDK version, template version, last deploy date, source domains, resource tables (workflows and agents), documentation index, SDK reference summary, commands/rules/skills, memory system listing, and configuration state. The agent reads this file at session start for project orientation.
+
+This file is fully auto-generated -- do not edit manually. Changes are overwritten on the next 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 task documents managed by `/work`. Each file represents an active work item with objective, plan, progress markers, and resume context. This is separate from the Projects data model exposed through `elevasis-sdk project:*`. When all steps are complete, the agent suggests finalizing the task, which moves finished items to their permanent location in `docs/`.
+
+This directory is NOT deployed -- it is filtered out during the doc scan in `elevasis-sdk deploy`.
+
+---
+
+## Progressive Disclosure Directories
+
+The following directories are included in the scaffold:
+
+| Directory                            | Created by      | When                                                               |
+| ------------------------------------ | --------------- | ------------------------------------------------------------------ |
+| `operations/src/example/`            | Scaffold        | Always -- echo starter workflow lives here (replace with your own) |
+| `operations/src/email-notification/` | Scaffold        | Always -- multi-step notification workflow example                 |
+| `core/`                              | Scaffold        | Always -- cross-runtime contracts, schemas, and organization model |
+| `ui/`                                | Scaffold        | Always -- React frontend application                               |
+| `docs/`                              | Scaffold        | Always                                                             |
+| `docs/in-progress/`                  | Agent           | When you create a task doc for in-progress work                    |
+| `docs/resources.md`                  | `/deploy` skill | Auto-generated on every deploy                                     |
+| `data/`                              | Agent           | When you connect a database                                        |
+| `scripts/`                           | Agent           | When you need local scripts not deployed to the platform           |
+| `operations/src/lib/`                | Agent           | 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.
+
+### `operations/src/lib/`
+
+Shared code directory for utilities used by multiple workflows within the operations package. In the current workspace scaffold, prefer the top-level `core/` package for cross-runtime contracts. Included in the esbuild bundle alongside workflow code.
+
+### `data/`
+
+Created by the agent when you connect a database. 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-sdk deploy` Scope
+
+`elevasis-sdk deploy` touches only two directories:
+
+| Directory           | Action                                                                               | Deployed? |
+| ------------------- | ------------------------------------------------------------------------------------ | --------- |
+| `operations/src/`   | Bundle into `dist/bundle.js` via esbuild (includes `operations/src/lib/` if present) | Yes       |
+| `docs/`             | Scan `.md` and `.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        |
+| `ui/`               | Ignored -- frontend application, deployed separately                                 | No        |
+
+---
+
+## Configuration Files
+
+### `.env`
+
+Contains your `ELEVASIS_PLATFORM_KEY`. This file is gitignored. Never commit it.
+
+### `.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 descriptor-backed resource definitions, Zod schemas, and the `DeploymentSpec` 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`
+
+Configures Claude Code for the workspace: registers a PostToolUse formatting/type-check hook (runs after Write, Edit, and MultiEdit) and a PostToolUseFailure error recovery hook (runs after Bash failures).
+
+### `.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               # Skill dimensions and Growth Log
+│   └── 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/skills/` directory contains skills covering the core development loop:
+
+- **`/setup`** -- First-time project setup: placeholder replacement, deps, verification
+- **`/deploy`** -- Full deploy pipeline: test, build, commit, push
+- **`/elevasis`** -- SDK operations: check, deploy, exec
+- **`/work`** -- Task tracking across sessions: auto-detects intent (create, save, resume); suggests complete
+- **`/status`** -- Quick project health check
+- **`/save`** -- Auto-manage docs from conversation context
+- **`/explore`** -- Codebase exploration anchored to docs
+- **`/continue`** -- Resume in-progress work from docs
+- **`/project`** -- Routes project management to the canonical `elevasis-sdk project:*` commands
+- **`/dsp`** -- Parallel agent dispatch for implementation tasks
+- **`/sync`** -- Pull latest, wipe caches, fresh reinstall
+
+Boundary summary:
+
+- `/project` updates shared project records
+- `/work` manages docs-backed work tracking
+- `/adev` handles implementation and execution work
+
+For detailed command documentation, see [Agent System](agent).
+
+---
+
+## File Classification
+
+Not all scaffolded files participate in template updates. Files fall into two categories:
+
+**SCAFFOLD_FILES total: 32**
+
+**INIT_ONLY** -- Written once during initial scaffold, never overwritten by updates:
+
+- `package.json`, `pnpm-workspace.yaml`, `tsconfig.json`
+- `.env`, `.npmrc`
+- `operations/src/index.ts`, `operations/src/email-notification/index.ts`, `operations/src/email-notification/exports.ts`, `operations/src/example/echo.ts`, `operations/src/example/index.ts`, `core/`
+- `docs/index.md`, `docs/in-progress/.gitkeep`
+
+**MANAGED** -- Written during initial scaffold and updated when the template evolves:
+
+- `operations/elevasis.config.ts`, `.gitignore`, `CLAUDE.md`, `.claude/settings.json`
+- Two hooks: `.claude/hooks/post-edit-validate.mjs`, `.claude/hooks/tool-failure-recovery.mjs`
+- Skills: `.claude/skills/work/SKILL.md`, `.claude/skills/elevasis/SKILL.md`, `.claude/skills/deploy/skill.md`, `.claude/skills/setup/SKILL.md`
+- Rule files: `.claude/rules/task-tracking.md`, `.claude/rules/platform.md`, `.claude/rules/error-handling.md`, `.claude/rules/docs.md`, `.claude/rules/execution.md`, `.claude/rules/observability.md`
+- One script: `.claude/scripts/statusline-command.js`
+
+---
+
+## File Reference
+
+| File                            | When You Edit It                                                    |
+| ------------------------------- | ------------------------------------------------------------------- |
+| `operations/src/index.ts`       | Adding or removing resources                                        |
+| `operations/src/<domain>/*.ts`  | Writing and modifying workflow logic (organized by business domain) |
+| `docs/index.md`                 | Updating project documentation                                      |
+| `docs/resources.md`             | Never -- auto-generated by `/deploy` and `/elevasis deploy`         |
+| `operations/elevasis.config.ts` | Changing project-level settings                                     |
+| `.env`                          | Adding environment variables                                        |
+| `CLAUDE.md`                     | Rarely -- only to add project-specific context                      |
+| `.claude/skills/*/SKILL.md`     | Rarely -- skills work well as scaffolded                            |
+
+---
+
+**Last Updated:** 2026-04-17

package/reference/sdk/framework/resource-documentation.mdx

@@ -8,12 +8,12 @@ loadWhen: "Working with resource documentation or the /docs command"
 
 ## Directory Structure
 
-Create `.mdx` files inside a `docs/` directory at your project root. `elevasis-sdk init` scaffolds a starter structure:
+Create `.mdx` files inside a `docs/` directory at your project root. Your Elevasis SDK project includes a starter structure:
 
 ```
 my-project/
 ├── docs/
-│   └── index.mdx          # Resource overview (scaffolded by init)
+│   └── index.mdx          # Resource overview (included by default)
 ├── src/
 │   └── index.ts            # Resource definitions
 └── elevasis.config.ts

package/reference/sdk/getting-started.mdx

@@ -1,23 +1,23 @@
 ---
 title: Getting Started
-description: Install the Elevasis SDK, scaffold a project, and run your first deployment
+description: Set up your Elevasis SDK project and run your first deployment
 ---
 
 **Prerequisites:** Node.js 20+ and pnpm (`npm install -g pnpm`).
 
-## Create a Project
+## Your Project
 
-Scaffold a new project and install dependencies:
+Your Elevasis project is a standalone git repo containing your platform workflows, frontend, and configuration. Clone the repo and install dependencies:
 
 ```bash
-pnpm dlx @elevasis/sdk init my-project
+git clone <your-project-repo-url>
 cd my-project
 pnpm install
 ```
 
-`pnpm dlx` downloads the SDK temporarily to run `elevasis-sdk init`, which scaffolds your project with a working echo workflow, TypeScript config, and Claude Code integration. `pnpm install` then installs the SDK and its dependencies locally -- after that, all `elevasis-sdk` commands work directly via the scripts in `package.json` or `pnpm exec elevasis-sdk <command>`.
+After `pnpm install`, all `elevasis-sdk` commands work via the scripts in `package.json` or `pnpm exec elevasis-sdk <command>`.
 
-The command scaffolds 30 files covering configuration, source, documentation, and Claude Code integration:
+The project ships with 30 files covering configuration, source, documentation, and Claude Code integration:
 
 ```
 my-project/
@@ -134,7 +134,7 @@ Replace `<execution-id>` with the ID returned from the executions list.
 - [CLI Reference](cli.mdx) -- Full command reference with flags
 - [Deployment](deployment/index.mdx) -- Deployment lifecycle and environment variables
 
-When a new SDK version is released, run `/meta fix` in Claude Code for an interactive upgrade that includes SDK update, drift repair, and documentation verification. Alternatively, run `elevasis-sdk update` from the terminal to update managed files (CLAUDE.md, slash commands, `.gitignore`) without agent interaction. To update the SDK package itself, run `pnpm update @elevasis/sdk`.
+When a new SDK version is released, run `/meta fix` in Claude Code for an interactive upgrade that includes SDK update, drift repair, and documentation verification. To update the SDK package itself directly, run `pnpm update @elevasis/sdk`.
 
 ---
 

package/reference/sdk/index.mdx

@@ -70,7 +70,7 @@ See [Platform Tools](platform-tools/index.mdx) for the full catalog, adapter ref
 - [Agent Configuration](framework/agent.mdx) - Agent capabilities, tool access, model config, and Claude Code integration patterns
 - [Memory](framework/memory.mdx) - Agent memory system, session state, developer profiles, and workspace conventions
 - [Interaction Guidance](framework/interaction-guidance.mdx) - Skill dimension adaptation rules for platform navigation, API integration, and automation concepts
-- [Tutorial System](framework/tutorial-system.mdx) - 21-item tutorial menu, skill-adaptive lesson variants, progress tracking, and module contents
+- [Tutorial System](framework/tutorial-system.mdx) - Two-track onboarding (8 vibe-coder + 19 technical lessons), skill-adaptive lesson variants, progress tracking, and module contents
 - [Resource Documentation](framework/resource-documentation.mdx) - Docs directory structure, frontmatter schema, size limits, deploy behavior, and /docs command reference
 
 ### Resources Subpages
@@ -85,6 +85,7 @@ See [Platform Tools](platform-tools/index.mdx) for the full catalog, adapter ref
 
 ### More
 
+- [Export Catalog](exports.mdx) - Auto-generated catalog of all published @elevasis/sdk subpath exports
 - [Troubleshooting](troubleshooting.mdx) - Static error catalog for CLI, deployment, schema, and runtime failures
 - [Roadmap](roadmap.mdx) - Planned features including error taxonomy, retry semantics, circuit breaker, and metrics