@elevasis/sdk 1.5.2 → 1.5.3

package/dist/cli.cjs

@@ -43990,7 +43990,7 @@ function wrapAction(commandName, fn) {
 // package.json
 var package_default = {
   name: "@elevasis/sdk",
-  version: "1.5.2",
+  version: "1.5.3",
   description: "SDK for building Elevasis organization resources",
   type: "module",
   bin: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -44,7 +44,7 @@
     "tsup": "^8.0.0",
     "typescript": "5.9.2",
     "zod": "^4.1.0",
-    "@repo/core": "0.2.0",
+    "@repo/core": "0.2.1",
     "@repo/typescript-config": "0.0.0"
   },
   "scripts": {

package/reference/cli.mdx

@@ -402,23 +402,23 @@ elevasis-sdk describe onboard-client
 
 ---
 
-## elevasis-sdk env
+## elevasis-sdk creds
 
-Manage environment variables for your project.
+Manage credentials for your project.
 
 **Synopsis:**
 
 ```
-elevasis-sdk env list
-elevasis-sdk env set <key> <value>
-elevasis-sdk env remove <key>
+elevasis-sdk creds list
+elevasis-sdk creds set <key> <value>
+elevasis-sdk creds remove <key>
 ```
 
 **Behavior:**
 
-- `list` -- display all environment variables configured for the project
-- `set` -- add or update an environment variable
-- `remove` -- delete an environment variable
+- `list` -- display all credentials configured for the project
+- `set` -- add or update a credential
+- `remove` -- delete a credential
 
 **Flags:**
 
@@ -429,9 +429,9 @@ elevasis-sdk env remove <key>
 **Examples:**
 
 ```bash
-elevasis-sdk env list
-elevasis-sdk env set OPENAI_API_KEY sk-proj-***
-elevasis-sdk env remove OPENAI_API_KEY
+elevasis-sdk creds list
+elevasis-sdk creds set OPENAI_API_KEY sk-proj-***
+elevasis-sdk creds remove OPENAI_API_KEY
 ```
 
 ---
@@ -503,7 +503,7 @@ elevasis-sdk rename ist-upload-workflow --to ist-upload-contacts-workflow --exec
 
 ---
 
-## elevasis-sdk project:*
+## elevasis-sdk project:\*
 
 Project-management commands operate on the shared delivery system used by packaged Projects pages and task-oriented agent workflows.
 
@@ -566,10 +566,10 @@ elevasis-sdk project:note:delete <id>
 
 Most `project:*` commands support:
 
-| Flag | Description |
-| ---- | ----------- |
-| `--pretty` | Human-readable terminal output instead of raw JSON |
-| `--api-url <url>` | Override the API base URL |
+| Flag              | Description                                        |
+| ----------------- | -------------------------------------------------- |
+| `--pretty`        | Human-readable terminal output instead of raw JSON |
+| `--api-url <url>` | Override the API base URL                          |
 
 For exact required flags and accepted enum values, see the command source under `packages/sdk/src/cli/commands/project/`.
 

package/reference/deployment/index.mdx

@@ -37,7 +37,8 @@ elevasis-sdk deploy
   Uploading...               done
 
   Deployed! 4 resources live.
-  Deployment: deploy_abc123
+  Version:  v1.0.0
+  Duration: 4.2s
 ```
 
 Each deploy creates a new deployment record. The previous active deployment is automatically stopped. You can view all deployments with `elevasis-sdk deployments`.
@@ -62,9 +63,8 @@ The CLI validates your resources before bundling. Validation uses the same `Reso
   Authenticating...          done (acme-corp)
   Validating...
     ERROR  Duplicate resource ID 'onboard-client' in organization 'Acme Corp'
-    ERROR  Workflow step 'send-email' references non-existent next step 'notify'
 
-  2 errors. Deploy aborted.
+  Deploy aborted.
 ```
 
 Run `elevasis-sdk check` at any time to validate without deploying.
@@ -98,8 +98,9 @@ The CLI also accepts a `--api-url` flag on every command, which takes priority o
 **API URL resolution order:**
 
 1. `--api-url` flag (highest priority)
-2. `ELEVASIS_API_URL` environment variable
-3. `NODE_ENV`-based default (production: `https://api.elevasis.io`, development: localhost)
+2. `--prod` flag (forces production URL, overrides `NODE_ENV=development`)
+3. `ELEVASIS_API_URL` environment variable
+4. `NODE_ENV`-based default (production: `https://api.elevasis.io`, development: localhost)
 
 **Setting `ELEVASIS_PLATFORM_KEY` via `.env` file:**
 

package/reference/deployment/provided-features.mdx

@@ -4,7 +4,7 @@ description: Shared UI and API surfaces for packaged business systems like Lead
 loadWhen: "Building against packaged app features, list-oriented lead gen, CRM, or project-management surfaces"
 ---
 
-The SDK now covers more than raw workflow execution. The published `@elevasis/ui@2.7.0` package includes:
+The SDK now covers more than raw workflow execution. The published `@elevasis/ui@2.9.0` package includes:
 
 - manifest-backed shared features under `@elevasis/ui/features/<name>`
 - headless shell/provider exports under `@elevasis/ui/provider`
@@ -16,7 +16,7 @@ Use this page to understand what the shared shell actually owns, which surfaces
 
 ## Shared Shell Contract
 
-`ElevasisFeaturesProvider` and `FeatureShell` give you a shared manifest-driven shell layer, not a full application shell. In `2.7.0` they handle:
+`ElevasisFeaturesProvider` and `FeatureShell` give you a shared manifest-driven shell layer, not a full application shell. In `2.9.0` they handle:
 
 - feature registration
 - feature-gated nav contribution
@@ -79,27 +79,27 @@ Dashboard is not part of that shared manifest shell by default. `@elevasis/ui/fe
 
 ## Contract Matrix
 
-This is the published contract split in `@elevasis/ui@2.7.0`:
+This is the published contract split in `@elevasis/ui@2.9.0`:
 
-| Contract type | What is published | Current examples |
-| ------------- | ----------------- | ---------------- |
-| Manifest-backed shared subshell features | Feature manifest plus shared sidebar/pages, mounted through `@elevasis/ui/provider` | Lead Gen, CRM, Projects, Operations, SEO |
-| Manifest-backed nav/app sections | Feature manifest contributes gated nav and route metadata, but the host still owns the route pages or shell chrome | Monitoring, Settings |
-| Exported compatibility components | Reusable components exported without a manifest-backed shell contract | Dashboard components such as `Dashboard`, `OperationsOverview`, `ResourceOverview`, `RecentExecutionsByResource`, `UnresolvedErrorsTeaser` |
-| Compatibility barrel | Existing imports remain available from `@elevasis/ui/components`, but new host integrations should prefer feature/provider subpaths | Manifests, sidebars, and page components re-exported for compatibility |
+| Contract type                            | What is published                                                                                                                   | Current examples                                                                                                                           |
+| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Manifest-backed shared subshell features | Feature manifest plus shared sidebar/pages, mounted through `@elevasis/ui/provider`                                                 | Lead Gen, CRM, Projects, Operations, SEO                                                                                                   |
+| Manifest-backed nav/app sections         | Feature manifest contributes gated nav and route metadata, but the host still owns the route pages or shell chrome                  | Monitoring, Settings                                                                                                                       |
+| Exported compatibility components        | Reusable components exported without a manifest-backed shell contract                                                               | Dashboard components such as `Dashboard`, `OperationsOverview`, `ResourceOverview`, `RecentExecutionsByResource`, `UnresolvedErrorsTeaser` |
+| Compatibility barrel                     | Existing imports remain available from `@elevasis/ui/components`, but new host integrations should prefer feature/provider subpaths | Manifests, sidebars, and page components re-exported for compatibility                                                                     |
 
 Projects is currently the only packaged system with a first-class `elevasis-sdk project:*` CLI family. Lead Gen and CRM are still primarily UI + API + workflow/runtime surfaces, and browser-facing interactions remain REST-driven even when runtime tools exist.
 
 ## System Map
 
-| System | Primary route space | Shared UI surface | Main data surface | Best SDK entry point |
-| ------ | ------------------- | ----------------- | ----------------- | -------------------- |
-| Lead Gen | `/lead-gen/*` | Lead Gen pages, sidebars, list detail page, run dialogs | Acquisition list APIs + list/acqDb platform tools | `@elevasis/ui/features/lead-gen`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker` |
-| CRM | `/crm/*` | CRM sidebar, overview widgets, deal/detail pages, workbench panels | Deal APIs, recent-activity API, acquisition-backed hooks, and the `crm` runtime adapter | `@elevasis/ui/features/crm`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker` |
-| Projects | `/projects/*` | Projects list page, milestones/tasks/notes sidebars and pages | Project, milestone, task, note REST endpoints + CLI | `@elevasis/ui/features/delivery`, `@elevasis/ui/hooks/delivery`, `elevasis-sdk project:*` |
-| Dashboard | host-owned | Dashboard and overview components only; no shared manifest-backed nav contract | Host-chosen API composition | `@elevasis/ui/features/dashboard` |
-| Monitoring | `/monitoring/*` | Monitoring nav metadata plus exported pages/components; no shared `FeatureShell` sidebar today | Monitoring REST APIs | `@elevasis/ui/features/monitoring` |
-| Settings | `/settings/*` | Settings nav metadata plus exported settings components; no shared `FeatureShell` sidebar today | Settings/account/org REST APIs | `@elevasis/ui/features/settings` |
+| System     | Primary route space | Shared UI surface                                                                               | Main data surface                                                                       | Best SDK entry point                                                                      |
+| ---------- | ------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Lead Gen   | `/lead-gen/*`       | Lead Gen pages, sidebars, list detail page, run dialogs                                         | Acquisition list APIs + list/acqDb platform tools                                       | `@elevasis/ui/features/lead-gen`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker`            |
+| CRM        | `/crm/*`            | CRM sidebar, overview widgets, deal/detail pages, workbench panels                              | Deal APIs, recent-activity API, acquisition-backed hooks, and the `crm` runtime adapter | `@elevasis/ui/features/crm`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker`                 |
+| Projects   | `/projects/*`       | Projects list page, milestones/tasks/notes sidebars and pages                                   | Project, milestone, task, note REST endpoints + CLI                                     | `@elevasis/ui/features/delivery`, `@elevasis/ui/hooks/delivery`, `elevasis-sdk project:*` |
+| Dashboard  | host-owned          | Dashboard and overview components only; no shared manifest-backed nav contract                  | Host-chosen API composition                                                             | `@elevasis/ui/features/dashboard`                                                         |
+| Monitoring | `/monitoring/*`     | Monitoring nav metadata plus exported pages/components; no shared `FeatureShell` sidebar today  | Monitoring REST APIs                                                                    | `@elevasis/ui/features/monitoring`                                                        |
+| Settings   | `/settings/*`       | Settings nav metadata plus exported settings components; no shared `FeatureShell` sidebar today | Settings/account/org REST APIs                                                          | `@elevasis/ui/features/settings`                                                          |
 
 ---
 
@@ -131,17 +131,17 @@ The most important page for downstream agents is `LeadGenListDetailPage`. It com
 
 `@elevasis/ui/hooks` exposes list-aware hooks backed by the acquisition API:
 
-| Hook | HTTP path |
-| ---- | --------- |
-| `useLists()` | `GET /acquisition/lists` |
-| `useList(listId)` | `GET /acquisition/lists/:listId` |
-| `useListsTelemetry()` | `GET /acquisition/lists/telemetry` |
-| `useListProgress(listId)` | `GET /acquisition/lists/:listId/progress` |
-| `useListExecutions(listId)` | `GET /acquisition/lists/:listId/executions` |
-| `useCreateList()` | `POST /acquisition/lists` |
-| `useUpdateList(listId)` | `PATCH /acquisition/lists/:listId` |
-| `useUpdateListConfig(listId)` | `PATCH /acquisition/lists/:listId/config` |
-| `useDeleteList()` | `DELETE /acquisition/lists/:listId` |
+| Hook                          | HTTP path                                   |
+| ----------------------------- | ------------------------------------------- |
+| `useLists()`                  | `GET /acquisition/lists`                    |
+| `useList(listId)`             | `GET /acquisition/lists/:listId`            |
+| `useListsTelemetry()`         | `GET /acquisition/lists/telemetry`          |
+| `useListProgress(listId)`     | `GET /acquisition/lists/:listId/progress`   |
+| `useListExecutions(listId)`   | `GET /acquisition/lists/:listId/executions` |
+| `useCreateList()`             | `POST /acquisition/lists`                   |
+| `useUpdateList(listId)`       | `PATCH /acquisition/lists/:listId`          |
+| `useUpdateListConfig(listId)` | `PATCH /acquisition/lists/:listId/config`   |
+| `useDeleteList()`             | `DELETE /acquisition/lists/:listId`         |
 
 Lead Gen also sits on broader acquisition endpoints for companies and contacts:
 
@@ -247,16 +247,16 @@ Projects is the packaged delivery/project-management system. It has both a share
 
 `@elevasis/ui/hooks/delivery` talks to the project-management API:
 
-| Hook | HTTP path |
-| ---- | --------- |
-| `useProjects()` | `GET /projects` |
-| `useProject(id)` | `GET /projects/:id` |
-| `useTasks({ projectId })` | `GET /projects/:projectId/tasks` |
-| `useMilestones({ projectId })` | `GET /projects/:projectId/milestones` |
-| `useProjectNotes({ projectId })` | `GET /projects/:projectId/notes` |
-| `useCreateTask()` | `POST /project-tasks` |
-| `useUpdateTask()` | `PATCH /project-tasks/:id` |
-| `useCreateNote()` | `POST /project-notes` |
+| Hook                             | HTTP path                             |
+| -------------------------------- | ------------------------------------- |
+| `useProjects()`                  | `GET /projects`                       |
+| `useProject(id)`                 | `GET /projects/:id`                   |
+| `useTasks({ projectId })`        | `GET /projects/:projectId/tasks`      |
+| `useMilestones({ projectId })`   | `GET /projects/:projectId/milestones` |
+| `useProjectNotes({ projectId })` | `GET /projects/:projectId/notes`      |
+| `useCreateTask()`                | `POST /project-tasks`                 |
+| `useUpdateTask()`                | `PATCH /project-tasks/:id`            |
+| `useCreateNote()`                | `POST /project-notes`                 |
 
 ### CLI Surface
 

package/reference/deployment/ui-execution.mdx

@@ -88,9 +88,8 @@ import { useState } from 'react'
 import { Modal, Button, Text } from '@mantine/core'
 import { ResourceExecuteForm } from '@elevasis/ui/features/operations'
 import { useExecuteAsync } from '@elevasis/ui/hooks'
-import type { SerializedExecutionFormSchema } from '@elevasis/ui/hooks'
 
-const formSchema: SerializedExecutionFormSchema = {
+const formSchema = {
   fields: [
     { name: 'topic', label: 'Topic', type: 'text', required: true },
   ],

package/reference/framework/agent.mdx

@@ -40,67 +40,47 @@ At the start of every session the agent runs these steps silently before respond
 
 ## Slash Commands
 
-Slash commands are short Markdown instruction files in `.claude/commands/`. When you type `/command-name` in a Claude Code session, the agent reads the corresponding file and follows its instructions.
+Skills are Markdown instruction files in `.claude/skills/`. When you type `/skill-name` in a Claude Code session, the agent reads the corresponding `SKILL.md` and follows its instructions.
 
-Four commands and one skill are scaffolded by `elevasis-sdk init` and committed to version control so collaborators get the same experience:
+The following skills are scaffolded by `elevasis-sdk init` and committed to version control so collaborators get the same experience:
 
-| Command     | File          | Purpose                                                                          |
-| ----------- | ------------- | -------------------------------------------------------------------------------- |
-| `/meta`     | `meta.md`     | Project lifecycle -- init, status, fix (incl. docs verification), deploy, health |
-| `/docs`     | `docs.md`     | Browse, create, and verify permanent documentation                               |
-| `/work`     | `work.md`     | Task tracking -- list, create, save, resume, complete                            |
-| `/tutorial` | `tutorial.md` | Progressive learning path -- 3 tracks, menu-driven                               |
+| Skill       | File                       | Purpose                                                  |
+| ----------- | -------------------------- | -------------------------------------------------------- |
+| `/work`     | `skills/work/SKILL.md`     | Task tracking -- list, create, save, resume, complete    |
+| `/elevasis` | `skills/elevasis/SKILL.md` | SDK operations -- check, deploy, exec                    |
+| `/deploy`   | `skills/deploy/skill.md`   | Full deploy pipeline (test, build, commit, push)         |
+| `/setup`    | `skills/setup/SKILL.md`    | First-time project setup (placeholder replacement, deps) |
+| `/status`   | `skills/status/SKILL.md`   | Quick project health check                               |
+| `/continue` | `skills/continue/SKILL.md` | Resume in-progress work from docs                        |
+| `/project`  | `skills/project/SKILL.md`  | Client project management via elevasis-sdk               |
+| `/sync`     | `skills/sync/SKILL.md`     | Pull latest, wipe caches, fresh reinstall                |
+| `/explore`  | `skills/explore/SKILL.md`  | Codebase exploration anchored to docs                    |
+| `/save`     | `skills/save/SKILL.md`     | Auto-manage docs from conversation context               |
+| `/dsp`      | `skills/dsp/SKILL.md`      | Parallel agent dispatch for implementation tasks         |
 
-The `/creds` skill (`.claude/skills/creds/SKILL.md`) is also scaffolded. It auto-triggers when the agent detects credential-related context and manages credential storage and retrieval.
+### Key Skills
 
-### `/meta` Command
+**`/setup`** -- First-time project setup. Replaces template placeholders, installs dependencies, configures `.env`, verifies the project, and optionally runs a first deploy.
 
-The `/meta` command namespace manages the full project lifecycle. It has five operations:
+**`/deploy`** -- Full deploy pipeline: type-check, validate resources, commit, deploy (auto-regenerates `docs/index.md` and `docs/resources.md`), verify platform, and optionally push.
 
-- **`/meta init`** -- First-run guided setup. Runs after `elevasis-sdk init` to install dependencies, configure `.env`, run the competency assessment onboarding flow, seed `memory/profile/`, verify the project, and optionally do a first deploy.
-- **`/meta`** (no arguments) -- Project health status. Shows current template version, SDK version, profile summary, a quick drift check, and last deployment status.
-- **`/meta fix`** -- SDK upgrade check and 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.
-- **`/meta 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.
-- **`/meta health`** -- Execution debugging and resource status; shows recent executions, analyzes failures, and checks environment connectivity.
+**`/elevasis`** -- SDK operations entry point: `check` validates resource definitions, `deploy` bundles and uploads, `exec` runs a resource with input.
 
-### `/docs` Command
+**`/work`** -- File-based task lifecycle. Creates, resumes, saves, and completes task docs in `docs/in-progress/`. Intent-driven: the agent detects what to do from context.
 
-The `/docs` command manages the permanent `docs/` tree -- everything except `docs/in-progress/` (owned by `/work`) and auto-generated files (`project-map.mdx`, `resource-map.mdx`). Three operations:
+**`/status`** -- Quick project health check: shows SDK version, deployed resources, last deploy date, and environment status.
 
-- **`/docs`** (no arguments) -- Browse. Scans `docs/` recursively and displays a numbered list of user-maintained docs with auto-generated files shown separately as read-only. Pick a number to read and discuss, or say "create" or "verify."
-- **`/docs create [description]`** -- Interview-driven reference doc creation. If the doc is about a specific resource, the agent scans `src/` and pre-populates from code (config, schemas, step names, platform tools). Scaffolds sections appropriate to the doc type (resource guide, integration guide, architecture notes, process doc, or general reference).
-- **`/docs verify [file?]`** -- Interactive standalone version of `/meta fix` step 5. Cross-references resource IDs, schema fields, and platform tools in docs against `src/`. Shows a summary, then guides fixes interactively. Can be scoped to a single file.
+**`/save`** -- Auto-manages docs from conversation context: writes or updates docs based on what was discussed in the session.
 
-### `/work` Command
+**`/explore`** -- Codebase exploration anchored to `docs/`. Reads the doc map first, then drills into source as needed.
 
-The `/work` command manages in-progress task tracking across sessions. It uses `docs/in-progress/` for task documents with standardized frontmatter (`status: planned | in-progress | complete`).
+**`/continue`** -- Resumes in-progress work by reading `docs/in-progress/` and picking up where the last session left off.
 
-`/work` is intent-driven -- the agent detects what to do from context rather than requiring explicit subcommands:
+**`/project`** -- Client project management: milestones, tasks, and notes via `elevasis-sdk project` commands.
 
-- **`/work`** (no arguments) -- Lists tasks sorted by status (`in-progress` first) with last-saved date and current step. Pick by number or name to auto-resume, or describe new work to auto-create a task.
-- **Auto-create** -- When the user describes work that doesn't match an existing task, the agent creates a task doc automatically. If intent is clear, it skips the interview; if ambiguous, it asks 1-2 focused questions.
-- **Auto-save** -- The agent saves progress silently when the conversation context is getting heavy, the user is wrapping up, or 2+ steps have been completed without saving. Updates progress markers, files modified, and resume context.
-- **Auto-resume** -- When the user picks an existing task (by number, name, or keyword), the agent loads context and resumes automatically.
-- **Suggest complete** -- When all plan steps are marked COMPLETE, the agent suggests finalizing: "All steps for '`{task}`' look done. Want me to finalize it?" It never auto-invokes completion. The complete flow validates readiness, cleans the doc (strips resume context, removes progress markers, targets 200-400 lines), determines destination in `docs/`, confirms with user, moves, and verifies.
+**`/dsp`** -- Dispatches subagents in parallel for implementation tasks that can run concurrently.
 
-**Directory conventions for `docs/in-progress/`:**
-
-```
-docs/in-progress/
-├── crm-integration/
-│   ├── index.mdx          # Main task doc
-│   └── attio-schema.mdx   # Supporting analysis
-├── email-templates.mdx    # Small standalone task
-└── ui-dashboard/
-    ├── index.mdx          # Main task doc
-    └── component-list.mdx # Supporting analysis
-```
-
-The numbered list is derived from scanning this directory. `index.mdx` is treated as the primary task doc for a directory. On complete, destination in `docs/` is determined by scanning for related existing directories.
-
-### `/tutorial` Command
-
-The `/tutorial` command shows a track menu on every invocation and runs a progressive learning path adapted to the user's skill profile. Three tracks: Orchestration Concepts (7 lessons), Examples & Advanced Modules (9 standalone modules), and Meta-Framework (5 lessons). Two skill dimensions tracked: `automation` (none / low-code / custom) and `platformNavigation` (none / oriented / comfortable).
+**`/sync`** -- Pulls latest changes, wipes all `node_modules` and caches, and runs a fresh reinstall.
 
 ## Developer Profile
 
@@ -138,14 +118,26 @@ The agent does not prompt for confirmation on minor updates. Major changes (leve
 
 ## Rules System
 
-Six rule files are scaffolded in `.claude/rules/`. Rule files are auto-injected by Claude Code when their path patterns match the current file being edited -- no manual loading needed.
+Ten rule files are scaffolded in `.claude/rules/`. Rule files are auto-injected by Claude Code when their path patterns match the current file being edited -- no manual loading needed.
+
+Rules injected for operations source files (`operations/src/`):
+
+- **`platform.md`** -- SDK adapter patterns, typed adapters, platform tool usage.
+- **`error-handling.md`** -- Error types (`ExecutionError`, `PlatformToolError`), retry behavior.
+- **`execution.md`** -- Worker thread model, timeouts, concurrency, org isolation.
+- **`observability.md`** -- Logging with `context.logger`, step-level auto-logging, debugging.
+- **`deployment.md`** -- Deploy commands, dev vs prod, version bumping, common errors.
+
+Rules injected for docs files (`docs/`):
 
-The two files you will interact with directly:
+- **`docs.md`** -- Documentation structure, frontmatter conventions, auto-generated files.
+- **`task-tracking.md`** -- Task doc conventions, injected for in-progress files.
 
-- **`sdk-patterns.md`** (MANAGED) -- Injected when editing `src/`. Covers SDK imports, source structure, runtime, and typed adapter patterns. Updated by `elevasis-sdk update`.
-- **`workspace-patterns.md`** (INIT_ONLY) -- Injected project-wide. Starts empty; grows via error promotion (3+ recurrences of the same error become a rule). Never overwritten by updates.
+Additional contextual rules:
 
-Four additional MANAGED rules (`docs-authoring.md`, `memory-conventions.md`, `project-map.md`, `task-tracking.md`) are injected contextually for docs, memory, and task files. These are maintained by the SDK and require no user action.
+- **`frontend.md`** -- React/Mantine patterns, injected for UI source files.
+- **`shared-types.md`** -- Cross-runtime type conventions, injected for foundations files.
+- **`organization-os.md`** -- Organization model and feature shell conventions.
 
 ## Interaction Guidance
 

package/reference/framework/index.mdx

@@ -14,22 +14,25 @@ Running `elevasis-sdk init my-project` produces the following agent infrastructu
 
 ```
 .claude/
-├── settings.json               # autoCompact: false
-├── commands/
-│   ├── meta.md                 # Project lifecycle (init, fix, deploy, health)
-│   ├── docs.md                 # Browse, create, and verify permanent docs
-│   ├── tutorial.md             # Progressive learning path (3 tracks)
-│   └── work.md                 # Task tracking
+├── settings.json               # Hook registrations (PostToolUse, PostToolUseFailure)
 ├── hooks/
-│   └── enforce-sdk-boundary.mjs  # Blocks file modifications outside project boundary
+│   ├── post-edit-validate.mjs    # Formatting/type-check hook (after Write/Edit/MultiEdit)
+│   └── tool-failure-recovery.mjs # Error recovery hook (after Bash failures)
 ├── skills/
-│   └── creds/SKILL.md          # Credential management (auto-triggers)
+│   ├── work/SKILL.md           # Task tracking across sessions
+│   ├── elevasis/SKILL.md       # SDK operations (check, deploy, exec)
+│   ├── deploy/skill.md         # Deploy pipeline
+│   ├── setup/SKILL.md          # First-time project setup
+│   ├── status/SKILL.md         # Project health check
+│   └── ...                     # Additional skills (dsp, continue, project, sync, explore, save)
+├── scripts/
+│   └── statusline-command.js   # Status line command
 └── rules/
     ├── sdk-patterns.md         # SDK patterns (auto-loaded for src/ files)
     ├── docs-authoring.md       # MDX conventions (auto-loaded for docs/ files)
-    ├── memory-conventions.md   # Memory conventions (auto-loaded)
-    ├── project-map.md          # Project map conventions (auto-loaded)
     ├── task-tracking.md        # Task tracking conventions (auto-loaded)
+    ├── platform.md             # Platform tool patterns
+    ├── error-handling.md       # Error handling patterns
     └── workspace-patterns.md   # Project-specific patterns (grows over time)
 ```
 

package/reference/framework/project-structure.mdx

@@ -12,35 +12,30 @@ The current full-stack scaffold uses a workspace layout with `ui/`, `operations/
 
 ## Source Files
 
-### `src/index.ts`
+### `operations/src/index.ts`
 
 The registry entry point for your workspace. This file aggregates 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 aggregation:
 
 ```ts
 import type { DeploymentSpec } from '@elevasis/sdk'
-import * as operations from './operations/index.js'
 import * as example from './example/index.js'
+import * as emailNotification from './email-notification/exports.js'
 
 const org: DeploymentSpec = {
-  workflows: [
-    ...operations.workflows,
-    ...example.workflows,
-  ],
-  agents: [
-    ...operations.agents,
-    ...example.agents,
-  ],
+  version: '0.1.0',
+  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. The `/resource workflow` command updates the appropriate domain barrel automatically.
+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.
 
-### `src/operations/platform-status.ts`
+### `operations/src/email-notification/index.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`.
+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.
 
-### `src/example/echo.ts`
+### `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.
 
@@ -48,9 +43,9 @@ The starter workflow, scaffolded to demonstrate the per-file pattern: one workfl
 
 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.
 
-### `elevasis.config.ts`
+### `operations/elevasis.config.ts`
 
-Project-level configuration. The scaffolded file includes commented-out options (`defaultStatus`, `dev.port`) so you can discover available settings without looking them up:
+Project-level configuration. The scaffolded file includes commented-out options (`defaultStatus`, `dev.port`) and sets `docsDir` to point at the workspace-level `docs/` directory:
 
 ```ts
 import type { ElevasConfig } from '@elevasis/sdk'
@@ -58,10 +53,12 @@ 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)
+
+  docsDir: '../docs' // Scan the template's top-level docs/ directory
 } satisfies ElevasConfig
 ```
 
-Leave this file minimal -- the platform provides sensible defaults.
+The `docsDir` option (relative to CWD) overrides where the CLI scans for documentation files. Use `false` to disable documentation scanning entirely.
 
 ---
 
@@ -105,26 +102,26 @@ This directory is NOT deployed -- it is filtered out during the doc scan in `ele
 
 ## 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) |
-| `foundations/`         | `elevasis-sdk init` (default)    | Always -- cross-runtime contracts, schemas, and organization model |
-| `docs/`                | `elevasis-sdk init` (default)    | Always                                                             |
-| `docs/in-progress/`    | Agent (on first `/work`)         | 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              |
+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                 |
+| `foundations/`                       | 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.
 
-### `src/lib/`
+### `operations/src/lib/`
 
-Legacy shared code directory. In the current workspace scaffold, prefer the top-level `foundations/` package for cross-runtime contracts. The agent may still create `src/lib/` in older projects that predate the workspace-based layout. Included in the esbuild bundle alongside workflow code.
+Shared code directory for utilities used by multiple workflows within the operations package. In the current workspace scaffold, prefer the top-level `foundations/` package for cross-runtime contracts. Included in the esbuild bundle alongside workflow code.
 
 ### `data/`
 
@@ -140,14 +137,15 @@ Local utility scripts for tasks that do not run on the platform: database seeds,
 
 `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        |
+| 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        |
 
 ---
 
@@ -196,7 +194,7 @@ Do not remove or heavily edit `CLAUDE.md`. It is the primary context source that
 
 ### `.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.
+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/`
 
@@ -221,12 +219,19 @@ This directory is gitignored -- it is personal to you and not shared with collab
 
 ## Slash Commands
 
-The `.claude/commands/` directory contains four commands covering the core development loop:
+The `.claude/skills/` directory contains skills covering the core development loop:
 
-- **`/meta`** -- Project lifecycle: init, status, fix, deploy, health
-- **`/docs`** -- Browse, create, and verify permanent documentation
+- **`/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
-- **`/tutorial`** -- Progressive learning path adapted to your skill profile
+- **`/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`** -- Client project management via elevasis-sdk
+- **`/dsp`** -- Parallel agent dispatch for implementation tasks
+- **`/sync`** -- Pull latest, wipe caches, fresh reinstall
 
 For detailed command documentation, see [Agent System](agent).
 
@@ -238,40 +243,35 @@ Not all scaffolded files participate in template updates. Files fall into two ca
 
 **SCAFFOLD_FILES total: 32**
 
-**INIT_ONLY** (14 files) -- Written once during `elevasis-sdk init`, never updated by `elevasis-sdk update`:
+**INIT_ONLY** -- Written once during initial scaffold, never overwritten by updates:
 
 - `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`, `foundations/types/index.ts`
+- `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`, `foundations/`
 - `docs/index.md`, `docs/in-progress/.gitkeep`
-- `.claude/rules/workspace-patterns.md`
 
-**MANAGED** (18 files) -- Written during `elevasis-sdk init` and checked/updatable by `elevasis-sdk update`:
+**MANAGED** -- Written during initial scaffold and updated when the template evolves:
 
-- `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`
-- Three command files: `.claude/commands/meta.md`, `.claude/commands/docs.md`, `.claude/commands/tutorial.md`
-- Two skills: `.claude/skills/work/SKILL.md`, `.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`
+- `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`
 
-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.md`         | 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                                     |
+| 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                            |
 
 ---
 

package/reference/packages/core/src/README.md

@@ -6,26 +6,33 @@ This package is the source of truth for shared types, schemas, and contract help
 
 ## Import Rules
 
-- Use `@elevasis/core` for browser-safe shared types and schemas.
-- Use `@elevasis/core/server` only for Node.js-only helpers and services.
-- Use `@elevasis/core/test-utils` for test fixtures and mocks.
-- Prefer the narrowest published subpath that matches the work you are doing.
+- Use `@elevasis/core` (root export) for browser-safe shared types and schemas.
+- Use `@elevasis/core/organization-model` for the semantic contract layer.
+- These are the only two subpaths available to external consumers of the published npm package.
+- Paths like `@elevasis/core/server`, `@elevasis/core/test-utils`, `@elevasis/core/platform`, etc. are internal monorepo paths (`@repo/core/...`) and are NOT available to external consumers.
 
 ## Published Surface Groups
 
-- `platform` - shared constants, utilities, registry, SSE, and API types.
-- `auth` - multi-tenancy types for organizations, users, memberships, invitations, and credentials.
-- `execution` - workflow, agent, scheduler, calibration, and execution-interface contracts.
-- `commands` - command queue types and schemas.
-- `deployments` - deployment response types.
-- `operations` - sessions, notifications, observability, activities, triggers, and debug logs.
-- `business` - acquisition and SEO contracts, plus the PDF surface under its own subpaths.
-- `organization-model` - the semantic contract layer for CRM, lead gen, delivery, features, branding, and navigation.
-- `supabase` - generated database types and helpers.
-- `forms` - shared form schemas and form-facing types.
-- `integrations` - OAuth and credential contracts.
-- `projects` - project management request and response schemas.
-- `content` - published content metadata types.
+The published `@elevasis/core` npm package exposes exactly two subpaths:
+
+- `.` (`@elevasis/core`) - browser-safe shared types, schemas, and constants.
+- `./organization-model` (`@elevasis/core/organization-model`) - the semantic contract layer for CRM, lead gen, delivery, features, branding, and navigation.
+
+Within the monorepo, the internal `@repo/core` package exposes additional subpaths for use by `apps/` and other packages:
+
+- `@repo/core/server` - Node.js-only helpers and services.
+- `@repo/core/platform` - shared constants, utilities, registry, SSE, and API types.
+- `@repo/core/auth` - multi-tenancy types for organizations, users, memberships, invitations, and credentials.
+- `@repo/core/execution` - workflow, agent, scheduler, calibration, and execution-interface contracts.
+- `@repo/core/commands` - command queue types and schemas.
+- `@repo/core/operations` - sessions, notifications, observability, activities, triggers, and debug logs.
+- `@repo/core/supabase` - generated database types and helpers.
+- `@repo/core/integrations/...` - OAuth and credential contracts.
+- `@repo/core/projects/api-schemas` - project management request and response schemas.
+- `@repo/core/content` - published content metadata types.
+- `@repo/core/test-utils` - test fixtures and mocks (internal use only).
+
+These `@repo/core/*` subpaths are NOT available in the published `@elevasis/core` package.
 
 ## When To Read Deeper
 

package/reference/packages/ui/src/provider/README.md

@@ -4,6 +4,8 @@ The provider surface composes the shared Elevasis service, feature, appearance,
 
 ## Exports
 
+The following are exported from `published.ts`, which is the external consumer surface for `@elevasis/ui/provider`:
+
 - `ElevasisCoreProvider`
 - `ElevasisFeaturesProvider`
 - `useElevasisFeatures`
@@ -15,17 +17,16 @@ The provider surface composes the shared Elevasis service, feature, appearance,
 - `useElevasisServices`
 - `NotificationProvider`
 - `useNotificationAdapter`
-- `ElevasisUIProvider`
 - Related provider and service types
 
+Note: `ElevasisUIProvider` (the Mantine-facing visual layer) is available internally via `@repo/ui` but is NOT exported from the published `@elevasis/ui/provider` subpath. It is only available via the internal `./provider/ui` monorepo subpath.
+
 ## Related Published Subpaths
 
-- `./provider`
-- `./provider/ui`
-- `./provider/ElevasisServiceContext`
+- `./provider` - headless providers (points to `published.ts`; no Mantine dependency)
+- `./provider/ui` - full provider including Mantine-dependent `ElevasisUIProvider` (internal monorepo use; also published for consumers that opt in)
 
 ## Notes
 
-- `published.ts` is the external consumer surface.
-- `ElevasisUIProvider` is the Mantine-facing visual layer; `ElevasisCoreProvider` and `ElevasisFeaturesProvider` handle the platform shell.
-
+- `published.ts` is the external consumer surface for `@elevasis/ui/provider`.
+- `ElevasisUIProvider` is Mantine-dependent and available only via `@repo/ui` internally or `@elevasis/ui/provider/ui`; it is not included in the headless `./provider` published export.

package/reference/roadmap.mdx

@@ -44,7 +44,7 @@ Retries are platform-side only -- workers are ephemeral and never retry internal
 
 ## Workflow Step Failure
 
-**Status: Planned.** The current runtime uses fail-fast behavior with `WorkflowStepError`. The `onError` callback, `completedSteps`, and `partialOutput` features described below are not yet implemented.
+**Status: Planned.** The current runtime uses fail-fast behavior: when a step handler throws, the worker logs a `step-failed` context entry and re-throws the original error unchanged. The `onError` callback, `completedSteps`, and `partialOutput` features described below are not yet implemented.
 
 Default behavior is fail-fast: when a step throws, the workflow fails immediately.
 
@@ -71,11 +71,13 @@ Default behavior is fail-fast: when a step throws, the workflow fails immediatel
 
 ## Agent Failure Modes
 
-**Status: Implemented** (SDK 0.4.2). Agent execution runs in ephemeral worker threads with full tool calling support via `PostMessageLLMAdapter`.
+**Status: Planned.** Agent execution runs in ephemeral worker threads with full tool calling support via `PostMessageLLMAdapter`. The current runtime uses fail-fast behavior for all agent error paths; the richer failure handling described below is not yet implemented.
 
-Agents have multiple failure paths due to the LLM loop:
+**Current behavior:** Any unhandled error from the agent (including `AgentMaxIterationsError` thrown by `@repo/core` when the iteration limit is reached) propagates out of the worker and is reported as a failed execution. The worker sends: `{ type: 'result', status: 'failed', error: 'ErrorName: message', logs, metrics: { durationMs } }`. There is no graceful termination, partial output, or retry logic in the worker itself.
 
-- **Max iterations reached:** The agent returns the best output produced so far, plus a warning flag (`maxIterationsReached: true`). This is a graceful termination, not an error.
+**Planned improvements:**
+
+- **Max iterations reached:** Instead of throwing, the agent returns the best output produced so far, plus a warning flag (`maxIterationsReached: true`). This becomes a graceful termination rather than a failure.
 - **Tool crash:** Tool errors are caught by the SDK runtime, formatted as a tool result, and sent back to the LLM. The LLM decides whether to retry, try a different approach, or give up.
 - **Model refusal:** If the model refuses the prompt, the SDK retries once with an adjusted system prompt. If the retry also refuses, the agent fails with `code: 'MODEL_REFUSAL'`.
 - **Model API error:** Network errors, rate limits, or server errors from the model provider. The SDK retries with exponential backoff (3 attempts, 1s/2s/4s), then fails with `code: 'MODEL_ERROR'`.

package/reference/scaffold/index.mdx

@@ -37,6 +37,8 @@ This scaffold reference contains universal documentation that applies to all Ele
 ### Operations
 
 - [Workflow Recipes](./operations/workflow-recipes.md) -- workflow anatomy, adapter patterns, trigger patterns
+- [Propagation Pipeline](./operations/propagation-pipeline.md) -- three-layer sync pipeline, verification checks, integration points
+- [Scaffold Maintenance](./operations/scaffold-maintenance.md) -- content placement, auto-generation, adding new scaffold docs
 
 ### Reference
 
@@ -48,12 +50,14 @@ This scaffold reference contains universal documentation that applies to all Ele
 
 Content is co-located with its owning package and copied here during SDK build:
 
-| Bundle Path                              | Source Location                                           | Owner           |
-| ---------------------------------------- | --------------------------------------------------------- | --------------- |
-| `scaffold/recipes/`                      | `packages/sdk/docs/scaffold/recipes/`                     | SDK             |
-| `scaffold/operations/`                   | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
-| `scaffold/ui/`                           | `packages/ui/src/scaffold/`                               | UI              |
-| `scaffold/core/`                         | `packages/core/src/organization-model/`                   | Core            |
-| `scaffold/reference/glossary.md`         | `packages/core/src/reference/glossary.md`                 | Core            |
-| `scaffold/reference/contracts.md`        | `packages/core/src/reference/_generated/contracts.md`     | Core (auto-gen) |
-| `scaffold/reference/feature-registry.md` | `packages/ui/src/scaffold/_generated/feature-registry.md` | UI (auto-gen)   |
+| Bundle Path                                   | Source Location                                           | Owner           |
+| --------------------------------------------- | --------------------------------------------------------- | --------------- |
+| `scaffold/recipes/`                           | `packages/sdk/docs/scaffold/recipes/`                     | SDK             |
+| `scaffold/operations/`                        | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
+| `scaffold/operations/propagation-pipeline.md` | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
+| `scaffold/operations/scaffold-maintenance.md` | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
+| `scaffold/ui/`                                | `packages/ui/src/scaffold/`                               | UI              |
+| `scaffold/core/`                              | `packages/core/src/organization-model/`                   | Core            |
+| `scaffold/reference/glossary.md`              | `packages/core/src/reference/glossary.md`                 | Core            |
+| `scaffold/reference/contracts.md`             | `packages/core/src/reference/_generated/contracts.md`     | Core (auto-gen) |
+| `scaffold/reference/feature-registry.md`      | `packages/ui/src/scaffold/_generated/feature-registry.md` | UI (auto-gen)   |

package/reference/scaffold/operations/propagation-pipeline.md

@@ -0,0 +1,129 @@
+---
+title: Propagation Pipeline
+description: Three-layer pipeline that keeps Organization OS artifacts current across the monorepo and all template-derived external projects -- source generation, template sync, and verification.
+---
+
+# Propagation Pipeline
+
+`🟢 Stable` -- These pipelines run automatically. Understand them when debugging sync issues or extending the scaffold.
+
+---
+
+## Architecture
+
+The Organization OS propagation pipeline has three layers. Each has its own scripts, triggers, and failure modes.
+
+```
+Layer 1: Source Generation (pnpm scaffold:sync)
+   Regenerates derived docs from TypeScript types and manifests
+        ↓
+Layer 2: Template Sync (/external sync)
+   Propagates template to downstream external projects
+        ↓
+Layer 3: Sync Verification (pnpm sync:verify)
+   Asserts correctness across all template-derived projects
+```
+
+---
+
+## Layer 1: Source Generation
+
+`pnpm scaffold:sync` is the meta-script that regenerates all derived documentation and validates the output. It chains three sub-scripts:
+
+| Script                                  | Input                                                                                                                                         | Output                                                                                                                    |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `generate-scaffold-contracts.js`        | `packages/core/src/organization-model/types.ts`, `packages/ui/src/features/registry/types.ts`, `packages/core/src/platform/registry/types.ts` | `packages/core/src/reference/_generated/contracts.md`                                                                     |
+| `generate-scaffold-feature-registry.js` | `packages/ui/src/features/*/manifest.ts`, `packages/core/src/organization-model/domains/features.ts`                                          | `packages/ui/src/scaffold/_generated/feature-registry.md`                                                                 |
+| `generate-reference-artifacts.js`       | SDK manifest, navigation sources                                                                                                              | `packages/sdk/reference/_reference-manifest.json`, `_navigation.md`, `external/_template/docs/platform-navigation-map.md` |
+
+After generation, `validate-reference-artifacts.js` checks that the outputs are consistent. Exit 1 if drifted.
+
+### Trigger Points
+
+- **`/external sync` Phase 0 (Scaffold Sync Preflight):** Runs before any writes. Generated file changes fold into the sync scope so they propagate naturally to `_template` and downstream projects.
+- **`/sdk release` Step 1 (Shared Reference Preflight):** Runs before publish. Generated changes must be committed; validator failure is a hard blocker.
+- **Manual:** `pnpm scaffold:sync` is idempotent and safe to run anytime.
+- **Opt-out:** `--skip-scaffold-sync` on `/external sync` (rare).
+
+### Design: Regenerate-on-Propagation
+
+Drift is healed at the moment it would otherwise leak downstream. This is cheaper and more reliable than CI-only checks. The single meta-script gives one command to reason about, while the chained sub-scripts remain individually callable for debugging.
+
+---
+
+## Layer 2: Template Sync
+
+`/external sync` propagates the `external/_template` to downstream projects. It uses a three-tier model:
+
+| Tier                           | Policy                                    | Examples                                                            |
+| ------------------------------ | ----------------------------------------- | ------------------------------------------------------------------- |
+| **Tier 1 (Infrastructure)**    | Always replaced from template             | Configs, `shared/`, `lib/`, `test-utils/`, `.claude/`, entry points |
+| **Tier 2 (Standard Features)** | Synced unless project has customized them | Standard UI features, common patterns                               |
+| **Tier 3 (Project-Specific)**  | Never touched                             | `nav-items.ts`, `operations/src/`, `docs/`, `CLAUDE.md`             |
+
+The sync skill doc (`.claude/skills/external/SKILL.md`) defines the full tier model and phase sequence.
+
+---
+
+## Layer 3: Sync Verification
+
+`pnpm sync:verify` runs 86+ automated checks to assert propagation correctness. The script lives at `scripts/external/verify-sync.js`.
+
+### Per-Project Checks (auto-discovered)
+
+| Category       | What It Checks                                                                                                                                                                                                                                                                                                                                              |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `deps`         | `@elevasis/ui`, `@elevasis/sdk`, `@elevasis/core` versions match template                                                                                                                                                                                                                                                                                   |
+| `tier1`        | 9 config files match template (with placeholder resolution for project slug/name)                                                                                                                                                                                                                                                                           |
+| `org-os`       | Organization model exists, exports canonical symbols, imports from `@elevasis/core/organization-model`, calls `defineOrganizationModel` + `resolveOrganizationModel`, app-config references org model, `__root.tsx` uses `ElevasisFeaturesProvider` + `canonicalOrganizationModel`, `main.tsx` uses `ElevasisUIProvider`, all 3 CSS subpath imports present |
+| `placeholders` | No unresolved `__PROJECT_SLUG__`, `__PROJECT_NAME__`, `__PROJECT_DESCRIPTION__` in key config files                                                                                                                                                                                                                                                         |
+| `scripts`      | `ui` and `operations` `package.json` have required npm scripts                                                                                                                                                                                                                                                                                              |
+| `claude`       | `.claude/skills/`, `hooks/`, `rules/` exist; `settings.json` is valid JSON                                                                                                                                                                                                                                                                                  |
+| `shared`       | `ui/src/shared/`, `lib/`, `test-utils/` exist with minimum file counts                                                                                                                                                                                                                                                                                      |
+| `tier3`        | `nav-items.ts` has project-specific customization (not overwritten by template)                                                                                                                                                                                                                                                                             |
+| `conflicts`    | No merge conflict markers in source files                                                                                                                                                                                                                                                                                                                   |
+| `git`          | Working tree is clean                                                                                                                                                                                                                                                                                                                                       |
+| `lockfile`     | `pnpm-lock.yaml` and `node_modules` exist                                                                                                                                                                                                                                                                                                                   |
+
+### Monorepo-Level Checks
+
+| Category    | What It Checks                                  |
+| ----------- | ----------------------------------------------- |
+| `scaffold`  | `pnpm scaffold:sync` passes (artifacts current) |
+| `artifacts` | 5 generated artifacts exist and have content    |
+
+### Usage
+
+```bash
+pnpm sync:verify              # Post-sync assertion (exit 1 on failures)
+pnpm sync:verify --pre         # Pre-sync drift report (always exit 0)
+pnpm sync:verify -- ZentaraHQ  # Single project
+```
+
+### Integration Points
+
+- **`/external sync` Phase 0:** Runs `pnpm sync:verify --pre` to show drift before writes
+- **`/external sync` Phase 5/7:** Runs `pnpm sync:verify` to assert correctness after sync
+- **Vitest suite:** Tests at `scripts/external/__tests__/verify-sync.test.js` (project: `scripts-external`)
+
+### Known Acceptable Drifts
+
+Some failures are expected and intentional:
+
+- **`style.css` in nirvana-marketing:** Project-specific sidebar logo rounding customization
+- **`.gitignore` in ZentaraHQ:** Minor project-specific additions
+- **SDK patch versions:** Template may bump to a patch ahead of downstream projects between syncs
+
+These do not indicate sync failures.
+
+---
+
+## Remaining Gaps (Future Work)
+
+| Gap                                                                       | Priority |
+| ------------------------------------------------------------------------- | -------- |
+| Feature manifest validation (all manifests imported in `__root.tsx`)      | Medium   |
+| TypeScript verification (`check-types` per project)                       | Medium   |
+| Template docs surface validation (`docs/index.md`, `agent-start-here.md`) | Medium   |
+| Environment variable template validation (`.env.example` completeness)    | Low      |
+| CI drift check (fail if worktree dirty after `scaffold:sync`)             | Low      |

package/reference/scaffold/operations/scaffold-maintenance.md

@@ -0,0 +1,125 @@
+---
+title: Scaffold Maintenance
+description: How scaffold documentation is organized, generated, and bundled into the SDK -- content placement map, auto-generation pipeline, and instructions for adding new scaffold docs.
+---
+
+# Scaffold Maintenance
+
+`🟢 Stable` -- Use this when adding or modifying scaffold documentation.
+
+---
+
+## Content Placement Model
+
+Scaffold docs are co-located with their owning package and copied into the SDK reference at build time. This makes each package owner responsible for their docs and avoids a single monolithic directory.
+
+### Placement Rules
+
+- If a doc explains a single abstraction boundary, **co-locate it** with the owning package.
+- If a doc explains relationships between multiple abstractions, **centralize it** in `packages/sdk/docs/scaffold/`.
+- If a doc can be derived from code or manifests, **generate it**.
+- Hand-authored docs should point to generated maps rather than restating them.
+
+### Source-to-Destination Map
+
+| Content                     | Source                                                          | SDK Reference Destination                     |
+| --------------------------- | --------------------------------------------------------------- | --------------------------------------------- |
+| Organization Model          | `packages/core/src/organization-model/organization-model.mdx`   | `scaffold/core/organization-model.mdx`        |
+| Organization Graph          | `packages/core/src/organization-model/organization-graph.mdx`   | `scaffold/core/organization-graph.mdx`        |
+| Glossary                    | `packages/core/src/reference/glossary.md`                       | `scaffold/reference/glossary.md`              |
+| Contracts (auto-gen)        | `packages/core/src/reference/_generated/contracts.md`           | `scaffold/reference/contracts.md`             |
+| UI Recipes                  | `packages/ui/src/scaffold/recipes.md`                           | `scaffold/ui/recipes.md`                      |
+| Feature Flags & Gating      | `packages/ui/src/scaffold/feature-flags-and-gating.md`          | `scaffold/ui/feature-flags-and-gating.md`     |
+| Customization               | `packages/ui/src/scaffold/customization.md`                     | `scaffold/ui/customization.md`                |
+| Feature Shell               | `packages/ui/src/scaffold/feature-shell.mdx`                    | `scaffold/ui/feature-shell.mdx`               |
+| Composition & Extensibility | `packages/ui/src/scaffold/composition-extensibility.mdx`        | `scaffold/ui/composition-extensibility.mdx`   |
+| Feature Registry (auto-gen) | `packages/ui/src/scaffold/_generated/feature-registry.md`       | `scaffold/reference/feature-registry.md`      |
+| Scaffold Index              | `packages/sdk/docs/scaffold/index.mdx`                          | `scaffold/index.mdx`                          |
+| Pathway Recipes (3)         | `packages/sdk/docs/scaffold/recipes/`                           | `scaffold/recipes/`                           |
+| Workflow Recipes            | `packages/sdk/docs/scaffold/operations/workflow-recipes.md`     | `scaffold/operations/workflow-recipes.md`     |
+| Propagation Pipeline        | `packages/sdk/docs/scaffold/operations/propagation-pipeline.md` | `scaffold/operations/propagation-pipeline.md` |
+| This doc                    | `packages/sdk/docs/scaffold/operations/scaffold-maintenance.md` | `scaffold/operations/scaffold-maintenance.md` |
+
+---
+
+## Auto-Generation Pipeline
+
+Two types of docs are auto-generated from source:
+
+### Contracts (`contracts.md`)
+
+Generated by `scripts/monorepo/generate-scaffold-contracts.js` from TypeScript source types:
+
+- `packages/core/src/organization-model/types.ts` -- Organization Model, Feature System
+- `packages/ui/src/features/registry/types.ts` -- Feature Registry
+- `packages/core/src/platform/registry/types.ts` -- Resource Registry, Deployment Spec
+
+Output: `packages/core/src/reference/_generated/contracts.md`
+
+### Feature Registry (`feature-registry.md`)
+
+Generated by `scripts/monorepo/generate-scaffold-feature-registry.js` from feature manifests:
+
+- `packages/ui/src/features/*/manifest.ts` -- individual feature manifests
+- `packages/core/src/organization-model/domains/features.ts` -- feature key definitions
+
+Output: `packages/ui/src/scaffold/_generated/feature-registry.md`
+
+### Reference Artifacts
+
+Generated by `scripts/monorepo/generate-reference-artifacts.js`:
+
+- `packages/sdk/reference/_reference-manifest.json` -- machine-readable catalog of all reference entries
+- `packages/sdk/reference/_navigation.md` -- navigation table
+- `external/_template/docs/platform-navigation-map.md` -- cross-package reference map for external projects
+
+### Running Generators
+
+```bash
+pnpm scaffold:generate    # Run both generators
+pnpm scaffold:sync        # Generate + validate (the full loop)
+pnpm sdk-ref:generate     # Reference artifacts only
+```
+
+Generated files should never be edited manually. If the output is wrong, fix the source types or the generator script.
+
+---
+
+## SDK Build Pipeline (Reference Copy)
+
+`packages/sdk/scripts/copy-reference-docs.mjs` runs during `pnpm --filter @elevasis/sdk build` and has three phases:
+
+1. **Phase 1:** Copies SDK public docs from `apps/docs/content/docs/sdk/` with link rewriting and MDX escape stripping
+2. **Phase 2:** Copies package-owned reference docs declared in reference manifests
+3. **Phase 3:** Copies scaffold docs from co-located package sources using the `SCAFFOLD_COPIES` map
+
+The output lands in `packages/sdk/reference/` which is included in the npm package's `files` array. External projects access it via `node_modules/@elevasis/sdk/reference/`.
+
+---
+
+## Adding New Scaffold Docs
+
+1. **Create the source doc** in the appropriate package:
+   - Core concepts: `packages/core/src/...`
+   - UI patterns: `packages/ui/src/scaffold/...`
+   - Cross-package or SDK-owned: `packages/sdk/docs/scaffold/...`
+
+2. **Add to `SCAFFOLD_COPIES`** in `packages/sdk/scripts/copy-reference-docs.mjs`:
+
+   ```javascript
+   { source: 'packages/sdk/docs/scaffold/operations/my-doc.md', target: 'scaffold/operations/my-doc.md' }
+   ```
+
+3. **Update the scaffold index** in `packages/sdk/docs/scaffold/index.mdx` with a link and description.
+
+4. **Rebuild the SDK** to verify: `pnpm --filter @elevasis/sdk build`
+
+5. **Update the permanent architecture docs** if the new doc covers a concept already referenced in `apps/docs/content/docs/technical/architecture/scaffold-reference.mdx`.
+
+---
+
+## Freshness Validation
+
+External projects have a local freshness validator: `scripts/validate-autogenerated-docs.mjs` (invoked via `pnpm check:autogenerated-docs`). This checks that generated docs in the project match what their generators would produce.
+
+At the monorepo level, `pnpm scaffold:sync` followed by `pnpm sync:verify` confirms that all artifacts are current and all downstream projects are consistent.

package/reference/scaffold/recipes/add-a-resource.md

@@ -89,18 +89,19 @@ If the resource triggers another resource, uses a human checkpoint, or depends o
 ```ts
 const org: DeploymentSpec = {
   // ...
-  relationships: [
-    {
-      source: 'my-workflow',
-      target: 'email-notification',
-      type: 'triggers'
+  relationships: {
+    'my-workflow': {
+      triggers: { workflows: ['email-notification'] }
     }
-  ],
+  },
   humanCheckpoints: [
     {
-      id: 'approval-gate',
-      label: 'Approve before sending',
-      routesTo: { resourceType: 'workflow', resourceId: 'my-workflow' }
+      resourceId: 'approval-gate',
+      name: 'Approve before sending',
+      type: 'human',
+      version: '1.0.0',
+      status: 'prod',
+      routesTo: { workflows: ['my-workflow'] }
     }
   ]
 }
@@ -117,9 +118,10 @@ To make the resource referenceable from the org model (so the Operations graph a
 ```ts
 resourceMappings: [
   {
+    id: 'my-workflow',
     resourceId: 'my-workflow',
     resourceType: 'workflow',
-    domainId: 'operations',
+    domainIds: ['operations'],
     label: 'My Workflow'
   }
 ]

package/reference/scaffold/ui/feature-shell.mdx

@@ -213,7 +213,7 @@ See [Composition & Extensibility](./composition-extensibility.mdx) for the sideb
 
 ### CRM Sidebar
 
-The CRM sidebar (`packages/ui/src/features/crm/sidebar/`) exports `CrmSidebar`, `CrmSidebarTop`, and `CrmSidebarMiddle`. `SavedViewsPanel` lives in `packages/ui/src/features/crm/workbench/SavedViewsPanel.tsx` and is exported from the CRM workbench barrel; it provides the saved contact views panel rendered within the CRM workbench surface.
+The CRM sidebar (`packages/ui/src/features/crm/sidebar/`) exports `CrmSidebar`, `CrmSidebarTop`, and `CrmSidebarMiddle`. `SavedViewsPanel` lives in `packages/ui/src/features/crm/workbench/SavedViewsPanel.tsx` and is exported from the CRM workbench barrel; it provides the saved contact views panel. It is currently commented out of the default `CrmSidebarMiddle` layout while the CRM sidebar section model is being reworked, but can be re-included explicitly when composing a custom sidebar.
 
 ### Operations Sidebar