@elevasis/sdk 0.5.13 → 0.5.15

package/reference/framework/project-structure.mdx

@@ -1,298 +1,277 @@
----
-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.
-
----
-
-## Source Files
-
-### `src/index.ts`
-
-The registry entry point for your workspace. This file aggregates resources from domain barrel files and re-exports them 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 * as operations from './operations/index.js'
-import * as example from './example/index.js'
-
-const org: OrganizationResources = {
-  workflows: [
-    ...operations.workflows,
-    ...example.workflows,
-  ],
-  agents: [
-    ...operations.agents,
-    ...example.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. The `/resource workflow` command updates the appropriate domain barrel automatically.
-
-### `src/operations/platform-status.ts`
-
-A multi-step workflow demonstrating real platform API usage. Calls `platform.call({ tool: 'status', method: 'overview' })` to gather platform status data, then passes it to `platform.call({ tool: 'llm', method: 'generate' })` for a natural language summary. Shows the pattern for workflows that interact with platform tools and chain steps with `StepType.LINEAR`.
-
-### `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.
-
-### `src/shared/`
-
-Cross-domain shared types and utilities. This directory starts empty (`.gitkeep`). Place code here when two or more domains share the same utility -- for example, formatters, shared types, or notification helpers. Domain-specific shared code goes in `<domain>/shared/` instead.
-
-### `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: 14,
-  // 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-sdk 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-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 created by `/work create`. Each file represents an active work item with objective, plan, progress markers, and resume context. `/work complete` 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
-
-Only `src/` and `docs/` are scaffolded by `elevasis-sdk init`. The following directories are NOT created by default -- they appear when a specific need arises:
-
-| Directory | Created by | When |
-|-----------|-----------|------|
-| `src/operations/` | `elevasis-sdk init` (default) | Always -- platform-status workflow lives here |
-| `src/example/` | `elevasis-sdk init` (default) | Always -- echo starter workflow lives here (replace with your own) |
-| `src/shared/` | `elevasis-sdk init` (default) | Always -- cross-domain shared utilities (starts empty) |
-| `docs/` | `elevasis-sdk init` (default) | Always |
-| `docs/in-progress/` | Agent (on first `/work create`) | When you create a task doc for in-progress work |
-| `docs/project-map.mdx` | `elevasis-sdk deploy` | Auto-generated on every deploy |
-| `docs/priorities.mdx` | Agent (on first goal discussion) | When you discuss project goals or priorities |
-| `data/` | Agent (on demand) | 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/`
-
-Legacy shared code directory. In v5+ projects, use `src/shared/` for cross-domain utilities instead. The agent may still create `src/lib/` in older projects that predate the domain-based organization. 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? |
-|-----------|--------|-----------|
-| `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.
-
-### `.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               # 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/commands/` directory contains four commands covering the core development loop. Invoke them in Claude Code with `/meta`, `/docs`, `/work`, and `/tutorial`.
-
-### `/meta` -- Project Lifecycle
-
-Manages the full lifecycle of your workspace. Five operations:
-
-- **`init`** -- First-run guided setup: installs dependencies, configures `.env`, runs competency assessment to build your developer profile in `.claude/memory/`, and optionally deploys the starter workflow. Triggered automatically by the `<!-- initialized: false -->` flag in CLAUDE.md.
-- **No arguments** -- Project health status: shows template version, SDK version, profile summary, last deployment status, and a quick drift check for missing files.
-- **`fix`** -- SDK upgrade check and full drift repair. Step 0 offers to run `pnpm update @elevasis/sdk` and merge template changes. Steps 1-8 repair drift: missing managed files, gitignore entries, CLAUDE.md sections, memory structure, doc cross-references, settings, rules health, and project map freshness.
-- **`deploy`** -- Full 9-step deploy pipeline: validate, type-check, verify docs, commit, deploy (auto-regenerates `docs/project-map.mdx`), verify platform, update deployment state, and optionally push.
-- **`health`** -- Execution debugging and resource status; shows recent executions, analyzes failures, and checks environment connectivity.
-
-### `/docs` -- Documentation
-
-Manages the permanent `docs/` tree. Three operations:
-
-- **No arguments** -- Browse. Lists user-maintained docs with auto-generated files (`project-map.mdx`, `resource-map.mdx`) shown as read-only. Pick a number to read and discuss.
-- **`create [description]`** -- Interview-driven reference doc creation. If the doc is about a specific resource, the agent reads `src/` and pre-populates from code. Scaffolds sections by doc type (resource guide, integration guide, architecture notes, process doc, general reference).
-- **`verify [file?]`** -- Interactive standalone docs verification. Cross-references resource IDs, schema fields, and platform tools in docs against `src/`. Guides fixes interactively.
-
-### `/work` -- Task Tracking
-
-Manages in-progress task tracking across sessions using `docs/in-progress/` task documents. Five operations:
-
-- **No arguments** -- List all task documents sorted by status.
-- **`create <description>`** -- Create a new task document with Objective, Plan, Progress, and Resume Context sections.
-- **`save`** -- Update the current task document with progress made this session.
-- **`resume [<name>]`** -- Load a task document and continue from where it left off.
-- **`complete`** -- Mark the current task as complete.
-
-### `/tutorial` -- Progressive Learning
-
-A 7-lesson guided learning path adapted to the user's skill profile. Lessons cover project orientation, writing workflows, schemas, platform tools, multi-step workflows, conditional routing, and production deployment.
-
----
-
-## File Classification
-
-Not all scaffolded files participate in template updates. Files fall into two categories:
-
-**SCAFFOLD_FILES total: 29**
-
-**INIT_ONLY** (14 files) -- Written once during `elevasis-sdk init`, never updated by `elevasis-sdk update`:
-- `package.json`, `pnpm-workspace.yaml`, `tsconfig.json`
-- `.env`, `.npmrc`
-- `src/index.ts`, `src/operations/platform-status.ts`, `src/operations/index.ts`, `src/example/echo.ts`, `src/example/index.ts`, `src/shared/.gitkeep`
-- `docs/index.mdx`, `docs/in-progress/.gitkeep`
-- `.claude/rules/workspace-patterns.md`
-
-**MANAGED** (15 files) -- Written during `elevasis-sdk init` and checked/updatable by `elevasis-sdk update`:
-- `elevasis.config.ts`, `.gitignore`, `CLAUDE.md`, `.claude/settings.json`
-- One hook: `.claude/hooks/enforce-sdk-boundary.mjs`
-- Four command files: `.claude/commands/meta.md`, `.claude/commands/docs.md`, `.claude/commands/tutorial.md`, `.claude/commands/work.md`
-- One skill: `.claude/skills/creds/SKILL.md`
-- Five rule files: `.claude/rules/sdk-patterns.md`, `.claude/rules/docs-authoring.md`, `.claude/rules/memory-conventions.md`, `.claude/rules/project-map.md`, `.claude/rules/task-tracking.md`
-
-Run `elevasis-sdk 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 fix`.
-
----
-
-## File Reference
-
-| File | When You Edit It |
-|------|-----------------|
-| `src/index.ts` | Adding or removing resources (the `/resource` command does this automatically) |
-| `src/<domain>/*.ts` | Writing and modifying workflow logic (organized by business domain) |
-| `docs/index.mdx` | Updating project documentation |
-| `docs/project-map.mdx` | Never -- auto-generated by `elevasis-sdk 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-03-03
+---
+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.
+
+---
+
+## Source Files
+
+### `src/index.ts`
+
+The registry entry point for your workspace. This file aggregates resources from domain barrel files and re-exports them 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 * as operations from './operations/index.js'
+import * as example from './example/index.js'
+
+const org: OrganizationResources = {
+  workflows: [
+    ...operations.workflows,
+    ...example.workflows,
+  ],
+  agents: [
+    ...operations.agents,
+    ...example.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. The `/resource workflow` command updates the appropriate domain barrel automatically.
+
+### `src/operations/platform-status.ts`
+
+A multi-step workflow demonstrating real platform API usage. Calls `platform.call({ tool: 'status', method: 'overview' })` to gather platform status data, then passes it to `platform.call({ tool: 'llm', method: 'generate' })` for a natural language summary. Shows the pattern for workflows that interact with platform tools and chain steps with `StepType.LINEAR`.
+
+### `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.
+
+### `src/shared/`
+
+Cross-domain shared types and utilities. This directory starts empty (`.gitkeep`). Place code here when two or more domains share the same utility -- for example, formatters, shared types, or notification helpers. Domain-specific shared code goes in `<domain>/shared/` instead.
+
+### `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: 28,
+  // defaultStatus: 'dev',     // Default status for new resources ('dev' | 'prod')
+  // 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-sdk 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-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 created by `/work create`. Each file represents an active work item with objective, plan, progress markers, and resume context. `/work complete` 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
+
+Only `src/` and `docs/` are scaffolded by `elevasis-sdk init`. The following directories are NOT created by default -- they appear when a specific need arises:
+
+| Directory              | Created by                       | When                                                               |
+| ---------------------- | -------------------------------- | ------------------------------------------------------------------ |
+| `src/operations/`      | `elevasis-sdk init` (default)    | Always -- platform-status workflow lives here                      |
+| `src/example/`         | `elevasis-sdk init` (default)    | Always -- echo starter workflow lives here (replace with your own) |
+| `src/shared/`          | `elevasis-sdk init` (default)    | Always -- cross-domain shared utilities (starts empty)             |
+| `docs/`                | `elevasis-sdk init` (default)    | Always                                                             |
+| `docs/in-progress/`    | Agent (on first `/work create`)  | When you create a task doc for in-progress work                    |
+| `docs/project-map.mdx` | `elevasis-sdk deploy`            | Auto-generated on every deploy                                     |
+| `docs/priorities.mdx`  | Agent (on first goal discussion) | When you discuss project goals or priorities                       |
+| `data/`                | Agent (on demand)                | 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/`
+
+Legacy shared code directory. In v5+ projects, use `src/shared/` for cross-domain utilities instead. The agent may still create `src/lib/` in older projects that predate the domain-based organization. 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? |
+| ------------------- | ------------------------------------------------------------------------- | --------- |
+| `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_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 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`
+
+Configures Claude Code for the workspace: disables auto-compaction (prevents losing earlier context in long sessions) and registers three hooks -- a PreToolUse boundary hook, a PostToolUse formatting/type-check hook, and a PostToolUseFailure error recovery hook.
+
+### `.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/commands/` directory contains four commands covering the core development loop:
+
+- **`/meta`** -- Project lifecycle: init, status, fix, deploy, health
+- **`/docs`** -- Browse, create, and verify permanent documentation
+- **`/work`** -- Task tracking across sessions: list, create, save, resume, complete
+- **`/tutorial`** -- Progressive learning path adapted to your skill profile
+
+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** (14 files) -- Written once during `elevasis-sdk init`, never updated by `elevasis-sdk update`:
+
+- `package.json`, `pnpm-workspace.yaml`, `tsconfig.json`
+- `.env`, `.npmrc`
+- `src/index.ts`, `src/operations/platform-status.ts`, `src/operations/index.ts`, `src/example/echo.ts`, `src/example/index.ts`, `src/shared/.gitkeep`
+- `docs/index.mdx`, `docs/in-progress/.gitkeep`
+- `.claude/rules/workspace-patterns.md`
+
+**MANAGED** (18 files) -- Written during `elevasis-sdk init` and checked/updatable by `elevasis-sdk update`:
+
+- `elevasis.config.ts`, `.gitignore`, `CLAUDE.md`, `.claude/settings.json`
+- Three hooks: `.claude/hooks/enforce-sdk-boundary.mjs`, `.claude/hooks/post-edit-validate.mjs`, `.claude/hooks/tool-failure-recovery.mjs`
+- Four command files: `.claude/commands/meta.md`, `.claude/commands/docs.md`, `.claude/commands/tutorial.md`, `.claude/commands/work.md`
+- One skill: `.claude/skills/creds/SKILL.md`
+- Five rule files: `.claude/rules/sdk-patterns.md`, `.claude/rules/docs-authoring.md`, `.claude/rules/memory-conventions.md`, `.claude/rules/project-map.md`, `.claude/rules/task-tracking.md`
+- One script: `.claude/scripts/statusline-command.js`
+
+Run `elevasis-sdk 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 fix`.
+
+---
+
+## File Reference
+
+| File                    | When You Edit It                                                               |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| `src/index.ts`          | Adding or removing resources (the `/resource` command does this automatically) |
+| `src/<domain>/*.ts`     | Writing and modifying workflow logic (organized by business domain)            |
+| `docs/index.mdx`        | Updating project documentation                                                 |
+| `docs/project-map.mdx`  | Never -- auto-generated by `elevasis-sdk 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-03-03