@elevasis/sdk 1.20.2 → 1.22.0

package/reference/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'
-import { resourceGovernanceModel } 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',
-  organizationModel: resourceGovernanceModel,
-  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
+---
+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'
+import { resourceGovernanceModel } 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',
+  organizationModel: resourceGovernanceModel,
+  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