@elevasis/sdk 1.21.0 → 1.22.1

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

@@ -1,57 +1,57 @@
----
-description: Deployment workflow -- check-first, dev vs prod, version bumping, common errors
-paths:
-  - operations/**
----
-
-# Deployment
-
-## Always Check Before Deploy
-
-```bash
-pnpm -C operations run check        # Validate resource definitions
-pnpm -C operations run check-types  # TypeScript type-check
-pnpm -C operations run deploy       # Deploy to dev (only after both pass)
-```
-
-`check` catches duplicate resource IDs, OM descriptor/code mismatches, invalid step chains, broken relationships, and schema serialization issues. Same validation runs during deploy -- if `check` passes, deploy validation will pass.
-
-## Dev vs Prod
-
-| Command                              | Target            | When                    |
-| ------------------------------------ | ----------------- | ----------------------- |
-| `pnpm -C operations run deploy`      | Local dev API     | Development and testing |
-| `pnpm -C operations run deploy:prod` | `api.elevasis.io` | Production release      |
-
-Always test in dev first, verify with `elevasis-sdk exec`, then deploy to prod.
-
-## Version Bumping
-
-Deploy accepts `--major`, `--minor`, `--patch` flags to bump the deployment version. The bumped version is written back to `src/index.ts`. Bump on contract changes (input/output schema modifications).
-
-## What Gets Deployed
-
-1. **Bundle:** esbuild compiles `src/index.ts` + all dependencies into a single self-contained CJS file. No `node_modules` needed at runtime.
-2. **Metadata:** Resource definitions, OM Resources descriptor bindings, Zod schemas (converted to JSON Schema), relationships, triggers.
-
-## Environment
-
-- `ELEVASIS_PLATFORM_KEY` in `.env` is required for CLI auth
-- `.env` is never included in the bundle -- it stays local
-- Integration credentials live in Command Center, not `.env`
-
-## Common Errors
-
-| Error                                    | Fix                                                     |
-| ---------------------------------------- | ------------------------------------------------------- |
-| `401: Invalid API key`                   | Check `ELEVASIS_PLATFORM_KEY` in `.env`                 |
-| `Duplicate resource ID`                  | Fix the duplicated OM Resource descriptor ID, then derive runtime `resourceId` from that descriptor |
-| `Missing OM Resource descriptor`         | Add the descriptor to `core/config/organization-model.ts` under `resources.entries` |
-| `Step references non-existent next step` | Fix the `next:` field in the step chain                 |
-| `Schema serialization failed`            | Simplify the Zod schema (warning, still deploys)        |
-| `No default export found`                | `src/index.ts` must `export default` a `DeploymentSpec` |
-| `Documentation file exceeds 100KB`       | Split the `.md` file                                    |
-
-## Deployment Replaces Previous
-
-Only one deployment can be `active` at a time. Deploying again automatically marks the previous deployment as `stopped`. Resources become executable immediately after deploy succeeds.
+---
+description: Deployment workflow -- check-first, dev vs prod, version bumping, common errors
+paths:
+  - operations/**
+---
+
+# Deployment
+
+## Always Check Before Deploy
+
+```bash
+pnpm -C operations run check        # Validate resource definitions
+pnpm -C operations run check-types  # TypeScript type-check
+pnpm -C operations run deploy       # Deploy to dev (only after both pass)
+```
+
+`check` catches duplicate resource IDs, OM descriptor/code mismatches, invalid step chains, broken relationships, and schema serialization issues. Same validation runs during deploy -- if `check` passes, deploy validation will pass.
+
+## Dev vs Prod
+
+| Command                              | Target            | When                    |
+| ------------------------------------ | ----------------- | ----------------------- |
+| `pnpm -C operations run deploy`      | Local dev API     | Development and testing |
+| `pnpm -C operations run deploy:prod` | `api.elevasis.io` | Production release      |
+
+Always test in dev first, verify with `elevasis-sdk exec`, then deploy to prod.
+
+## Version Bumping
+
+Deploy accepts `--major`, `--minor`, `--patch` flags to bump the deployment version. The bumped version is written back to `src/index.ts`. Bump on contract changes (input/output schema modifications).
+
+## What Gets Deployed
+
+1. **Bundle:** esbuild compiles `src/index.ts` + all dependencies into a single self-contained CJS file. No `node_modules` needed at runtime.
+2. **Metadata:** Resource definitions, OM Resources descriptor bindings, Zod schemas (converted to JSON Schema), relationships, triggers.
+
+## Environment
+
+- `ELEVASIS_PLATFORM_KEY` in `.env` is required for CLI auth
+- `.env` is never included in the bundle -- it stays local
+- Integration credentials live in Command Center, not `.env`
+
+## Common Errors
+
+| Error                                    | Fix                                                     |
+| ---------------------------------------- | ------------------------------------------------------- |
+| `401: Invalid API key`                   | Check `ELEVASIS_PLATFORM_KEY` in `.env`                 |
+| `Duplicate resource ID`                  | Fix the duplicated OM Resource descriptor ID, then derive runtime `resourceId` from that descriptor |
+| `Missing OM Resource descriptor`         | Add the descriptor to `core/config/organization-model.ts` under the id-keyed `resources` map |
+| `Step references non-existent next step` | Fix the `next:` field in the step chain                 |
+| `Schema serialization failed`            | Simplify the Zod schema (warning, still deploys)        |
+| `No default export found`                | `src/index.ts` must `export default` a `DeploymentSpec` |
+| `Documentation file exceeds 100KB`       | Split the `.md` file                                    |
+
+## Deployment Replaces Previous
+
+Only one deployment can be `active` at a time. Deploying again automatically marks the previous deployment as `stopped`. Resources become executable immediately after deploy succeeds.

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

@@ -1,56 +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 |
+---
+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

@@ -1,40 +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.
+---
+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

@@ -17,8 +17,8 @@ paths:
 ## 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
-- `core/` cannot import React or `@elevasis/sdk/worker` -- it is runtime-agnostic shared types and organization configuration only
-- `@/*` resolves to `ui/src/*`, `@core/*` resolves to `core/*` -- never import from `operations/` (separate runtime)
+- `core/` cannot import React or `@elevasis/sdk/worker` -- it is runtime-agnostic shared types and organization configuration only
+- `@/*` resolves to `ui/src/*`, `@core/*` resolves to `core/*` -- never import from `operations/` (separate runtime)
 
 ## Stack Constraints
 
@@ -36,8 +36,8 @@ When building pages that display external data, use published `@elevasis/ui` com
 ## 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` -- `systemKey` / `SystemGuard` / `AdminGuard` model
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- `systemKey` / `SystemGuard` / `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 (`SystemModule`, `NavItem`, `OrganizationModel`)
+- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- TypeScript shapes (`SystemModule`, `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

@@ -1,31 +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 elevasis-sdk execution <resourceId> <executionId>
-pnpm elevasis-sdk executions <resourceId>
-```
-
-## Detailed Reference
-
-- `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- full logging patterns and handler examples
+---
+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 elevasis-sdk execution <resourceId> <executionId>
+pnpm 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/operations.md

@@ -12,16 +12,16 @@ paths:
 
 The `operations/` directory contains platform resources and deployment metadata that deploy to the Elevasis platform. It is a standalone TypeScript project with its own `package.json`, `tsconfig.json`, and dependencies.
 
-**Discovering deployed resources:** Read `operations/src/index.ts` for deployment assembly and `core/config/organization-model.ts` for the OM Resources descriptor catalog. Run `pnpm elevasis-sdk project:list --pretty` against the live DB for the deployed surface.
+**Discovering deployed resources:** Read `operations/src/index.ts` for deployment assembly and `core/config/organization-model.ts` for the OM Resources descriptor catalog. Run `pnpm elevasis-sdk project:list --pretty` against the live DB for the deployed surface.
 
 ## Echo Workflow (Starter Example)
 
 **Location:** `operations/src/example/echo.ts`
 
-The echo workflow accepts a message string and returns it unchanged. Its purpose is the wiring, not the logic: input and output schemas are defined in `core/types/index.ts` and imported by both the workflow and the frontend.
+The echo workflow accepts a message string and returns it unchanged. Its purpose is the wiring, not the logic: input and output schemas are defined in `core/types/index.ts` and imported by both the workflow and the frontend.
 
 ```
-core/types/index.ts             -- defines echoInputSchema, echoOutputSchema
+core/types/index.ts             -- defines echoInputSchema, echoOutputSchema
 operations/src/example/echo.ts  -- imports schemas for workflow contract
 ui/src/routes/                  -- imports schemas for form validation and display
 ```
@@ -30,15 +30,19 @@ The workflow is registered in `operations/src/index.ts` as part of the `example`
 
 ## Adding a New Workflow
 
-1. **Define the descriptor in `core/config/organization-model.ts`** -- Add the OM Resource descriptor under `resources.entries` so identity, System membership, owner role, and governance status are authored once.
-
-2. **Define the contract in `core/types/`** -- Add Zod schemas and inferred types to `core/types/index.ts` (or a new file under `core/types/`).
-
-3. **Implement the workflow in `operations/src/`** -- Create a new directory under `operations/src/` for the feature. Import the descriptor, derive runtime `resourceId` / `type` from it, export the workflow from its `index.ts`, and register it in `operations/src/index.ts`.
-
-4. **Add the UI in `ui/src/routes/`** -- Create a new route file. Use TanStack Query to call the workflow execution endpoint. Import schemas from `@core/types` for validation and type inference.
-
-5. **Deploy and verify:**
+1. **Define the descriptor in `core/config/organization-model.ts`** -- Add the OM Resource descriptor under the id-keyed `resources` map so identity, System membership, owner role, and governance status are authored once.
+
+2. **Model the semantic surface** -- Add durable business nouns, verbs, catalogs, links, events, and surfaces to the owning System's `ontology`; bind executable Resources through `resource.ontology.actions` and optional `resource.ontology.primaryAction`; add system-local defaults/settings to `System.config`; add explanatory or governing material to `knowledge`; and keep transient DTOs and handler internals out of the OM. Top-level `entities`, top-level `actions`, and `System.content` are compatibility mirrors only when current published consumers still need them.
+
+3. **Define the contract in `core/types/`** -- Add Zod schemas and inferred types to `core/types/index.ts` (or a new file under `core/types/`). Use `core/types/entities.ts` when workflows operate on project-specific entity contracts.
+
+4. **Implement the workflow in `operations/src/`** -- Create a new directory under `operations/src/` for the feature. Import the descriptor, derive runtime `resourceId`, `type`, `name`, and `description` from it, export the workflow from its `index.ts`, and register it in `operations/src/index.ts`.
+
+5. **Add the UI in `ui/src/routes/`** -- Create a new route file. Use TanStack Query to call the workflow execution endpoint. Import schemas from `@core/types` for validation and type inference. Read OM resources, ontology, knowledge, and graph data where possible instead of creating page-local semantic registries.
+
+6. **Update rules when the pattern persists** -- If the workflow introduces a reusable adapter pattern, checkpoint/schedule convention, domain vocabulary, or workflow family behavior that future agents must follow, update this rule or add a scoped rule under `.claude/rules/` in the same change.
+
+7. **Deploy and verify:**
 
 ```bash
 pnpm -C operations check        # validate resource definitions
@@ -47,14 +51,14 @@ pnpm -C operations deploy       # deploy to dev
 
 ## Resource Registry
 
-`operations/src/index.ts` default-exports a `DeploymentSpec` with `version`, `organizationModel`, `workflows`, `agents`, and optional topology-oriented metadata such as `triggers`, `integrations`, `relationships`, `humanCheckpoints`, and `externalResources`. Each feature group exports `workflows` and `agents` arrays from its own `index.ts`, spread into the top-level spec. `DeploymentSpec` assembles deployable behavior; it should not be treated as a second resource identity catalog.
+`operations/src/index.ts` default-exports a `DeploymentSpec` with `version`, `organizationModel`, `workflows`, `agents`, and optional deployment mechanics such as `triggers`, `integrations`, `relationships`, `humanCheckpoints`, and `externalResources`. Durable operational wiring belongs in `organizationModel.topology.relationships`; deployment mechanics, credentials, provider webhook details, and per-run state stay outside the OM. Each feature group exports `workflows` and `agents` arrays from its own `index.ts`, spread into the top-level spec. `DeploymentSpec` assembles deployable behavior; it should not be treated as a second resource identity catalog.
 
 When you need breadth first, read:
 
-- `operations/src/README.md` for the source boundary and drill-down guidance
-- `core/config/organization-model.ts` for descriptor identity and governance metadata
-- `operations/src/index.ts` for deployment assembly
-- `pnpm elevasis-sdk project:list --pretty` for the live deployed surface
+- `operations/src/README.md` for the source boundary and drill-down guidance
+- `core/config/organization-model.ts` for descriptor identity and governance metadata
+- `operations/src/index.ts` for deployment assembly
+- `pnpm elevasis-sdk project:list --pretty` for the live deployed surface
 
 ## Commands
 
@@ -66,3 +70,11 @@ When you need breadth first, read:
 | `pnpm -C operations deploy:prod` | Deploy to production          |
 
 Always run `check` before `deploy`.
+
+## Rule Updates
+
+When developing resources, workflows, agents, integrations, checkpoints, schedules, or recurring operational conventions, keep `.claude/rules/` current.
+
+- Update `operations.md` for package-wide operations invariants.
+- Add a scoped rule for domain-specific workflow families whose conventions should autoload for future edits.
+- Do not bury durable operational rules only in task notes or chat context.