@elevasis/sdk 1.55.0 → 1.57.0

package/dist/index.js

@@ -1,2 +1,2 @@
-export { ActivityEventSchema, BuildPlanSnapshotStepSchema, ProspectingBuildTemplateSchema as BuildTemplateSchema, ContractRefResolutionError, CrmStageKeySchema, CrmStateKeySchema, EmailSchema, ExecutionError, ListBuilderStageKeySchema, ProcessingStageStatusSchema, RegistryValidationError, ResourceRegistry, StepType, ToolingError, bindResourceDescriptor, compileBusinessOntologyValidationIndex, concurrentPool, createLeadGenStageValidators, defineContract, defineResource, defineResourceOntology, defineResources, defineSingleStepWorkflow, defineTopology, defineTopologyRelationship, defineWorkflowConfig, deriveActions, diagnosticOutput, integrationInput, isBuiltInReadinessProfile, isZodType, lookupReadinessProfile, parseTopologyNodeRef, registerReadinessProfile, resolveContractRef, runDiagnostic, splitName, topologyRef, topologyRelationship, validateDeclaredSystemInterfaceReadiness, validateResourceGovernance } from './chunk-R3J6BEPO.js';
+export { ActivityEventSchema, BuildPlanSnapshotStepSchema, ProspectingBuildTemplateSchema as BuildTemplateSchema, ContractRefResolutionError, CrmStageKeySchema, CrmStateKeySchema, EmailSchema, ExecutionError, ListBuilderStageKeySchema, ProcessingStageStatusSchema, RegistryValidationError, ResourceRegistry, StepType, ToolingError, bindResourceDescriptor, compileBusinessOntologyValidationIndex, compileCrmActionCatalog, compileCrmApiOntologyValidationIndex, concurrentPool, createLeadGenStageValidators, defineContract, defineResource, defineResourceOntology, defineResources, defineSingleStepWorkflow, defineTopology, defineTopologyRelationship, defineWorkflowConfig, deriveCompiledCrmActions, diagnosticOutput, integrationInput, isBuiltInReadinessProfile, isCompiledCrmActionAvailable, isZodType, lookupReadinessProfile, parseTopologyNodeRef, registerReadinessProfile, resolveContractRef, runDiagnostic, splitName, topologyRef, topologyRelationship, validateDeclaredSystemInterfaceReadiness, validateResourceGovernance } from './chunk-HDMMMDIR.js';
 export { projectDeploymentSpec, projectTopologyRelationships, toSdkResourceDescriptor, withPlatformAgentResourceDescriptor, withPlatformAgentResourceDescriptors, withPlatformIntegrationResourceDescriptor, withPlatformIntegrationResourceDescriptors, withPlatformResourceDescriptor, withPlatformResourceDescriptors } from './chunk-QF2RNYYX.js';

package/dist/node/index.d.ts

@@ -44,15 +44,8 @@ interface KnowledgeNodeInput {
     summary: string;
     body: string;
 }
-interface KnowledgeSearchEntry {
-    id: string;
-    title: string;
-    summary: string;
-    bodyText: string;
-}
 interface CodegenResult {
     bodiesTsx: string;
-    searchIndex: KnowledgeSearchEntry[];
 }
 /**
  * Compiles knowledge nodes into generated file contents.
@@ -71,4 +64,4 @@ interface ResolvedKnowledgeLayout {
 declare function runKnowledgeCodegen(layout: ResolvedKnowledgeLayout): Promise<void>;
 
 export { generateKnowledgeBodies, generateKnowledgeNodes, generateKnowledgeNodesTs, readKnowledgeNodeMdx, runKnowledgeCodegen };
-export type { CodegenResult, GenerateKnowledgeNodesOptions, GenerateKnowledgeNodesResult, KnowledgeCodegenNode, KnowledgeKind, KnowledgeNodeInput, KnowledgeSearchEntry, ResolvedKnowledgeLayout };
+export type { CodegenResult, GenerateKnowledgeNodesOptions, GenerateKnowledgeNodesResult, KnowledgeCodegenNode, KnowledgeKind, KnowledgeNodeInput, ResolvedKnowledgeLayout };

package/dist/node/index.js

@@ -393,9 +393,6 @@ To add a component:
     );
   }
 }
-function stripToPlainText(body) {
-  return body.replace(/^(import|export)\s+.+$/gm, "").replace(/<[A-Z][^>]*>/g, "").replace(/<\/[A-Z][^>]*>/g, "").replace(/^#{1,6}\s+/gm, "").replace(/[*_`~]/g, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/\n{3,}/g, "\n\n").trim();
-}
 var BODIES_HEADER = [
   "// @generated by generate-knowledge-bodies -- DO NOT EDIT",
   "// Regenerate: pnpm scaffold:sync",
@@ -457,11 +454,10 @@ async function generateKnowledgeBodies(nodes) {
       "> = {}",
       ""
     ].join("\n");
-    return { bodiesTsx: bodiesTsx2, searchIndex: [] };
+    return { bodiesTsx: bodiesTsx2 };
   }
   const nodeComments = [];
   const mapEntries = [];
-  const searchIndex = [];
   for (const node of nodes) {
     if (/^(import|export)\s+/m.test(node.body)) {
       throw new Error(
@@ -475,15 +471,13 @@ async function generateKnowledgeBodies(nodes) {
     });
     const fnBodyCode = String(compiled);
     validateComponents(node.id, fnBodyCode);
-    const bodyText = stripToPlainText(node.body);
-    searchIndex.push({ id: node.id, title: node.title, summary: node.summary, bodyText });
     nodeComments.push(`// Node: ${node.id} (${node.kind})`);
     mapEntries.push(`  '${node.id}': makeKnowledgeComponent(${JSON.stringify(fnBodyCode)})`);
   }
   const mapBlock = `export const KNOWLEDGE_BODIES: Record<string, ComponentType<KnowledgeBodyProps>> = {
 ` + mapEntries.join(",\n") + "\n}\n";
   const bodiesTsx = BODIES_HEADER + FACTORY_BLOCK + MAP_HEADER + (nodeComments.length > 0 ? nodeComments.join("\n") + "\n\n" : "") + mapBlock;
-  return { bodiesTsx, searchIndex };
+  return { bodiesTsx };
 }
 async function runKnowledgeCodegen(layout) {
   let nodes;
@@ -504,14 +498,9 @@ async function runKnowledgeCodegen(layout) {
     });
     nodes = result.nodes;
   }
-  const { bodiesTsx, searchIndex } = await generateKnowledgeBodies(nodes);
+  const { bodiesTsx } = await generateKnowledgeBodies(nodes);
   mkdirSync(layout.generatedDir, { recursive: true });
   writeFileSync(resolve(layout.generatedDir, "knowledge-bodies.tsx"), bodiesTsx, "utf8");
-  writeFileSync(
-    resolve(layout.generatedDir, "knowledge-search-index.json"),
-    JSON.stringify(searchIndex, null, 2) + "\n",
-    "utf8"
-  );
 }
 
 export { generateKnowledgeBodies, generateKnowledgeNodes, generateKnowledgeNodesTs, readKnowledgeNodeMdx, runKnowledgeCodegen };

package/dist/test-utils/index.js

@@ -1,5 +1,5 @@
-import { executeWorkflow } from '../chunk-72ZGICTR.js';
-import { validateDeploymentSpec, validateRelationships } from '../chunk-R3J6BEPO.js';
+import { executeWorkflow } from '../chunk-3XEHBMWM.js';
+import { validateDeploymentSpec, validateRelationships } from '../chunk-HDMMMDIR.js';
 import '../chunk-QF2RNYYX.js';
 import { vi } from 'vitest';
 

package/dist/worker/index.js

@@ -1,3 +1,3 @@
-export { ListBuilderResultSchema, ListBuilderResultsSchema, PlatformToolError, acqDb, approval, artifacts, classifyPlatformToolError, content, createAdapter, createAnymailfinderAdapter, createApifyAdapter, createAttioAdapter, createCaptionGenerationWorkflow, createCaptureInstagramMetricsWorkflow, createClickUpAdapter, createDropboxAdapter, createGmailAdapter, createGoogleSheetsAdapter, createImageAnalysisWorkflow, createInstagramAdapter, createInstantlyAdapter, createMillionVerifierAdapter, createPublishInstagramWorkflow, createResendAdapter, createSignatureApiAdapter, createStripeAdapter, createTombaAdapter, crm, email, executeWorkflow, execution, generateHmacToken, list, listBuilderWorkflow, llm, notifications, pdf, platform, projects, scheduler, startWorker, storage, toContentMetrics } from '../chunk-72ZGICTR.js';
-import '../chunk-R3J6BEPO.js';
+export { ListBuilderResultSchema, ListBuilderResultsSchema, PlatformToolError, acqDb, approval, artifacts, classifyPlatformToolError, content, createAdapter, createAnymailfinderAdapter, createApifyAdapter, createAttioAdapter, createCaptionGenerationWorkflow, createCaptureInstagramMetricsWorkflow, createClickUpAdapter, createDropboxAdapter, createGmailAdapter, createGoogleSheetsAdapter, createImageAnalysisWorkflow, createInstagramAdapter, createInstantlyAdapter, createMillionVerifierAdapter, createPublishInstagramWorkflow, createResendAdapter, createSignatureApiAdapter, createStripeAdapter, createTombaAdapter, crm, email, executeWorkflow, execution, generateHmacToken, list, listBuilderWorkflow, llm, notifications, pdf, platform, projects, scheduler, startWorker, storage, toContentMetrics } from '../chunk-3XEHBMWM.js';
+import '../chunk-HDMMMDIR.js';
 import '../chunk-QF2RNYYX.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.55.0",
+  "version": "1.57.0",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -63,8 +63,8 @@
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
     "zod": "^4.1.0",
-    "@repo/core": "0.71.0",
     "@repo/eslint-config": "0.0.0",
+    "@repo/core": "0.73.0",
     "@repo/typescript-config": "0.0.0"
   },
   "license": "MIT",

package/reference/_navigation.md

@@ -162,7 +162,7 @@ Package entries indexed: 63.
 | Theme | `packages/ui/src/theme/README.md` | Published theme entry for downstream applications. | (not specified) |
 | Graph | `packages/ui/src/graph/README.md` | Published graph helper and visualization entry. | (not specified) |
 | Theme Presets | `packages/ui/src/theme/presets/README.md` | Published THEME_PRESETS tuple, ThemePresetName union, and ThemePresetEnum Zod enum, defined locally and kept manually aligned with the canonical list in packages/core/src/auth/multi-tenancy/theme-presets.ts. | (not specified) |
-| Knowledge | `packages/ui/src/knowledge/README.md` | Published knowledge browser primitives: Browser, Tree, NodeList, NodeView, SearchBar, MDX provider, and the generated KNOWLEDGE_BODIES map. | (not specified) |
+| Knowledge | `packages/ui/src/knowledge/README.md` | Published knowledge browser primitives: Browser, Tree, NodeList, NodeView, SearchBar, MDX provider, and the KnowledgeBodiesMap type. Machinery only -- each consumer supplies its own compiled corpus via the required knowledgeBodies prop. | (not specified) |
 
 ---
 
@@ -194,7 +194,7 @@ Universal scaffold documentation for all SDK projects. Source locations are co-l
 | Build and Extend CRM | `scaffold/recipes/extend-crm.md` | Map the CRM platform primitives available to SDK projects: shared UI pages, sidebar composition, data hooks, action definitions, workflow adapters, System Interfaces, and org-model extension boundaries. |
 | Build and Extend Lead Gen | `scaffold/recipes/extend-lead-gen.md` | Map the lead-gen platform primitives available to SDK projects: shared UI pages, provider-injected Organization Model config, data hooks, list/member state, artifacts, workflow adapters, System Interfaces, and tenant-owned extension boundaries. |
 | Build and Extend Content | `scaffold/recipes/extend-content.md` | Map the content platform primitives available to SDK projects: pipeline and step catalogs, shared review/pipeline/distribution pages, data hooks, the content workflow adapter, and org-model extension boundaries. |
-| Customize CRM Actions | `scaffold/recipes/customize-crm-actions.md` | Add, hide, or replace CRM deal action buttons in a template-derived project, and override default platform action workflows with project-owned implementations. |
+| Customize CRM Actions | `scaffold/recipes/customize-crm-actions.md` | Add, hide, reorder, or re-implement CRM deal action buttons by authoring them in your project's Organization Model and deploying the workflows they dispatch to. |
 | Customize Knowledge Browser | `scaffold/recipes/customize-knowledge-browser.md` | Author knowledge nodes and customize the Knowledge Browser in a template-derived project -- from zero-config authoring through sidebar composition, custom dispatchers, and direct query access. |
 | Query the Knowledge Graph | `scaffold/recipes/query-the-knowledge-graph.md` | Use the `knowledge:*` CLI subcommands on `elevasis-sdk` (external projects) and `elevasis` (monorepo) to browse, inspect, and traverse the OrganizationModel knowledge graph via six mount axes. |
 | Workflow Recipes | `scaffold/operations/workflow-recipes.md` | Anatomy of a workflow, adapter usage, and trigger patterns -- runnable email-notification example replaces the trivial echo workflow. Resolves eval score 2/5 on workflow authoring. |
@@ -226,9 +226,9 @@ Agent rules indexed: 19.
 | Platform | `rules/platform.md` | Platform conventions -- SDK workflows, agents, deployment, resource registry | Authoring a workflow or agent definition, or registering a resource in the registry. |
 | Deployment | `rules/deployment.md` | Deployment workflow -- check-first, dev vs prod, version bumping, common errors | Before any deploy -- a plain `run deploy` targets production by default. |
 | Content | `rules/content.md` | Building the content System behind the shipped pipeline, item, and distribution routes -- which recipe to read, and the catalog vocabulary that is model-owned rather than coded | Editing anything under `ui/src/routes/content/` -- items, pipelines, distributions, or a review gate. |
-| Execution Model | `rules/execution.md` | Execution model -- timeouts, memory, concurrency, org isolation, runtime constraints | Hitting a timeout, memory ceiling, concurrency limit, or org-isolation question at runtime. |
+| Execution Model | `rules/execution.md` | Execution model -- per-step and agent timeouts, spend ceilings, memory, concurrency, org isolation | Hitting a timeout, memory ceiling, concurrency limit, or org-isolation question at runtime. |
 | Agent Runtime | `rules/agent-runtime.md` | Agent runtime behavior -- iteration response shape, session memory and replay, prose normalization, and why a redeploy is what makes a platform fix live | Debugging an agent turn -- a missing reply, a corrupted one, a session that forgot, or an unenforced schema. |
-| Error Handling | `rules/error-handling.md` | Error handling -- ExecutionError vs PlatformToolError, retry logic, no auto-retry | Writing or debugging a step handler that throws, catches, or retries. |
+| Error Handling | `rules/error-handling.md` | Error handling -- ExecutionError vs PlatformToolError, retry logic, no auto-retry, /api/external error envelope | Writing or debugging a step handler that throws, catches, or retries. |
 | Observability | `rules/observability.md` | Observability -- context.logger API, execution inspection, step-level context | Adding logging to a step handler, or inspecting a past execution. |
 
 ### Orientation

package/reference/_reference-manifest.json

@@ -875,7 +875,7 @@
       "subpath": "./knowledge",
       "kind": "subpath",
       "title": "Knowledge",
-      "description": "Published knowledge browser primitives: Browser, Tree, NodeList, NodeView, SearchBar, MDX provider, and the generated KNOWLEDGE_BODIES map.",
+      "description": "Published knowledge browser primitives: Browser, Tree, NodeList, NodeView, SearchBar, MDX provider, and the KnowledgeBodiesMap type. Machinery only -- each consumer supplies its own compiled corpus via the required knowledgeBodies prop.",
       "group": "Visual",
       "order": 3,
       "sourcePath": "packages/ui/src/knowledge/index.ts",
@@ -948,7 +948,7 @@
     {
       "packageName": "@elevasis/sdk",
       "title": "Execution Model",
-      "description": "Execution model -- timeouts, memory, concurrency, org isolation, runtime constraints",
+      "description": "Execution model -- per-step and agent timeouts, spend ceilings, memory, concurrency, org isolation",
       "group": "Operations",
       "order": 4,
       "loadWhen": "Hitting a timeout, memory ceiling, concurrency limit, or org-isolation question at runtime.",
@@ -968,7 +968,7 @@
     {
       "packageName": "@elevasis/sdk",
       "title": "Error Handling",
-      "description": "Error handling -- ExecutionError vs PlatformToolError, retry logic, no auto-retry",
+      "description": "Error handling -- ExecutionError vs PlatformToolError, retry logic, no auto-retry, /api/external error envelope",
       "group": "Operations",
       "order": 6,
       "loadWhen": "Writing or debugging a step handler that throws, catches, or retries.",

package/reference/index.mdx

@@ -33,7 +33,7 @@ You do not need all three packages. A pure automation project needs only `@eleva
 
 ### @elevasis/sdk (v1.48.0)
 
-The primary developer package. Provides the TypeScript API for defining workflows and agents, the `elevasis-sdk` CLI for validation and deployment, and typed worker adapters for 27 platform and integration tools.
+The primary developer package. Provides the TypeScript API for defining workflows and agents, the `elevasis-sdk` CLI for validation and deployment, and typed worker adapters for 28 platform and integration tools.
 
 **Install:** `pnpm add @elevasis/sdk`
 

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

@@ -1,33 +1,33 @@
-# @elevasis/ui/knowledge
-
-Read-only browser primitives for the Organization Model knowledge graph.
-
-## Surface
-
-| Export                                                                 | Purpose                                                                             |
-| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `KnowledgeBrowser`                                                     | Selected-node detail pane. Tree/search now live in the feature sidebar.             |
-| `KnowledgeTree`                                                        | By-feature primary tree with hierarchical features and multi-governance duplication. |
-| `KnowledgeNodeList`                                                    | Legacy flat list of node summary cards; exported for compatibility.                 |
-| `KnowledgeNodeView`                                                    | Single knowledge-node detail view using `NodeDescribeShell` and relationship groups. |
-| `KnowledgeSearchBar`                                                   | Client-side search over `_generated/knowledge-search-index.json`.                   |
+# @elevasis/ui/knowledge
+
+Read-only browser primitives for the Organization Model knowledge graph.
+
+## Surface
+
+| Export                                                                 | Purpose                                                                                                        |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `KnowledgeBrowser`                                                     | Selected-node detail pane. Tree/search now live in the feature sidebar.                                        |
+| `KnowledgeTree`                                                        | By-feature primary tree with hierarchical features and multi-governance duplication.                           |
+| `KnowledgeNodeList`                                                    | Legacy flat list of node summary cards; exported for compatibility.                                            |
+| `KnowledgeNodeView`                                                    | Single knowledge-node detail view using `NodeDescribeShell` and relationship groups.                           |
+| `KnowledgeSearchBar`                                                   | Client-side search built in-memory from the live `knowledgeNodes` prop.                                        |
 | `KnowledgeNodeDetailRouteView`                                         | Shared `/knowledge/$nodeId` content route view; apps keep TanStack route adapters and navigation wiring local. |
-| `KnowledgeRouteIds` helpers                                            | Decode route ids, resolve Knowledge route targets, and derive route labels for app-local breadcrumbs. |
-| `KnowledgeSidebarMiddle`                                               | Deprecated legacy sidebar middle section; active sidebar lives under `features/knowledge/sidebar`. |
-| `KNOWLEDGE_ITEMS`                                                      | Deprecated default sidebar nav items retained for compatibility.                    |
-| `KnowledgeMDXProvider`, `useKnowledgeAllowlist`, `KNOWLEDGE_ALLOWLIST` | MDX runtime allowlist (`Card`, `Cards`, `Step`, `Steps`, `Callout`, `Tab`, `Tabs`). |
-| `KNOWLEDGE_BODIES`                                                     | Build-time-compiled MDX components keyed by node id.                                |
-
-## Customization tiers
-
-1. **Default** — mount `knowledgeManifest` from `@elevasis/ui/features/knowledge`.
-2. **Extend** — pass `extraComponents` to `KnowledgeMDXProvider` or compose around the feature sidebar primitives.
-3. **Replace** — call `@elevasis/core/knowledge` queries directly from project-owned routes.
-
-## Codegen
-
-`KNOWLEDGE_BODIES` and the search index are regenerated by `pnpm scaffold:sync` (or `pnpm knowledge:generate` to run only the knowledge step). Source: `canonicalOrganizationModel.knowledge.nodes` from `@repo/elevasis-core`.
-
-The Vite plugin at `@elevasis/ui/vite-plugin-knowledge` re-runs codegen on `buildStart` and watches the OM source dir for HMR.
-
-Phase 1 is read-only. Phase 2 will move bodies into Supabase and ship via `mdx-bundler`.
+| `KnowledgeRouteIds` helpers                                            | Decode route ids, resolve Knowledge route targets, and derive route labels for app-local breadcrumbs.          |
+| `KnowledgeSidebarMiddle`                                               | Deprecated legacy sidebar middle section; active sidebar lives under `features/knowledge/sidebar`.             |
+| `KNOWLEDGE_ITEMS`                                                      | Deprecated default sidebar nav items retained for compatibility.                                               |
+| `KnowledgeMDXProvider`, `useKnowledgeAllowlist`, `KNOWLEDGE_ALLOWLIST` | MDX runtime allowlist (`Card`, `Cards`, `Step`, `Steps`, `Callout`, `Tab`, `Tabs`).                            |
+| `KnowledgeBodiesMap`                                                   | Type for the compiled MDX-component-by-node-id map. `@elevasis/ui` ships this type only, not a corpus.         |
+
+## Customization tiers
+
+1. **Default** — mount `knowledgeManifest` from `@elevasis/ui/features/knowledge`.
+2. **Extend** — pass `extraComponents` to `KnowledgeMDXProvider` or compose around the feature sidebar primitives.
+3. **Replace** — call `@elevasis/core/knowledge` queries directly from project-owned routes.
+
+## Codegen
+
+This package ships the machinery only, not a compiled corpus. Each consumer generates its own `knowledge-bodies.tsx` (matching `KnowledgeBodiesMap`) beside its own Organization Model and hands it to `ElevasisSystemsProvider` as the required `knowledgeBodies` prop. In the monorepo that lives at `packages/elevasis/core/config/knowledge/_generated/`, sourced from `canonicalOrganizationModel.knowledge.nodes`; in an external project it lives at `<project-root>/core/config/knowledge/_generated/`. Regenerate with `pnpm scaffold:sync` (or `pnpm knowledge:generate` for only the knowledge step).
+
+The Vite plugin at `@elevasis/ui/vite-plugin-knowledge` re-runs codegen on `buildStart` and watches the OM source dir for HMR.
+
+Phase 1 is read-only. Phase 2 will move bodies into Supabase and ship via `mdx-bundler`.

package/reference/rules/agent-start-here.md

@@ -103,7 +103,7 @@ Load first:
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md`
 - Typed feature and surface ID constants exported from `@elevasis/core/organization-model` (`SALES_FEATURE_ID`, `PROSPECTING_LISTS_SURFACE_ID`, and the rest). Always use these constants instead of magic strings when overriding feature/surface IDs; the full list is enumerated in `.claude/rules/organization-os.md`.
-- The `extend-crm.md`, `extend-lead-gen.md`, and `customize-crm-actions.md` recipes listed under Class 1 -- CRM and lead gen are Organization OS + UI + hooks + workflow-adapter surfaces, and CRM action buttons are not `sales.actions` org-model config in v1 (use the recipe's provider/custom-button path).
+- The `extend-crm.md`, `extend-lead-gen.md`, and `customize-crm-actions.md` recipes listed under Class 1 -- CRM and lead gen are Organization OS + UI + hooks + workflow-adapter surfaces, and CRM deal action buttons come from your own `sales.crm` ontology `actionTypes` records rather than any `sales.actions` field (the recipe shows the record shape and the provider wiring).
 
 Then inspect:
 

package/reference/rules/error-handling.md

@@ -1,5 +1,5 @@
 ---
-description: Error handling -- ExecutionError vs PlatformToolError, retry logic, no auto-retry
+description: Error handling -- ExecutionError vs PlatformToolError, retry logic, no auto-retry, /api/external error envelope
 paths:
   - operations/**
 ---
@@ -41,6 +41,17 @@ try {
 }
 ```
 
+## What Your Handler May Throw
+
+`ExecutionError` is the class to throw from workflow and agent code. It carries a `context` record
+and an `isRetryable()` the engine reads, which is why it is preferable to a bare `Error` -- a plain
+throw arrives at the platform with no classification and no structured context.
+
+Handler code runs in a worker thread, not in an API request. A throw there becomes an **execution
+failure** recorded against the execution -- it never becomes an HTTP response body, so there is no
+status code to pick and no envelope to shape. The envelope below is what you _receive_ when you call
+the platform's own API, not what your handler produces.
+
 ## 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.
@@ -60,6 +71,44 @@ The platform does NOT automatically retry failed steps. Your handler is responsi
 | `credentials_invalid` | No        | Credential not found or expired   |
 | `validation_error`    | No        | Invalid parameters passed to tool |
 
+## Error Bodies From `/api/external/*`
+
+Every `/api/external/*` route returns the same error envelope. Tenants are the only consumers of
+these routes, so this is the shape your API-key client parses:
+
+```json
+{
+  "error": "human-readable message",
+  "code": "VALIDATION_ERROR",
+  "requestId": "correlates with server logs",
+  "fields": { "newResourceId": ["must differ from oldResourceId"] }
+}
+```
+
+`error` and `code` are always present. `requestId` is present on every error response -- quote it
+when reporting a problem. `fields` appears only when the request body itself failed schema
+validation. `retryAfter` (seconds) accompanies `RATE_LIMIT_EXCEEDED`, and `details` carries a
+structured payload on some conflicts.
+
+**`POST /api/external/resources/rename` changed shape -- read `code`, not just `error`.** It used to
+build `{ error, code }` by hand, and then briefly returned `code: "VALIDATION_ERROR"` with a 400 for
+_every_ failure, including ones that were not your fault. It now states the real cause:
+
+| Failure                                       | Status | `code`                             |
+| --------------------------------------------- | ------ | ---------------------------------- |
+| Body fails schema validation                  | 400    | `VALIDATION_ERROR` (with `fields`) |
+| `newResourceId` already has execution history | 409    | `CONFLICT`                         |
+| A database query or update failed             | 500    | `INTERNAL_SERVER_ERROR`            |
+
+A client that branched on "400 means my input was wrong" now needs to distinguish 409 (rename to a
+different id) from 500 (retry or report). A client reading only `error` as its diagnostic silently
+loses that distinction -- the message text is not a stable contract, and `code` is.
+
+**On any 5xx, `error` is generic by design.** The platform suppresses server-fault messages, so a 500
+reads `"Internal server error"` rather than what actually broke -- that sentence was written for
+whoever fixes the server, and it stays in the server's logs. `requestId` is what joins your failure
+to that log line, so quote it when you report a 5xx rather than the message.
+
 ## CLI Transport Failures
 
 These are errors in the CLI you type commands into, not in your handler code. They are worth knowing because the natural reaction to one of them is the wrong reaction.

package/reference/rules/execution.md

@@ -1,5 +1,5 @@
 ---
-description: Execution model -- timeouts, memory, concurrency, org isolation, runtime constraints
+description: Execution model -- per-step and agent timeouts, spend ceilings, memory, concurrency, org isolation
 paths:
   - operations/**
 ---
@@ -15,15 +15,71 @@ Each execution runs in an isolated Node.js worker thread spawned from the deploy
 
 ## 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                                                  |
+| Constraint | Workflows                       | Agents                                         |
+| ---------- | ------------------------------- | ---------------------------------------------- |
+| Timeout    | 2h execution ceiling            | 2h ceiling, lower it 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.
+- The ceiling is a safety net against a runaway loop, not a duration budget. Bound the work you
+  actually want bounded with a per-step `timeout` (below) or `constraints.timeout`, rather than
+  relying on the ceiling to stop it.
+
+## Per-Step Timeouts
+
+A workflow step may declare its own millisecond ceiling:
+
+| Field                  | Applies to    | Omitted                                               |
+| ---------------------- | ------------- | ----------------------------------------------------- |
+| `WorkflowStep.timeout` | one step      | the step is bounded only by the 2h execution ceiling  |
+| `constraints.timeout`  | a whole agent | the agent is bounded only by the 2h execution ceiling |
+
+`WorkflowConfig` has no `constraints` field on purpose. A per-workflow override would only restate
+the execution ceiling; "this HTTP call should never take more than 5 seconds" is a property of the
+step and has nowhere else to live.
+
+**The two timeout failures are not the same failure, and the difference is whether a retry can
+work.** A step that breaches its own `timeout` while the workflow still has budget left fails
+**retryably** -- a slow third-party call is exactly what a retry exists for. A workflow that reaches
+the 2h execution ceiling fails **non-retryably**: there is no budget left to retry inside. Neither
+error class is exported from `@elevasis/sdk`, so branch on your own step's outcome rather than on
+`instanceof`; the retryability distinction is what determines whether re-running is worth anything.
+
+Declare a `timeout` on any step that calls something you do not control. Without one, a hung
+integration call holds the whole workflow open for two hours.
+
+## Agent Spend Guards
+
+`maxIterations` and `timeout` bound how MANY model calls an agent makes and how LONG it runs.
+Neither bounds how much those calls cost. An agent on a large context or an expensive model can
+spend without limit inside a budget it is technically respecting. Three `AgentConstraints` fields
+close that:
+
+| Constraint               | Bounds                                           | Default             |
+| ------------------------ | ------------------------------------------------ | ------------------- |
+| `maxCostUsd`             | total USD across every AI call in the turn       | unset -- no ceiling |
+| `maxTotalTokens`         | total input + output tokens across every AI call | unset -- no ceiling |
+| `maxIdenticalIterations` | consecutive byte-identical plans before stopping | 3                   |
+
+Set at least one of the first two on any agent you are not watching. Unset is genuinely unbounded,
+not "bounded by something sensible".
+
+**Reaching a spend ceiling fails the execution.** The stop reason is `spend_exhausted`, and the
+worker reports `status: 'failed'` with `AgentSpendExhaustedError` -- deliberately, because an agent
+that stopped at its ceiling did not finish its work, and reporting that as success is what makes the
+failure mode invisible. Whatever the agent synthesized still travels on the failed result, so a
+partial answer is not lost.
+
+`spend_exhausted` is kept distinct from `budget_exhausted` (the `maxIterations` stop) because the
+right response differs: an agent out of iterations may just need a larger `maxIterations`, while one
+out of spend is the ceiling doing its job. Read the stop reason before raising either limit.
+
+Ceilings are enforced only where the platform injects a usage collector, which is every
+coordinator-run execution. Note that a **synchronous nested execution shares its parent's
+collector**, so a parent's ceiling covers the agent and everything it invokes synchronously -- and
+can therefore be reached by a child's spend.
 
 ## Concurrency
 

package/reference/rules/organization-model.md

@@ -59,7 +59,7 @@ Bare `/om` runs the layered flow (identity → customers → offerings → roles
 
 Do not author Resource `actionKey` in the target contract. Runtime/UI routing that needs a single selectable action should read `resource.ontology.primaryAction`.
 
-Do not add `sales.actions` to the org model -- the v1 server-side override surface is intentionally deferred. Customize deal actions through `scaffold/recipes/customize-crm-actions.md` instead.
+There is no `sales.actions` field -- do not add one. CRM deal actions are `actionTypes` records in the `sales.crm` System's `ontology` scope, each carrying `label`, `order`, `resourceId`, and `availableFrom`, with the ontology local id as the dispatch key. `compileCrmActionCatalog` turns them into the deal panel's buttons. See `scaffold/recipes/customize-crm-actions.md`.
 
 ## `System.apiInterface`
 
@@ -77,10 +77,11 @@ Do not confuse ontology `interface` records with `system.apiInterface`. Ontology
 
 ### Readiness contract authoring
 
-Three rules govern what you may write inside an `apiInterface`, all enforced at deploy preflight:
+Four rules govern what you may write inside an `apiInterface`, all enforced at deploy preflight:
 
 - **`readinessProfile` must be declared explicitly. There is no positional fallback.** An omitted value resolves to `undefined` and produces a `missing-readiness-profile` diagnostic -- it does **not** fall back to `${systemPath}.${interfaceKey}`. That fallback was removed because it coupled profile identity to tree position: a System sitting at a path that happened to match a built-in profile id (say `sales.crm`) silently inherited that built-in's requirements without ever declaring one.
 - **A `readinessContract` must list at least one entry in `requiredCatalogs`.** An empty or omitted list no longer parses, so a contract that asserts nothing fails at deploy rather than passing silently.
+- **Never declare a `readinessContract` beside a built-in profile** (`sales.lead-gen.api`, `sales.crm.api`, `sales.lead-gen.crm-handoff`). A platform validator already covers those, so a contract there would be ignored at runtime; deploy preflight and `om:doctor` reject it as `readiness-contract-on-built-in-profile`. Only contract-validated profiles such as `content.api` take one.
 - **`resourceIds` must scope real resources.** An empty array used to skip readiness validation entirely, which made deploy and runtime disagree -- deploy passed and the API then returned 503. If a stub marker exists, either scope it or remove the marker; absence is the designed opt-out.
 
 `profileForInterface` is removed. It had degraded to an identity function returning its third argument; read `apiInterface?.readinessProfile` directly.