@elevasis/sdk 1.44.2 → 1.45.0

package/reference/sdk/index.mdx

@@ -48,6 +48,9 @@ See [Platform Tools](platform-tools/index.mdx) for the full catalog, adapter ref
 - [Resources](resources/index.mdx) - Workflow and agent definition patterns, Zod schemas, step types, and routing
 - [Platform Tools](platform-tools/index.mdx) - Full catalog of 25 adapters (13 integration + 12 platform), integration adapters, and credential management
 - [Credential Security](platform-tools/index.mdx#credential-security) - Three-layer credential model, HTTP tool patterns, and credential management
+- [Human-in-the-Loop Workflows](human-in-the-loop.mdx) - The full HITL story: approval adapter, checkpoint metadata, and queue resolution
+- [The Deployment Spec Pattern](project-deployment-spec.mdx) - projectDeploymentSpec and defineWorkflowConfig, the shape the template actually ships
+- [When to Reach for the define\* Builders](define-builders.mdx) - Judgment guide for defineWorkflow, defineResource, defineTopology, and friends
 
 ### Reference
 
@@ -65,13 +68,10 @@ See [Platform Tools](platform-tools/index.mdx) for the full catalog, adapter ref
 
 ### Framework
 
-- [Development Framework](framework/index.mdx) - How Claude Code helps you build: project structure, agent integration, memory, and documentation
+- [Development Framework](framework/index.mdx) - How Claude Code helps you build: project structure, agent integration, and the skill surface
 - [Project Structure](framework/project-structure.mdx) - Scaffolded file layout, domain barrels, src/index.ts entry point, and config files
-- [Agent Configuration](framework/agent.mdx) - Agent capabilities, tool access, model config, and Claude Code integration patterns
-- [Memory](framework/memory.mdx) - Agent memory system, session state, developer profiles, and workspace conventions
-- [Interaction Guidance](framework/interaction-guidance.mdx) - Skill dimension adaptation rules for platform navigation, API integration, and automation concepts
-- [Tutorial System](framework/tutorial-system.mdx) - Two-track onboarding (8 vibe-coder + 19 technical lessons), skill-adaptive lesson variants, progress tracking, and module contents
-- [Resource Documentation](framework/resource-documentation.mdx) - Docs directory structure, frontmatter schema, size limits, deploy behavior, and /docs command reference
+- [Agent Configuration](framework/agent.mdx) - The shipped skill inventory, project context via `project:*`, upgrades via `/git-sync`, and the ambient vibe layer
+- [Tutorial System](framework/tutorial-system.mdx) - Two-track onboarding: 8 vibe-coder lessons and 19 technical lessons across 5 sections, with track choice persisted to `profile.md`
 
 ### Resources Subpages
 
@@ -87,7 +87,6 @@ See [Platform Tools](platform-tools/index.mdx) for the full catalog, adapter ref
 
 - [Export Catalog](exports.mdx) - Auto-generated catalog of all published @elevasis/sdk subpath exports
 - [Troubleshooting](troubleshooting.mdx) - Static error catalog for CLI, deployment, schema, and runtime failures
-- [Roadmap](roadmap.mdx) - Planned features including error taxonomy, retry semantics, circuit breaker, and metrics
 
 ---
 

package/reference/sdk/platform-tools/index.mdx

@@ -11,6 +11,8 @@ Your SDK workflows have access to 25 adapters (13 integration + 12 platform) --
 
 **Preferred: Typed adapters** (available for all integration tools + key platform services)
 
+{/* doc-snippet:skip: illustrative excerpt with `...` elisions, not a standalone compilable file */}
+
 ```typescript
 import { createResendAdapter, scheduler, llm } from '@elevasis/sdk/worker'
 
@@ -25,6 +27,8 @@ const result = await llm.generate({ messages: [...] })
 
 **Fallback: `platform.call()`** (for tools without typed adapters)
 
+{/* doc-snippet:skip: illustrative excerpt with `...` elisions, not a standalone compilable file */}
+
 ```typescript
 import { platform } from '@elevasis/sdk/worker'
 
@@ -51,6 +55,8 @@ Integration credentials are never stored in `.env` and never available via `proc
 
 All platform tools resolve credentials server-side. The credential value never crosses the postMessage boundary into the worker.
 
+{/* doc-snippet:skip: continues from the `import { platform } from '@elevasis/sdk/worker'` shown in Usage above */}
+
 ```typescript
 // Credential 'my-gmail' is resolved server-side -- value never enters worker memory
 const result = await platform.call({
@@ -65,6 +71,8 @@ const result = await platform.call({
 
 For APIs without a dedicated adapter, use the `http` platform tool. Credentials are injected server-side before the outgoing request.
 
+{/* doc-snippet:skip: continues from the `import { platform } from '@elevasis/sdk/worker'` shown in Usage above */}
+
 ```typescript
 const result = await platform.call({
   tool: 'http',
@@ -93,6 +101,8 @@ const result = await platform.call({
 
 For third-party SDKs that require a raw key (e.g., `new Stripe(key)`), use `platform.getCredential()`. This explicitly causes the credential value to enter worker memory.
 
+{/* doc-snippet:skip: illustrative composition with the third-party `stripe` npm package -- that package is not installed in this doc-check project and is not an @elevasis import */}
+
 ```typescript
 import { platform } from '@elevasis/sdk/worker'
 
@@ -152,6 +162,8 @@ Supabase is a first-class integration adapter for persistent storage. Pass the `
 
 **Methods:** `insert`, `select`, `update`, `delete`, `upsert`, `rpc`, `count`
 
+{/* doc-snippet:skip: continues from the `import { platform } from '@elevasis/sdk/worker'` shown in Usage above */}
+
 ```typescript
 const qualified = await platform.call({
   tool: 'supabase',

package/reference/sdk/platform-tools/type-safety.mdx

@@ -15,6 +15,8 @@ The approach: tighten types where misconfiguration is a realistic foot-gun, and
 
 `provider` and `model` are required on `SDKLLMGenerateParams` in `packages/sdk/src/worker/adapters/llm.ts`. They were previously optional because the server-side `modelConfig` fallback in `tool-dispatcher.ts` would fill them in -- but that fallback is a foot-gun, not a feature. Omitting them silently selects a default model that may not be appropriate for the call site.
 
+{/* doc-snippet:skip: illustrative excerpt with `...` elisions, not a standalone compilable file */}
+
 ```typescript
 // Required -- both fields must be specified inline
 await llm.generate({
@@ -54,6 +56,8 @@ The `never` pattern on sibling fields causes TypeScript to error if you pass two
 
 `ApprovalToolMap.create.params` uses `context: Record<string, unknown>` instead of `context: unknown`. This prevents passing primitives (strings, numbers) as context -- approval tasks always expect a structured key-value object.
 
+{/* doc-snippet:skip: illustrative excerpt with `...` elisions, not a standalone compilable file */}
+
 ```typescript
 // Correct
 await approval.create({

package/reference/sdk/project-deployment-spec.mdx

@@ -0,0 +1,131 @@
+---
+title: The Deployment Spec Pattern
+description: How projectDeploymentSpec and defineWorkflowConfig assemble the DeploymentSpec a scaffolded project actually ships, using operations/src/index.ts as the reference.
+---
+
+[Resources](resources/index.mdx#deploymentspec) shows the minimal shape of a `DeploymentSpec`: a hand-built object literal with `version`, `organizationModel`, `workflows`, and `agents`. That shape type-checks, but it is not what a scaffolded project ships. The real `operations/src/index.ts` -- the file every agent is pointed at to register a new resource -- is built on two exports this bundle otherwise only mentions in passing: `projectDeploymentSpec` and `defineWorkflowConfig`. This page teaches that shape, using the shipped file as the reference point.
+
+## The Real File
+
+`external/_template/operations/src/index.ts` (the file `pnpm dlx @elevasis/sdk init` scaffolds for you) looks like this, trimmed to the parts that matter:
+
+{/* doc-snippet:skip: real-file excerpt with project-local path aliases, not a standalone compilable file */}
+
+```typescript
+import { projectDeploymentSpec, type DeploymentSpec } from '@elevasis/sdk'
+import {
+  canonicalOrganizationModel,
+  getTemplateAgentResourceDescriptor,
+  getTemplateWorkflowResourceDescriptor
+} from '@core/config/organization-model'
+import * as example from './example/index.js'
+import * as emailNotification from './email-notification/exports.js'
+import { triggers, integrations, humanCheckpoints } from './metadata.js'
+
+function getTemplateIntegrationResourceDescriptor(resourceId: string): never {
+  throw new Error(`No integration OM Resource descriptor for "${resourceId}".`)
+}
+
+type TemplateDeploymentSpec = DeploymentSpec & {
+  organizationModel: typeof canonicalOrganizationModel
+}
+
+const deploymentSpec: TemplateDeploymentSpec = {
+  ...projectDeploymentSpec({
+    version: '0.1.0',
+    organizationModel: canonicalOrganizationModel,
+    workflows: [...example.workflows, ...emailNotification.workflows],
+    agents: [...example.agents, ...emailNotification.agents],
+    triggers,
+    integrations,
+    humanCheckpoints,
+    getWorkflowResourceDescriptor: getTemplateWorkflowResourceDescriptor,
+    getAgentResourceDescriptor: getTemplateAgentResourceDescriptor,
+    getIntegrationResourceDescriptor: getTemplateIntegrationResourceDescriptor
+  }),
+  organizationModel: canonicalOrganizationModel
+}
+export default deploymentSpec
+```
+
+Four things are doing work here that the minimal literal example does not show: `projectDeploymentSpec` itself, the descriptor resolver functions passed into it, the feature-group `exports.ts` files being spread into `workflows`/`agents`, and `metadata.ts` supplying `triggers`/`integrations`/`humanCheckpoints`. Each is below.
+
+## `projectDeploymentSpec`: What It Actually Does
+
+`projectDeploymentSpec` takes your bare `WorkflowDefinition[]` / `AgentDefinition[]` / `IntegrationDefinition[]` arrays and, for every entry, injects `config.resource`, `config.resourceId`, and `config.type` from the matching Organization Model resource descriptor -- looked up through the resolver functions you pass in. You never write those three fields into a workflow's `config` by hand under this pattern; the workflow file only needs a `resourceId` that exists in the OM.
+
+It also computes `relationships` for you, by projecting `organizationModel.topology.relationships` into the `triggers` / `uses` edges the Command Center graph reads. The minimal `DeploymentSpec` recipe has you author `relationships` manually; under `projectDeploymentSpec`, that field is derived, not authored -- edit topology in the OM (via `/om`) rather than adding a `relationships` entry to `index.ts` by hand.
+
+The three resolver functions are required or optional depending on what you're deploying:
+
+- `getWorkflowResourceDescriptor` -- required. Looks up a workflow's `resourceId` in the OM `resources` map and throws if it is missing or not `kind: 'workflow'`.
+- `getIntegrationResourceDescriptor` -- required by the function signature, even if you have zero integrations. The template satisfies this with a function that always throws, since `integrations` starts empty -- it is never invoked while the array stays empty, and it fails loudly the moment someone wires an integration without first adding its OM descriptor.
+- `getAgentResourceDescriptor` -- optional. Omit it and your `agents` array passes through unresolved.
+
+These resolvers are why a workflow you write must have a matching OM resource descriptor before it deploys -- `projectDeploymentSpec` is the point where that requirement is enforced, not a validation step bolted on afterward.
+
+## Feature-Group Exports
+
+Each feature folder under `operations/src/` owns an `exports.ts` (or, for a single-workflow group, folds the same two arrays into its `index.ts`) that lists its own workflows and agents:
+
+{/* doc-snippet:skip: real-file excerpt with a relative import, not a standalone compilable file */}
+
+```typescript
+// email-notification/exports.ts
+import { emailNotification } from './index.js'
+import type { WorkflowDefinition } from '@elevasis/sdk'
+
+export const workflows: WorkflowDefinition[] = [emailNotification]
+export const agents: never[] = []
+```
+
+`index.ts` at the project root spreads every group's arrays together: `workflows: [...example.workflows, ...emailNotification.workflows]`. Adding a new workflow to an existing feature means adding it to that feature's array; adding a new feature means adding a new `import * as myFeature from './my-feature/exports.js'` line and spreading its arrays alongside the others.
+
+## `defineWorkflowConfig`: Deriving `config` From One OM Descriptor
+
+`defineWorkflowConfig(resourceId, descriptors, actionRegistry?)` is a second, smaller helper for the common case where a workflow's `config.name`, `config.description`, `config.actions`, and `config.primaryAction` should all come from the same OM resource descriptor instead of being retyped by hand. `echo.ts` uses it:
+
+{/* doc-snippet:skip: real-file excerpt with project-local path aliases, not a standalone compilable file */}
+
+```typescript
+import { defineWorkflowConfig, type WorkflowDefinition } from '@elevasis/sdk'
+import { templateResourceDescriptors } from '@core/config/organization-model'
+import { echoInputSchema, echoOutputSchema } from '@core/types'
+
+export const echo: WorkflowDefinition = {
+  config: {
+    ...defineWorkflowConfig('echo', templateResourceDescriptors),
+    type: 'workflow',
+    version: '1.0.0',
+    status: 'dev'
+  },
+  contract: { inputSchema: echoInputSchema, outputSchema: echoOutputSchema },
+  steps: {
+    /* ... */
+  },
+  entryPoint: 'echo'
+}
+```
+
+It throws if the descriptor is missing, if it is not `kind: 'workflow'`, or if the descriptor's `ontology.primaryAction` is unset -- `defineWorkflowConfig` requires a resource that has already been given an ontology binding. A workflow whose OM descriptor has no `ontology.primaryAction` yet cannot use this helper. `email-notification.ts`, in the same shipped template, is that case: it reads `templateResourceDescriptors['email-notification']` directly and builds `config.resourceId` / `config.name` / `config.type` / `config.description` off the descriptor's own fields by hand, because that resource's ontology binding was not authored. Both are valid, verified-shipping patterns -- reach for `defineWorkflowConfig` once the descriptor has a `primaryAction`, and fall back to manual descriptor field access until it does.
+
+Note that `config.resource` and the final `config.resourceId` / `config.type` are still overwritten by `projectDeploymentSpec` at assembly time regardless of which of the two you use here -- `defineWorkflowConfig` and the manual fallback both only save you from retyping `name` and `description`, not from the resolver-injection step above.
+
+## `triggers`, `integrations`, `humanCheckpoints`: `metadata.ts`
+
+These three arrays are deployment mechanics, not OM identity, and live in `operations/src/metadata.ts`. All three start empty in a freshly scaffolded project -- add entries as you adopt webhook triggers, third-party credentials, or HITL checkpoints. See [Human-in-the-Loop Workflows](human-in-the-loop.mdx) for the `humanCheckpoints` shape in context.
+
+## Adding a Workflow Under This Pattern
+
+1. Write the workflow file (`config`, `contract`, `steps`, `entryPoint`), using `defineWorkflowConfig` if the resource already has an `ontology.primaryAction`, otherwise deriving `config` fields from the descriptor by hand.
+2. Make sure the resource exists in your OM -- for a tenant project this goes through the `/om` ceremony, not a direct edit to `core/config/organization-model.ts`.
+3. Export it from its feature group's `workflows` array (`exports.ts` or `index.ts`).
+4. Confirm the top-level `operations/src/index.ts` spreads that group into the `workflows` list passed to `projectDeploymentSpec` -- existing groups already do; a brand-new group needs the import and spread added once.
+5. Run `pnpm -C operations run check` (not `deploy` without `run` -- `pnpm -C operations deploy` without the `run` keyword is parsed as pnpm's own builtin `deploy` command, not your project's `deploy` script).
+6. Deploy with `pnpm -C operations run deploy`.
+
+## Documentation
+
+- [Resources](resources/index.mdx) -- the `WorkflowDefinition` / `AgentDefinition` shape these helpers assemble
+- [Human-in-the-Loop Workflows](human-in-the-loop.mdx) -- the `humanCheckpoints` entry in `metadata.ts`, in context
+- [Deployment](deployment/index.mdx) -- what happens after `deploy` runs

package/reference/sdk/resources/index.mdx

@@ -23,7 +23,7 @@ A complete workflow definition has four required properties:
 ```typescript
 import { z } from 'zod';
 import type { WorkflowDefinition } from '@elevasis/sdk';
-import { resourceDescriptors } from '@core/config/organization-model';
+import { templateResourceDescriptors } from '@core/config/organization-model';
 
 const echoInput = z.object({
   message: z.string(),
@@ -37,10 +37,10 @@ type EchoInput = z.infer<typeof echoInput>;
 
 const echoWorkflow: WorkflowDefinition = {
   config: {
-    resource: resourceDescriptors.echo,
-    resourceId: resourceDescriptors.echo.id,
+    resource: templateResourceDescriptors.echo,
+    resourceId: templateResourceDescriptors.echo.id,
     name: 'Echo',
-    type: resourceDescriptors.echo.kind,
+    type: templateResourceDescriptors.echo.kind,
     description: 'Returns the input message unchanged',
     version: '1.0.0',
     status: 'dev',
@@ -88,6 +88,8 @@ The `contract` block defines the Zod schemas for input and output. The platform
 
 Always use `z.object()` for both schemas. Use `z.infer` to derive TypeScript types -- this keeps types and runtime validation in sync automatically.
 
+{/* doc-snippet:skip: illustrative excerpt -- shows the contract shape in isolation, omits the `import { z } from 'zod'` shown in the Minimal Example above */}
+
 ```typescript
 const contract = {
   inputSchema: z.object({
@@ -105,6 +107,8 @@ const contract = {
 
 The `steps` record maps step IDs to step objects. Each step has metadata (`id`, `name`, `description`), a `handler` function, Zod schemas for its own input and output, and a `next` property that controls routing.
 
+{/* doc-snippet:skip: illustrative excerpt -- MyInput/myInputSchema/ValidatedData are placeholder names for types you define yourself, not a standalone compilable file */}
+
 ```typescript
 const steps = {
   validate: {
@@ -136,6 +140,8 @@ const steps = {
 
 `entryPoint` is the name of the first step. For single-step workflows it is always the only step name. For multi-step workflows it is the name of the first step in the chain.
 
+{/* doc-snippet:skip: illustrative excerpt with a `// ...` elision, not a standalone compilable file */}
+
 ```typescript
 const workflow: WorkflowDefinition = {
   // ...
@@ -153,6 +159,8 @@ For workflows with more than one step, import `StepType` from `@elevasis/sdk` to
 
 Use `StepType.LINEAR` to connect steps in a fixed sequence. Each step declares a `next` property pointing to the next step name.
 
+{/* doc-snippet:skip: illustrative excerpt -- fetchSomething/transform/pipelineInput/pipelineOutput are placeholder names for your own helpers and schemas, not a standalone compilable file */}
+
 ```typescript
 import { z } from 'zod';
 import type { WorkflowDefinition, WorkflowStep } from '@elevasis/sdk';
@@ -201,6 +209,8 @@ const pipeline: WorkflowDefinition = {
 
 Use `StepType.CONDITIONAL` to route to different steps based on output values. Each route has a `condition` function and a `target` step name. The first condition that returns `true` wins. A `default` fallback step is required.
 
+{/* doc-snippet:skip: illustrative excerpt -- `evaluate` is a placeholder name for your own scoring logic, not a standalone compilable file */}
+
 ```typescript
 import { z } from 'zod';
 import type { WorkflowStep } from '@elevasis/sdk';
@@ -246,7 +256,7 @@ import type { StepHandler } from '@elevasis/sdk';
 const myStep: StepHandler = async (input, context) => {
   const { executionId, organizationId, resourceId, logger, store } = context;
 
-  logger.info('Starting step', { executionId });
+  logger.info(`Starting step for execution ${executionId}`);
 
   // store is a simple key-value store scoped to this execution
   await store.set('progress', '50%');
@@ -328,19 +338,25 @@ const myAgent: AgentDefinition = {
 
 `contract.inputSchema` is required, same as a workflow. `contract.outputSchema` is what a **non-session** (single-shot) agent like the example above returns — there is no conversational reply to read a structured answer from otherwise. A `sessionCapable: true` agent typically omits `outputSchema` and speaks through its conversational `message` instead.
 
+The framework normalizes literal escape sequences out of that conversational `message`, out of `reasoning`, and out of session-memory values before any of them are persisted, streamed, or replayed. A model sometimes writes the two characters backslash-n where a line break belongs; the result is valid JSON that satisfies the response schema, so nothing upstream can catch it, and the operator ends up reading those characters mid-sentence. Nothing is required of you — no agent definition field changes — but two consequences are worth knowing. An agent that legitimately wants to show an escape sequence in prose (explaining a regex, say) will have it converted, because the normalizer is not markdown-aware. And a memory value that is itself JSON is skipped entirely, so a stored JSON blob keeps its internal escaping intact.
+
 ---
 
 ## DeploymentSpec
 
 All executable resources must be assembled through a `DeploymentSpec` default export from `operations/src/index.ts`. This is the entry point the platform reads when you deploy. Include the Organization Model payload so the validator can compare code-backed resources against OM descriptors.
 
+Use the canonical (resolved) organization model here, not the `organizationModel` convenience export used for navigation/UI code -- that export reshapes the `navigation` field into a template-facing surface list and is not assignable to `DeploymentSpec['organizationModel']`.
+
+{/* doc-snippet:skip: illustrative excerpt -- echoWorkflow and pipeline continue from the Minimal Example and Linear Steps examples earlier on this page, not a standalone compilable file */}
+
 ```typescript
 import type { DeploymentSpec } from '@elevasis/sdk';
-import { organizationModel } from '@core/config/organization-model';
+import { canonicalOrganizationModel } from '@core/config/organization-model';
 
 const org: DeploymentSpec = {
   version: '0.1.0',
-  organizationModel,
+  organizationModel: canonicalOrganizationModel,
   workflows: [echoWorkflow, pipeline],
   agents: [
     // myAgent,

package/reference/sdk/resources/patterns.mdx

@@ -13,6 +13,10 @@ The simplest pattern: a chain of steps where each step feeds its output into the
 
 Each `WorkflowStep` requires `id`, `name`, `description`, `handler`, `inputSchema`, `outputSchema`, and `next`. There is no `type` field on a step -- `StepType` (`LINEAR` / `CONDITIONAL`) is a label for `next.type` only, not a step property.
 
+A step's `handler` is typed `(input: unknown, context) => Promise<unknown>` -- narrowing the parameter itself (`async (input: Input) => ...`) breaks assignability under `strictFunctionTypes`. Cast inside the handler body instead, as shown below.
+
+{/* doc-snippet:skip: illustrative excerpt -- getOrder/createShipment are placeholder names for your own domain logic, not a standalone compilable file */}
+
 ```typescript
 import { z } from 'zod';
 import type { WorkflowDefinition, WorkflowStep } from '@elevasis/sdk';
@@ -28,9 +32,10 @@ const validateStep: WorkflowStep = {
   description: 'Checks the order exists before shipping',
   inputSchema: z.object({ orderId: z.string() }),
   outputSchema: z.object({ order: z.unknown() }),
-  handler: async (input: Input) => {
-    const order = await getOrder(input.orderId);
-    if (!order) throw new Error(`Order ${input.orderId} not found`);
+  handler: async (input) => {
+    const { orderId } = input as Input;
+    const order = await getOrder(orderId);
+    if (!order) throw new Error(`Order ${orderId} not found`);
     return { order };
   },
   next: { type: 'linear', target: 'ship' },
@@ -43,7 +48,8 @@ const shipStep: WorkflowStep = {
   inputSchema: z.object({ order: z.unknown() }),
   outputSchema: z.object({ shipped: z.boolean(), trackingNumber: z.string() }),
   handler: async (input) => {
-    const tracking = await createShipment(input.order);
+    const { order } = input as { order: unknown };
+    const tracking = await createShipment(order);
     return { shipped: true, trackingNumber: tracking.number };
   },
   next: null, // terminal -- no further steps
@@ -72,6 +78,8 @@ const fulfillOrder: WorkflowDefinition = {
 
 Use a `next.type` of `'conditional'` when the next step depends on the output of the current step. The step itself still has no `type` field -- the routing decision lives entirely in `next`.
 
+{/* doc-snippet:skip: illustrative excerpt, not a standalone compilable file */}
+
 ```typescript
 import { z } from 'zod';
 import type { WorkflowStep } from '@elevasis/sdk';
@@ -128,18 +136,20 @@ const sendEmailStep: WorkflowStep = {
   inputSchema: z.object({ recipientEmail: z.string(), subject: z.string(), body: z.string() }),
   outputSchema: z.object({ sent: z.boolean(), messageId: z.string() }),
   handler: async (input, context) => {
-    const result = await platform.call({
+    const { recipientEmail, subject, body } = input as {
+      recipientEmail: string;
+      subject: string;
+      body: string;
+    };
+
+    const result = (await platform.call({
       tool: 'email',
       method: 'send',
-      params: {
-        to: input.recipientEmail,
-        subject: input.subject,
-        body: input.body,
-      },
+      params: { to: recipientEmail, subject, body },
       credential: 'sendgrid',          // name of the stored credential
-    });
+    })) as { messageId: string };
 
-    context.logger.info('Email sent', { messageId: result.messageId });
+    context.logger.info(`Email sent: ${result.messageId}`);
     return { sent: true, messageId: result.messageId };
   },
   next: null,
@@ -149,7 +159,7 @@ const sendEmailStep: WorkflowStep = {
 **Key points:**
 
 - `platform.call()` is async and times out after 30 minutes (a worker-side safety net; real enforcement is server-side)
-- `credential` is the name of a platform environment variable set via `elevasis-sdk env set` when the tool needs one
+- `credential` is the name of a platform environment variable created via `elevasis-sdk creds create` when the tool needs one
 - On failure, `platform.call()` throws `PlatformToolError` (not `ToolingError`)
 - Always log success so executions are easy to debug in the dashboard
 
@@ -164,20 +174,20 @@ Use `PlatformToolError` (from `@elevasis/sdk/worker`) to handle tool-specific fa
 ```typescript
 import { platform, PlatformToolError } from '@elevasis/sdk/worker';
 
-const step = async (input) => {
+const step = async (input: { followUpAt?: string }) => {
   try {
-    const deals = await platform.call({
+    const deals = (await platform.call({
       tool: 'crm',
       method: 'listDeals',
       params: { stage: 'proposal', limit: 10 },
-    });
+    })) as Array<{ id: string }>;
 
     const deal = deals[0]
-      ? await platform.call({
+      ? ((await platform.call({
           tool: 'crm',
           method: 'getDeal',
           params: { dealId: deals[0].id },
-        })
+        })) as { id: string })
       : null;
 
     if (deal) {
@@ -234,6 +244,8 @@ const step = async (input) => {
 
 Use `ExecutionError` when your step detects a condition that should mark the entire execution as failed:
 
+{/* doc-snippet:skip: illustrative excerpt, not a standalone compilable file */}
+
 ```typescript
 import { ExecutionError } from '@elevasis/sdk';
 
@@ -254,10 +266,12 @@ const validateStep = async (input) => {
 
 `ToolingError` is thrown by lower-level platform operations (not `platform.call()` directly). You may encounter it in advanced scenarios:
 
+{/* doc-snippet:skip: illustrative excerpt -- `doSomething` is a placeholder name for your own logic, not a standalone compilable file */}
+
 ```typescript
 import { ToolingError } from '@elevasis/sdk';
 
-const step = async (input) => {
+const step = async (input: unknown) => {
   try {
     return await doSomething(input);
   } catch (err) {
@@ -274,17 +288,20 @@ const step = async (input) => {
 
 ## Logging in Steps
 
-The `context.logger` writes structured logs attached to the execution. Use it instead of `console.log` so logs appear in the dashboard alongside the execution record.
+The `context.logger` writes structured logs attached to the execution. Use it instead of `console.log` so logs appear in the dashboard alongside the execution record. `logger.info()`'s optional second parameter is an internal engine-only context type, not a place for arbitrary metadata -- interpolate values into the message string instead.
+
+{/* doc-snippet:skip: illustrative excerpt -- `doWork` is a placeholder name for your own logic, not a standalone compilable file */}
 
 ```typescript
 import type { StepHandler } from '@elevasis/sdk';
 
 const processStep: StepHandler = async (input, context) => {
-  context.logger.info('Starting process', { userId: input.userId });
+  const { userId } = input as { userId: string };
+  context.logger.info(`Starting process for user ${userId}`);
 
-  const result = await doWork(input);
+  const result = (await doWork(input)) as { id: string };
 
-  context.logger.info('Process complete', { resultId: result.id });
+  context.logger.info(`Process complete: ${result.id}`);
   return result;
 };
 ```
@@ -297,9 +314,14 @@ Avoid logging sensitive values (API keys, passwords, PII) since logs are stored
 
 `context.store` is a simple key-value store scoped to the current execution. Use it to pass data between steps without coupling step interfaces, or to checkpoint long-running work.
 
+{/* doc-snippet:skip: illustrative excerpt -- fetchExpensiveData/transform are placeholder names for your own logic, not a standalone compilable file */}
+
 ```typescript
+import type { StepHandler } from '@elevasis/sdk';
+
 const firstStep: StepHandler = async (input, context) => {
-  const data = await fetchExpensiveData(input.id);
+  const { id } = input as { id: string };
+  const data = await fetchExpensiveData(id);
 
   // Save for use by later steps
   await context.store.set('fetchedData', JSON.stringify(data));
@@ -325,6 +347,8 @@ Store values are strings. Serialize objects with `JSON.stringify` and parse with
 
 While building a resource, set `config.status` to `'dev'`:
 
+{/* doc-snippet:skip: illustrative excerpt with a `// ...` elision, not a standalone compilable file */}
+
 ```typescript
 const myWorkflow: WorkflowDefinition = {
   config: {
@@ -345,6 +369,8 @@ Dev resources:
 
 When you are ready to go live, change to `'prod'` and redeploy:
 
+{/* doc-snippet:skip: illustrative excerpt, not a standalone compilable file */}
+
 ```typescript
 config: {
   name: 'my-workflow',
@@ -375,6 +401,8 @@ Individual resources that set their own `config.status` override this default.
 
 As your project grows, organize resources by business domain. Each domain gets its own directory with an `index.ts` barrel that exports `workflows` and `agents` arrays:
 
+{/* doc-snippet:skip: illustrative excerpt with `...` elisions, not a standalone compilable file */}
+
 ```typescript
 // src/orders/fulfill-order.ts
 export const fulfillOrder: WorkflowDefinition = { ... };
@@ -423,6 +451,8 @@ The platform's HITL mechanism works in two parts: your workflow code creates an
 
 Call `approval.create()` from any workflow step to pause execution and emit a task to the Command Queue:
 
+{/* doc-snippet:skip: illustrative excerpt -- dealId/proposalUrl are shorthand for values from the enclosing step handler's input, not a standalone compilable file */}
+
 ```typescript
 import { approval } from '@elevasis/sdk/worker'
 

package/reference/sdk/resources/types.mdx

@@ -45,6 +45,8 @@ Zod is a peer dependency.
 
 Resource metadata uses graph links:
 
+{/* doc-snippet:skip: illustrative excerpt, not a standalone compilable file */}
+
 ```ts
 config: {
   resourceId: 'lead-import',
@@ -77,6 +79,8 @@ config: {
 ## ElevasConfig
 
 ```ts
+import type { ResourceStatus } from '@elevasis/sdk'
+
 export interface ElevasConfig {
   defaultStatus?: ResourceStatus
   dev?: { port?: number }
@@ -90,14 +94,13 @@ export interface ElevasConfig {
 
 ## StepHandler Context
 
+`logger`'s optional second parameter is an internal engine-only context type, not a place for arbitrary metadata -- interpolate values into the message string instead.
+
 ```ts
 import type { StepHandler, ExecutionContext } from '@elevasis/sdk'
 
 const handler: StepHandler = async (input, context: ExecutionContext) => {
-  context.logger.info('Processing', {
-    executionId: context.executionId,
-    resourceId: context.resourceId
-  })
+  context.logger.info(`Processing execution ${context.executionId} for resource ${context.resourceId}`)
 
   await context.store.set('checkpoint', JSON.stringify({ step: 'started' }))
   return { done: true }

package/reference/sdk/templates/data-enrichment.mdx

@@ -23,10 +23,12 @@ Fetches records from a Supabase table that need enrichment, sends each record to
 
 ## Input Schema
 
+{/* doc-snippet:skip: illustrative excerpt -- shows the schema shape in isolation, omits the `import { z } from 'zod'` shown in Workflow Code Pattern below */}
+
 ```typescript
 z.object({
   table: z.string(),              // Supabase table to enrich
-  filter: z.record(z.string()).optional(), // Filter rows to enrich (PostgREST format)
+  filter: z.record(z.string(), z.string()).optional(), // Filter rows to enrich (PostgREST format)
   sourceField: z.string(),        // Field to send to the LLM as input
   targetField: z.string(),        // Field to write enriched output to
   prompt: z.string(),             // LLM prompt template (use {value} as placeholder)
@@ -36,6 +38,8 @@ z.object({
 
 ## Output Schema
 
+{/* doc-snippet:skip: illustrative excerpt -- shows the schema shape in isolation, omits the `import { z } from 'zod'` shown in Workflow Code Pattern below */}
+
 ```typescript
 z.object({
   processed: z.number(),          // Rows successfully enriched
@@ -55,7 +59,7 @@ import { z } from 'zod'
 
 const inputSchema = z.object({
   table: z.string(),
-  filter: z.record(z.string()).optional(),
+  filter: z.record(z.string(), z.string()).optional(),
   sourceField: z.string(),
   targetField: z.string(),
   prompt: z.string(),
@@ -130,7 +134,7 @@ export const dataEnrichment: WorkflowDefinition = {
               },
             })
 
-            context.logger.info('Enriched row', { id: row.id })
+            context.logger.info(`Enriched row ${String(row.id)}`)
             processed++
           } catch (err) {
             const msg = err instanceof Error ? err.message : String(err)