@elevasis/sdk 1.5.2 → 1.5.4

package/reference/claude-config/rules/docs.md

@@ -0,0 +1,26 @@
+---
+description: Documentation conventions -- structure, frontmatter, /save integration, auto-generated files
+paths:
+  - docs/**
+---
+
+# Documentation
+
+## Safety Invariants
+
+- `docs/index.md` and `docs/resources.md` are auto-generated by the SDK CLI -- never edit manually
+- Regenerate: `pnpm exec elevasis-sdk generate-docs` / `pnpm exec elevasis-sdk generate-resources`
+- Validate: `pnpm exec elevasis-sdk validate-docs` (or `pnpm check:autogenerated-docs`)
+- Every `.md` file in `docs/` MUST have `title` and `description` frontmatter -- docs without it are skipped by the index generator
+- In-progress docs additionally require `status: planned | in-progress | complete`
+
+## Structure
+
+- All docs are Markdown (`.md`), not MDX -- external projects don't use Fumadocs
+- UI features → `docs/ui/`, platform features → `docs/operations/`, knowledge → `docs/knowledge/`
+- New subdirectories under `docs/` are automatically discovered by the index generator
+
+## Detailed Reference
+
+- `docs/index.md` -- auto-generated navigation hub (full doc map)
+- `docs/agent-start-here.md` -- canonical agent entrypoint and task-routing guidance

package/reference/claude-config/rules/error-handling.md

@@ -0,0 +1,56 @@
+---
+description: Error handling -- ExecutionError vs PlatformToolError, retry logic, no auto-retry
+paths:
+  - operations/**
+---
+
+# Error Handling
+
+## Error Types
+
+Two error classes from `@elevasis/sdk`:
+
+**`ExecutionError`** -- base class for workflow/step failures.
+
+```typescript
+import { ExecutionError } from '@elevasis/sdk'
+
+throw new ExecutionError('Payment processing failed', {
+  context: { invoiceId: '123', amount: 500 }
+})
+```
+
+**`PlatformToolError`** -- thrown by `platform.call()` and typed adapters.
+
+```typescript
+import { PlatformToolError } from '@elevasis/sdk'
+
+try {
+  await attio.createRecord({ ... })
+} catch (err) {
+  if (err instanceof PlatformToolError && err.retryable) {
+    // Transient error (rate limit, timeout, network) -- safe to retry
+  } else {
+    // Permanent error (invalid credentials, bad input) -- don't retry
+  }
+}
+```
+
+## No Auto-Retry
+
+The platform does NOT automatically retry failed steps. Your handler is responsible for retry logic. Check `PlatformToolError.retryable` to decide whether retrying is safe.
+
+## Error Visibility
+
+- Unhandled exceptions in handlers surface directly to CLI output and AI Studio.
+- Use `context.logger.error()` to log errors -- `console.error()` is NOT captured by the platform.
+- Write clear, descriptive error messages -- they're the primary debugging signal for end users.
+
+## Common PlatformToolError Codes
+
+| Code                  | Retryable | Cause                             |
+| --------------------- | --------- | --------------------------------- |
+| `rate_limit_exceeded` | Yes       | Integration API rate limit hit    |
+| `timeout_error`       | Yes       | Integration call timed out        |
+| `credentials_invalid` | No        | Credential not found or expired   |
+| `validation_error`    | No        | Invalid parameters passed to tool |

package/reference/claude-config/rules/execution.md

@@ -0,0 +1,40 @@
+---
+description: Execution model -- timeouts, memory, concurrency, org isolation, runtime constraints
+paths:
+  - operations/**
+---
+
+# Execution Model
+
+## Runtime Environment
+
+Each execution runs in an isolated Node.js worker thread spawned from the deployed bundle. Workers are ephemeral -- created on execution start, terminated on completion. No state persists between executions.
+
+## Constraints
+
+| Constraint | Workflows                       | Agents                                                |
+| ---------- | ------------------------------- | ----------------------------------------------------- |
+| Timeout    | 300s (5 min)                    | 600s (10 min, configurable via `constraints.timeout`) |
+| Memory     | 256MB hard limit                | 256MB hard limit                                      |
+| Disk       | None (no persistent filesystem) | None                                                  |
+
+- Platform enforces timeouts -- no handler code needed, worker terminates automatically.
+- Memory overflow crashes the worker. Other tenants are unaffected.
+- For long-running tasks, break work into multiple steps or use agents with extended timeout.
+
+## Concurrency
+
+Concurrent executions for the same organization run in completely separate workers with zero shared state. No locking, no race conditions between executions.
+
+## Organization Isolation
+
+- `organizationId` is injected server-side from the JWT context -- workers never see it.
+- Storage paths are automatically org-prefixed.
+- Resource IDs are scoped per organization (not global).
+- External developers cannot access other organizations' data by construction.
+
+No developer action needed for multi-tenancy -- the platform handles it.
+
+## Cancellation
+
+The platform can cancel in-flight executions. The worker terminates immediately with no cleanup handler.

package/reference/claude-config/rules/frontend.md

@@ -0,0 +1,43 @@
+---
+description: Frontend conventions -- React, routing, state, styling, testing, pages
+paths:
+  - ui/src/**
+---
+
+# Frontend
+
+## Safety Invariants
+
+- `ElevasisUIProvider` in `ui/src/main.tsx` auto-composes shared UI, auth, and API surface -- route files do not wire providers manually
+- `useApiClient()` from `@/lib/hooks/useApiClient` for authenticated API calls -- never raw `fetch` with auth headers
+- `routeTree.gen.ts` is auto-generated on `pnpm dev` -- never edit manually
+- Auth protection: wrap page content with `ProtectedRoute` from `@elevasis/ui/auth`. Admin pages nest `AdminGuard` inside `ProtectedRoute`
+- Never fork `@elevasis/ui` components -- if a published component needs a tweak, that missing capability is a bug in `@elevasis/ui`
+
+## Silent-Break Gotchas
+
+- Route files vs layout files: `operations.tsx` is a layout (renders `<Outlet />`), `operations/my-page.index.tsx` is a page. Confusing the two breaks routing silently
+- `foundations/` cannot import React or `@elevasis/sdk/worker` -- it is runtime-agnostic shared types only
+- `@/*` resolves to `ui/src/*`, `@foundation/*` resolves to `foundations/*` -- never import from `operations/` (separate runtime)
+
+## Stack Constraints
+
+- Mantine 8.2.7 for all UI components -- no Radix UI, no Tailwind CSS, no shadcn
+- `@tabler/icons-react` for icons -- never Lucide
+- Server state: TanStack Query. Client state: Zustand + Immer. Never mix the two
+- Glass background is the primary surface treatment: `var(--glass-background)` with `backdrop-filter: var(--glass-blur)`
+- Import shared components from `@elevasis/ui/components`, `@elevasis/ui/layout`, `@elevasis/ui/charts`
+- Import charts from `@elevasis/ui/charts`, not directly from `@mantine/charts`
+
+## Integration UI Surfaces
+
+When building pages that display external data, use published `@elevasis/ui` components before building custom UI. Use Mantine components and CSS variables exclusively -- no inline hex colors, no custom design tokens. Match existing page density and spacing.
+
+## Detailed Reference
+
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- add a page, add a nav item, theme tokens, feature-scoped components, route patterns (static, nested, dynamic)
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- `featureKey` / `FeatureGuard` / `AdminGuard` model
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` -- sidebar composition via manifest overrides
+- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- TypeScript shapes (`FeatureModule`, `NavItem`, `OrganizationModel`)
+- `ui/src/config/theme.ts` -- theme configuration and CSS variable definitions
+- `ui/src/config/nav-items.ts` -- sidebar navigation entries

package/reference/claude-config/rules/observability.md

@@ -0,0 +1,31 @@
+---
+description: Observability -- context.logger API, execution inspection, step-level context
+paths:
+  - operations/**
+---
+
+# Observability
+
+## Safety Invariants
+
+- Use `context.logger` for all logging in step handlers -- `console.*` is NOT captured by the platform
+- Log levels: `debug` (verbose), `info` (normal progress), `warn` (non-fatal, processing continues), `error` (fatal, processing stops)
+- Step lifecycle events (started, completed, failed, route taken) are auto-logged by the SDK worker -- no handler code needed
+
+## Key Rules
+
+- Every handler should log at: entry (step name + key params), decisions (skips, branches), progress (per-item in loops), summary (counts at end)
+- Error messages in handlers surface as the execution's error message -- write for humans, not machines
+- String values truncated at 200 characters in logs
+- 30-day log retention (includes logs from deleted resources)
+
+## Inspecting Executions
+
+```bash
+pnpm exec elevasis-sdk execution <resourceId> <executionId>
+pnpm exec elevasis-sdk executions <resourceId>
+```
+
+## Detailed Reference
+
+- `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- full logging patterns and handler examples

package/reference/claude-config/rules/organization-os.md

@@ -0,0 +1,62 @@
+# Organization OS
+
+Organization OS is the semantic contract layer defining how organizations, features, domains, surfaces, entities, capabilities, and resources relate. This project consumes Organization OS through the SDK and foundations config.
+
+## Key Files in This Project
+
+- `foundations/config/organization-model.ts` -- project-specific org model definition (calls `defineOrganizationModel` + `resolveOrganizationModel`)
+- `foundations/config/organization-model.examples.ts` -- 5 reference patterns: branding, CRM stages, lead-gen stages, resource mappings, custom features. Pure reference -- not imported anywhere. Read this when customizing the org model.
+- `foundations/types/entities.ts` -- typed entity contracts (Project, Deal, etc.). Extends `BaseProject`, `BaseDeal` from `@elevasis/core/entities` with project-specific metadata. Read this when authoring workflows that operate on these entities.
+- `ui/src/routes/__root.tsx` -- wires `ElevasisFeaturesProvider` with `canonicalOrganizationModel`
+- `ui/src/app-config.ts` -- references the org model
+- `operations/src/index.ts` -- `DeploymentSpec` registry for workflows and agents
+
+## Reference Documentation
+
+Full Organization OS documentation ships with the SDK and is available locally after `pnpm install`:
+
+### Scaffold Reference (via SDK)
+
+All paths under `node_modules/@elevasis/sdk/reference/scaffold/`:
+
+- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` -- scaffold root and navigation
+- `node_modules/@elevasis/sdk/reference/scaffold/core/organization-model.mdx` -- semantic contract, schema, authoring helpers
+- `node_modules/@elevasis/sdk/reference/scaffold/core/organization-graph.mdx` -- graph derivation, node/edge taxonomy, lenses
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-shell.mdx` -- FeatureModule manifest, provider runtime
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/composition-extensibility.mdx` -- layout primitives, router abstraction
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- copy-paste UI recipes for pages, nav items, components
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- three-concept gating model
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` -- sidebar composition via manifest overrides
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-feature.md` -- end-to-end from org model key through manifest, routes, gating
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md` -- author and deploy a workflow or agent
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/gate-by-feature-or-admin.md` -- decision table for access control patterns
+- `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- workflow anatomy, adapter patterns, trigger patterns
+- `node_modules/@elevasis/sdk/reference/scaffold/operations/propagation-pipeline.md` -- how sync and verification work across projects
+- `node_modules/@elevasis/sdk/reference/scaffold/operations/scaffold-maintenance.md` -- content placement and auto-generation pipeline
+- `node_modules/@elevasis/sdk/reference/scaffold/reference/glossary.md` -- Organization OS term definitions
+- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- auto-generated TypeScript contract shapes
+- `node_modules/@elevasis/sdk/reference/scaffold/reference/feature-registry.md` -- auto-generated feature manifest catalog
+
+### Local Project Docs
+
+- `docs/platform-navigation-map.md` -- auto-generated cross-package reference map
+- `docs/resources.md` -- auto-generated project resource topology
+- `docs/agent-start-here.md` -- canonical first-read for agents (includes task-class routing)
+
+## Published Subpaths and Constants
+
+- `@elevasis/core/organization-model` -- the curated organization-model barrel. Exports `defineOrganizationModel`, `resolveOrganizationModel`, `OrganizationModelSchema`, `DEFAULT_ORGANIZATION_MODEL`, organization-model types, and typed feature/surface constants.
+  - Feature IDs: `CRM_FEATURE_ID`, `LEAD_GEN_FEATURE_ID`, `PROJECTS_FEATURE_ID`, `OPERATIONS_FEATURE_ID`, `MONITORING_FEATURE_ID`, `SETTINGS_FEATURE_ID`, `SEO_FEATURE_ID`
+  - Headline surface IDs: `CRM_PIPELINE_SURFACE_ID`, `LEAD_GEN_LISTS_SURFACE_ID`, `PROJECTS_INDEX_SURFACE_ID`, `OPERATIONS_ORGANIZATION_GRAPH_SURFACE_ID`
+  - Use these constants instead of magic strings when overriding the org model.
+- `@elevasis/core/entities` -- entity contracts barrel. Exports `BaseProject`, `BaseProjectSchema`, `BaseProjectInput` and the equivalents for `Milestone`, `Task`, `Deal`, `Company`, `Contact`. Each base interface is generic over a `\<TMeta>` extension slot. Extend these in `foundations/types/entities.ts` to add project-specific fields.
+
+## When Working with Organization OS
+
+- **Adding a feature:** Follow `node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-feature.md`
+- **Adding a resource:** Follow `node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md`
+- **Changing org model:** Start with `foundations/config/organization-model.examples.ts` for reference patterns, then edit `foundations/config/organization-model.ts`. Use the typed feature/surface constants from `@elevasis/core/organization-model` rather than magic strings. Verify the org-os wiring (provider chain, CSS imports, feature shell).
+- **Extending entities:** Start with `foundations/types/entities.ts` for the demo extension pattern. Base shapes come from `@elevasis/core/entities`.
+- **Authoring a workflow that takes a Project/Deal/etc.:** Reference entity types from `foundations/types/entities.ts` in the input schema -- do not redeclare them.
+- **Understanding contracts:** Check `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for current type shapes
+- **Debugging sync issues:** Check `node_modules/@elevasis/sdk/reference/scaffold/operations/propagation-pipeline.md` for the verification pipeline

package/reference/claude-config/rules/platform.md

@@ -0,0 +1,41 @@
+---
+description: Platform conventions -- SDK workflows, agents, deployment, resource registry
+paths:
+  - operations/**
+---
+
+# Platform (Elevasis SDK)
+
+## Safety Invariants
+
+- Every workflow implements `WorkflowDefinition` from `@elevasis/sdk` with: `config`, `contract` (Zod schemas), `steps` map, and `entryPoint`
+- Input/output schemas MUST come from `@shared/types` -- never define inline Zod schemas in workflow files
+- `operations/src/index.ts` default-exports a `DeploymentSpec` with `workflows` and `agents` arrays -- every resource must be registered here
+- Always run `check` before `deploy`
+
+## Imports
+
+- `@elevasis/sdk` for types (`WorkflowDefinition`, `DeploymentSpec`)
+- `@elevasis/sdk/worker` for runtime utilities (`platform`, adapters: `llm`, `storage`, `scheduler`, `notifications`)
+- `@shared/*` resolves to `../shared/*` for shared type imports
+- Never import from `ui/src/` -- separate runtimes
+
+## Key Rules
+
+- Use typed adapters over raw `platform.call()` whenever a typed adapter exists
+- `version` in resource config is semver -- bump on contract changes
+- `status` is `'dev'` or `'prod'` -- new resources start as `'dev'`
+
+## CLI Commands
+
+| Command                              | Purpose                       |
+| ------------------------------------ | ----------------------------- |
+| `pnpm -C operations run check`       | Validate resource definitions |
+| `pnpm -C operations run deploy`      | Deploy to dev                 |
+| `pnpm -C operations run deploy:prod` | Deploy to production          |
+
+## Detailed Reference
+
+- `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- workflow anatomy, adapter patterns, trigger patterns
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md` -- end-to-end resource authoring guide
+- SDK reference docs: `operations/node_modules/@elevasis/sdk/reference/` (concepts, framework, platform-tools, runtime, CLI)

package/reference/claude-config/rules/shared-types.md

@@ -0,0 +1,46 @@
+---
+description: Shared type boundary -- what belongs in shared/, import rules, schema conventions
+paths:
+  - shared/**
+---
+
+# Shared Types
+
+`shared/` is the type boundary between the frontend (`src/`) and platform (`operations/`). Both runtimes import from here but never from each other.
+
+## What Belongs Here
+
+- Zod schemas for workflow input/output contracts
+- TypeScript types inferred from those schemas (`z.infer<typeof schema>`)
+- Domain types referenced by both runtimes (status enums, entity shapes)
+- Shared constants
+
+## What Does NOT Belong Here
+
+- React components, hooks, or anything importing `react`
+- SDK runtime code or anything importing `@elevasis/sdk/worker`
+- Browser APIs or Node-specific APIs
+- Implementation logic -- types and constants only
+
+## Schema Convention
+
+Define Zod schemas first, then infer the type:
+
+```typescript
+export const fooInputSchema = z.object({ ... })
+export type FooInput = z.infer<typeof fooInputSchema>
+```
+
+Name schemas `<name>InputSchema` / `<name>OutputSchema`. Name types `<Name>Input` / `<Name>Output`.
+
+## File Organization
+
+Types live in `shared/types/`. The directory structure:
+
+- `shared/types/index.ts` -- Main entry point, re-exports from domain files
+- As the project grows: split into domain files within the directory (e.g., `shared/types/billing.ts`, `shared/types/auth.ts`)
+- Re-export new domain files from `shared/types/index.ts`
+
+## Path Alias
+
+Both tsconfigs resolve `@shared/*` to `shared/*`. Always use `@shared/types` (not relative paths) when importing from `src/` or `operations/src/`.

package/reference/claude-config/rules/task-tracking.md

@@ -0,0 +1,47 @@
+---
+description: In-progress task conventions -- doc format, status values, auto-save behavior
+---
+
+# Task Tracking
+
+## Status Values
+
+Exactly three values for frontmatter `status`: `planned`, `in-progress`, `complete`.
+
+## Doc Format
+
+- Frontmatter: `title`, `description`, `status` (per the monorepo rule in `.claude/rules/in-progress-tasks.md` -- nothing else belongs in task-doc frontmatter; `resume_context` is DB-canonical on `prj_tasks`)
+- Sections: Objective, Plan, Progress, Resume Context
+- Progress subsections use markers: `### Step N: Title -- PENDING`, `-- IN PROGRESS`, `-- COMPLETE`
+
+## Auto-Update Behavior
+
+- When working on a tracked task, update the Progress section when a plan step transitions:
+  - PENDING -> IN PROGRESS (starting work on a step)
+  - IN PROGRESS -> COMPLETE (finishing a step)
+- Do NOT update on every action -- only on step transitions
+
+## Auto-Save Behavior
+
+The agent auto-saves progress (no user action needed) when:
+
+- The conversation context is getting heavy (many tool calls, large file reads)
+- The user appears to be wrapping up (thanks, goodbye, switching topics)
+- Significant progress has been made (2+ steps completed without saving)
+- Before a context reset
+
+Auto-save updates the task doc's Progress and Resume Context sections silently, then briefly confirms. The canonical persistence path is `pnpm exec elevasis-sdk project:task:save` -- the CLI writes through to `prj_tasks.resume_context` (JSONB) so another agent can resume without re-deriving intent.
+
+## Completion Suggestions
+
+When all plan steps are marked COMPLETE, **suggest** completing the task -- never auto-invoke. Ask: "All steps for '{task}' look done. Want me to finalize it?"
+
+## Where Tasks Live
+
+Project tasks for this template live in the `prj_tasks` Supabase table, not in repo-local files. Operate on them via the SDK CLI:
+
+- `pnpm exec elevasis-sdk project:work` -- entrypoint for task work (resume / new intent detection)
+- `pnpm exec elevasis-sdk project:list` -- portfolio / task listing
+- `pnpm exec elevasis-sdk project:task:save` -- persist progress + `resume_context` to the DB
+
+The monorepo-side `/work` slash command still exists for monorepo task docs under `apps/docs/content/docs/in-progress/**`; that flow is unchanged. What went away is the external template's own `/work` skill and its `docs/in-progress/` directory -- external projects now route through the DB-backed `project:*` surface above.

package/reference/claude-config/scripts/statusline-command.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+let input = ''
+process.stdin.on('data', (chunk) => (input += chunk))
+process.stdin.on('end', () => {
+  const data = JSON.parse(input)
+  const model = data.model?.display_name || '?'
+  const pct = Math.floor(data.context_window?.used_percentage || 0)
+
+  const DIM = '\x1b[90m',
+    RESET = '\x1b[0m'
+
+  const ctxSize = data.context_window?.context_window_size || 0
+  const usedTokens = Math.round((ctxSize * pct) / 100)
+  const rounded = Math.round(usedTokens / 100) * 100
+  const tokenStr = rounded >= 1000 ? (rounded / 1000).toFixed(1).replace(/\.0$/, '') + 'k' : String(rounded)
+
+  console.log(`${DIM}[${RESET}${model}${DIM}]${RESET} ${tokenStr} Tokens`)
+})

package/reference/claude-config/settings.json

@@ -0,0 +1,30 @@
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node .claude/scripts/statusline-command.js"
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/post-edit-validate.mjs"
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/tool-failure-recovery.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}

package/reference/claude-config/skills/deploy/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: deploy
+description: Test, build, fix issues, then commit and push
+---
+
+# Deploy
+
+Test, build, fix issues, then commit and push.
+
+**Usage:** `/deploy [--skip] [--minor | --major] [commit message]`
+
+## Flags
+
+- `--skip` -- Skip tests, type checking, and build (Steps 2-4). Go straight from pre-flight to commit and push.
+- `--minor` -- Bump the minor version instead of patch (e.g. 1.0.0 -> 1.1.0).
+- `--major` -- Bump the major version instead of patch (e.g. 1.0.0 -> 2.0.0).
+
+## Process
+
+### Step 1: Pre-flight Check
+
+Run in parallel:
+
+```bash
+git status
+git diff --stat
+```
+
+If there are no changes, report "Nothing to deploy" and stop.
+
+### Step 1b: Version Bump
+
+Read the current version from `package.json`, then bump it:
+
+- Default: bump **patch** (e.g. 1.0.0 -> 1.0.1)
+- `--minor`: bump **minor** (e.g. 1.0.0 -> 1.1.0)
+- `--major`: bump **major** (e.g. 1.0.0 -> 2.0.0)
+
+Use the Edit tool to update the `"version"` field in `package.json` directly. Do not use `npm version` or any CLI command.
+
+### Step 1c: Regenerate Documentation
+
+Run both doc generators in sequence (resources first so the nav index picks up `resources.md`):
+
+```bash
+pnpm exec elevasis-sdk generate-resources
+pnpm exec elevasis-sdk generate-docs
+```
+
+This ensures autogenerated files (`docs/resources.md`, `docs/index.md`) reflect the current resource state before they are committed. These must run after the version bump so any version references in generated output are correct.
+
+### Step 2: Run Tests
+
+```bash
+pnpm test
+```
+
+If tests fail:
+
+1. Read the failing test output
+2. Attempt to fix the issue
+3. Re-run tests
+4. If still failing after 2 attempts, stop and report the failures
+
+### Step 3: Type Check
+
+```bash
+pnpm lint
+```
+
+If type errors exist:
+
+1. Read the errors
+2. Attempt to fix
+3. Re-run
+4. If still failing after 2 attempts, stop and report
+
+### Step 4: Build
+
+```bash
+pnpm build
+```
+
+If build fails:
+
+1. Read the error output
+2. Attempt to fix
+3. Re-run
+4. If still failing after 2 attempts, stop and report
+
+### Step 5: Commit
+
+1. Stage all changed files: `git add -A`
+2. Create commit with the provided message (or auto-generate from changes)
+3. Format: conventional commits (feat:, fix:, chore:, docs:, etc.)
+
+```bash
+git add -A
+git commit -m "<message>"
+```
+
+### Step 6: Push
+
+```bash
+git push
+```
+
+If push fails (e.g., remote has new commits):
+
+1. `git pull --rebase`
+2. Re-run tests to verify no conflicts broke anything
+3. `git push`
+
+### Step 7: Report
+
+```
+Deploy Complete
+===============
+Version: <old> -> <new>
+Tests:   passed
+Types:   clean
+Build:   success
+Commit:  <hash> - <message>
+Push:    pushed to <branch>
+```
+
+### Step 8: Project Task Status Transition
+
+After a successful push, mark any linked project task as `submitted`. This is a best-effort fanout -- it must never fail the deploy.
+
+1. **Resolve the task ID.** Look for a `prj_tasks` UUID tied to the current work, in this order:
+   - A task UUID explicitly captured in the current conversation (e.g. from a previous `/save`, `/project work`, or `project:task:*` invocation).
+   - The most recent in-progress task on the most-recently-touched project, via:
+
+     ```bash
+     pnpm -C operations exec elevasis-sdk project:list --status active,blocked --format brief
+     pnpm -C operations exec elevasis-sdk project:task:list --project <project-id> --status in_progress
+     ```
+
+   - If the session produced an ambiguous or empty result, PROMPT the user once: "Mark a project task as submitted? (task UUID, or 'skip')". Default is skip.
+
+2. **Fire the transition** (only when a single confident task ID is resolved):
+
+   ```bash
+   pnpm -C operations exec elevasis-sdk project:task:update <task-id> --status submitted
+   ```
+
+3. **Failure handling.** If the CLI call errors, no task ID can be resolved, or the user declines, emit a single warning line and continue:
+
+   ```
+   Warning: skipped project:task status transition (<reason>). Deploy itself succeeded.
+   ```
+
+   Never retry, never block the deploy report, never exit non-zero on this step.
+
+## Error Recovery
+
+If any step fails and cannot be auto-fixed:
+
+```
+Deploy Failed at Step N: [step name]
+=====================================
+Error: [description]
+Attempted fixes: [what was tried]
+Manual action needed: [what the user should do]
+```