@elevasis/sdk 1.44.2 → 1.45.0

package/reference/sdk/framework/project-structure.mdx

@@ -1,282 +1,227 @@
 ---
 title: Project Structure
-description: Each file in an Elevasis SDK project and its purpose in the development workflow
+description: Each directory and file in an Elevasis SDK project and its purpose, verified against the current external/_template scaffold
 loadWhen: "Understanding scaffolded files or project layout"
 ---
 
-Your Elevasis SDK project includes a complete workspace structure. This page explains what each file does and when you will interact with it.
+Your Elevasis SDK project includes a complete workspace structure. This page explains what each directory and file does and when you will interact with it.
 
-The current full-stack scaffold uses a workspace layout with `ui/`, `operations/`, `core/`, and a root `docs/` directory. When older examples refer to `src/shared/`, read that as the current `core/` package for cross-runtime types, schemas, and organization-model configuration.
+The scaffold is a workspace with `ui/`, `operations/`, and `core/` packages plus a `.claude/` agent-infrastructure directory. There is no top-level `docs/` directory -- documentation content is not part of the current deploy path.
 
 ---
 
-## Source Files
+## Top-Level Layout
 
-### `operations/src/index.ts`
-
-The registry entry point for your workspace. This file imports OM resource governance from `core/config/organization-model.ts`, aggregates executable resources from domain barrel files, and re-exports them as a `DeploymentSpec` default export. It does not contain workflow logic itself -- its sole job is assembly:
-
-```ts
-import type { DeploymentSpec } from '@elevasis/sdk'
-import { organizationModel } from '@core/config/organization-model'
-import * as example from './example/index.js'
-import * as emailNotification from './email-notification/exports.js'
-
-const org: DeploymentSpec = {
-  version: '0.1.0',
-  organizationModel,
-  workflows: [...example.workflows, ...emailNotification.workflows],
-  agents: [...example.agents, ...emailNotification.agents]
-}
-export default org
 ```
-
-Each domain directory exports `workflows` and `agents` arrays via an `index.ts` barrel. When you add a new domain, import it here and spread its arrays.
-
-### `operations/src/email-notification/index.ts`
-
-A multi-step workflow demonstrating real platform API usage. Sends an email notification using the `notifications` adapter and chains steps with `StepType.LINEAR`. Shows the pattern for workflows that use platform tool adapters and pass data between steps.
-
-### `operations/src/example/echo.ts`
-
-The starter workflow, scaffolded to demonstrate the per-file pattern: one workflow per file with its own Zod input/output schemas, config object, contract, and step handler. Replace this domain with your own when you're ready.
-
-### `core/`
-
-Cross-runtime types, schemas, constants, and organization-model configuration shared between the UI and operations packages. Put contracts here when both runtimes need the same validation or labels without depending on app-specific code. Resource descriptors live in `core/config/organization-model.ts`.
-
-### `operations/elevasis.config.ts`
-
-Project-level configuration. The scaffolded file includes commented-out options (`defaultStatus`, `dev.port`):
-
-```ts
-import type { ElevasConfig } from '@elevasis/sdk'
-
-export default {
-  // defaultStatus: 'dev',     // Default status for new resources ('dev' | 'prod')
-  // dev: { port: 5170 },      // Local API port (internal development only)
-} satisfies ElevasConfig
+├── .claude/              # Agent infrastructure -- skills, rules, hooks (see Agent System)
+├── core/                 # Cross-runtime contracts, schemas, organization model
+├── operations/           # Platform workflows, agents, and deploy config
+├── ui/                   # React frontend application
+├── tmp/                  # Transient agent-generated input files (kept via .gitkeep)
+├── .elevasis             # Project marker: slug, templateVersion, appMode, workosOrgId
+├── .env / .env.example   # ELEVASIS_PLATFORM_KEY and other root-level environment values
+├── .gitattributes        # Line-ending normalization
+├── .gitignore            # Excludes node_modules, dist, .env, .tanstack, and more
+├── .npmrc                # auto-install-peers = true (Zod is a peer dependency)
+├── CLAUDE.md              # Project-owned identity and preferences (never overwritten by sync)
+├── CONNECTIONS.md         # Tenant-owned production wiring values (never overwritten)
+├── OPERATIONS.md          # Tenant-owned operational quirks (never overwritten, outranks generic guidance)
+├── package.json           # Root workspace manifest
+├── pnpm-lock.yaml         # Project's own lockfile (this is a standalone repo, not part of the monorepo)
+├── pnpm-workspace.yaml    # Workspace definition for core/operations/ui
+└── tsconfig.json          # Root TypeScript configuration
 ```
 
----
-
-## Documentation
-
-### `docs/index.md`
-
-The entry point for your workspace's documentation. Documentation files in `docs/` are deployed alongside your code during `elevasis-sdk deploy` and rendered in the Elevasis platform UI.
+This project is **not** part of the Elevasis monorepo pnpm workspace. It has its own `.git/`, its own `pnpm-lock.yaml`, its own `node_modules/`. The monorepo boundary hook does not apply here.
 
-Use MDX frontmatter to set page metadata:
-
-```yaml
----
-title: Overview
-description: Documentation for this project
-order: 0
 ---
-```
-
-Add more pages by creating additional `.mdx` files in `docs/`. Nested directories create sections: `docs/guides/setup.mdx` becomes a `guides/setup` page under your deployment's documentation.
 
-### `docs/project-map.mdx`
+## `core/`
 
-Auto-generated by `elevasis-sdk deploy` on every deploy and by `/meta fix` step 8. Contains a full project snapshot: organization, SDK version, template version, last deploy date, source domains, resource tables (workflows and agents), documentation index, SDK reference summary, commands/rules/skills, memory system listing, and configuration state. The agent reads this file at session start for project orientation.
+Cross-runtime types, schemas, constants, and organization-model configuration shared between `ui/` and `operations/`. Runtime-agnostic only -- no React, no Node APIs, no SDK worker imports.
 
-This file is fully auto-generated -- do not edit manually. Changes are overwritten on the next deploy.
+```
+core/
+├── config/
+│   ├── organization-model.ts                 # Canonical model + resource descriptor resolvers
+│   ├── organization-model.test.ts
+│   ├── organization-model.contract.test.ts
+│   ├── extensions/                            # Project-specific model extensions
+│   ├── knowledge/                              # Knowledge graph nodes
+│   └── README.md
+├── test-utils/
+│   └── core-contract-factories.ts
+├── types/
+│   ├── index.ts                                # Zod input/output schemas for workflows
+│   ├── index.test.ts
+│   ├── entities.ts                             # BaseProject/BaseDeal-style entity extension examples
+│   └── entities.test.ts / entities.contract.test.ts
+├── package.json
+├── tsconfig.json
+└── vitest.config.ts
+```
 
-### `docs/priorities.mdx`
+### `core/config/organization-model.ts`
 
-Created by the agent during your first goal discussion. Records current goals, priorities, and next steps for the workspace. Updated as goals change across sessions.
+Defines and resolves the canonical organization model (`canonicalOrganizationModel`) plus the resource-descriptor getters (`getTemplateWorkflowResourceDescriptor`, `getTemplateAgentResourceDescriptor`) that `operations/src/index.ts` imports. Direct edits are discouraged -- the file's own resolver (`resolveOrganizationModel()`) runs Zod cross-reference validation that a syntactically valid edit can still fail. All edits go through `/om`.
 
-This file is NOT scaffolded by default. The agent creates it the first time you discuss project goals or priorities in a session.
+### `core/types/index.ts`
 
-### `docs/in-progress/`
+Where workflow input/output Zod schemas are defined (for example `echoInputSchema`), so both `ui/` and `operations/` can import the same schema without a runtime dependency cycle.
 
-Work-in-progress task documents managed by `/work`. Each file represents an active work item with objective, plan, progress markers, and resume context. This is separate from the Projects data model exposed through `elevasis-sdk project:*`. When all steps are complete, the agent suggests finalizing the task, which moves finished items to their permanent location in `docs/`.
+### `core/types/entities.ts`
 
-This directory is NOT deployed -- it is filtered out during the doc scan in `elevasis-sdk deploy`.
+Demonstrates the entity-extension pattern: extend a base entity (`BaseProjectSchema`, `BaseDealSchema`, and similar, imported from `@elevasis/core/entities`) with project-specific metadata, or re-export a base entity unchanged when no extension is needed.
 
 ---
 
-## Progressive Disclosure Directories
-
-The following directories are included in the scaffold:
-
-| Directory                            | Created by      | When                                                               |
-| ------------------------------------ | --------------- | ------------------------------------------------------------------ |
-| `operations/src/example/`            | Scaffold        | Always -- echo starter workflow lives here (replace with your own) |
-| `operations/src/email-notification/` | Scaffold        | Always -- multi-step notification workflow example                 |
-| `core/`                              | Scaffold        | Always -- cross-runtime contracts, schemas, and organization model |
-| `ui/`                                | Scaffold        | Always -- React frontend application                               |
-| `docs/`                              | Scaffold        | Always                                                             |
-| `docs/in-progress/`                  | Agent           | When you create a task doc for in-progress work                    |
-| `docs/resources.md`                  | `/deploy` skill | Auto-generated on every deploy                                     |
-| `data/`                              | Agent           | When you connect a database                                        |
-| `scripts/`                           | Agent           | When you need local scripts not deployed to the platform           |
-| `operations/src/lib/`                | Agent           | When shared code exists between two or more workflows              |
-
-This structure keeps the initial workspace minimal and adds directories only when they earn their place.
-
-### `operations/src/lib/`
-
-Shared code directory for utilities used by multiple workflows within the operations package. In the current workspace scaffold, prefer the top-level `core/` package for cross-runtime contracts. Included in the esbuild bundle alongside workflow code.
-
-### `data/`
+## `operations/`
 
-Created by the agent when you connect a database. Contains `schema.ts` which documents your database schema as TypeScript types. The agent reads this file to understand your data model when writing workflow steps that call the Supabase tool. Not deployed -- it is local documentation for the agent.
+Platform workflows, agents, and deploy configuration -- the code that runs on the Elevasis platform.
 
-### `scripts/`
-
-Local utility scripts for tasks that do not run on the platform: database seeds, data migrations, one-off transformations, local testing helpers. Created on demand when you need a local script. Not deployed, not bundled.
-
----
-
-## `elevasis-sdk deploy` Scope
+```
+operations/
+├── src/
+│   ├── index.ts                       # DeploymentSpec entry point (registry assembly)
+│   ├── metadata.ts                    # Trigger/integration/human-checkpoint metadata (starts empty)
+│   ├── resource-registry.test.ts
+│   ├── README.md
+│   ├── example/
+│   │   ├── echo.ts                    # Starter workflow
+│   │   ├── example-agent.ts           # Starter agent
+│   │   └── index.ts                   # Domain barrel (exports workflows + agents)
+│   ├── email-notification/
+│   │   ├── exports.ts                 # Domain barrel
+│   │   ├── index.ts                   # Multi-step workflow using the notifications adapter
+│   │   └── adapter-contract.test.ts
+│   └── shared/                        # Empty by default (.gitkeep) -- code shared across domains
+├── elevasis.config.ts                 # Project-level SDK config
+├── package.json
+├── tsconfig.json
+└── vitest.config.ts
+```
 
-`elevasis-sdk deploy` touches only two directories:
+### `operations/src/index.ts`
 
-| Directory           | Action                                                                               | Deployed? |
-| ------------------- | ------------------------------------------------------------------------------------ | --------- |
-| `operations/src/`   | Bundle into `dist/bundle.js` via esbuild (includes `operations/src/lib/` if present) | Yes       |
-| `docs/`             | Scan `.md` and `.mdx` files, upload as documentation                                 | Yes       |
-| `docs/in-progress/` | Ignored -- work-in-progress, not deployed                                            | No        |
-| `data/`             | Ignored -- local documentation for the agent                                         | No        |
-| `scripts/`          | Ignored -- local scripts, not deployed                                               | No        |
-| `.claude/`          | Ignored -- local development only                                                    | No        |
-| `ui/`               | Ignored -- frontend application, deployed separately                                 | No        |
+The registry entry point. It imports the organization model and resource-descriptor resolvers from `core/config/organization-model.ts`, aggregates each domain's `workflows` and `agents` arrays, and calls the SDK's `projectDeploymentSpec()` to assemble the deployable `DeploymentSpec`, binding each resource to its OM Resource descriptor. Add a new domain by importing its barrel here and spreading its `workflows` / `agents` arrays.
 
----
+### `operations/src/metadata.ts`
 
-## Configuration Files
+Convention seed for deployment mechanics that are not resource identity: trigger definitions (webhook, event, schedule), integration definitions (third-party credential handles), and human-checkpoint queue metadata. All three arrays (`triggers`, `integrations`, `humanCheckpoints`) start empty and are wired into `index.ts`.
 
-### `.env`
+### `operations/src/example/echo.ts`
 
-Contains your `ELEVASIS_PLATFORM_KEY`. This file is gitignored. Never commit it.
+The starter workflow: one workflow per file with its own `config`, Zod `contract`, `steps` map, and `entryPoint`. Replace this domain with your own when ready. `operations/src/example/example-agent.ts` is the equivalent starter for an agent resource.
 
-### `.npmrc`
+### `operations/src/email-notification/index.ts`
 
-Sets `auto-install-peers = true`. The SDK uses Zod as a peer dependency, so this ensures Zod installs automatically.
+A multi-step workflow demonstrating a real platform tool adapter (`notifications`), chaining steps and passing data between them.
 
-### `tsconfig.json`
+### `operations/elevasis.config.ts`
 
-App-focused TypeScript configuration. It does not include `declaration` or `declarationMap` settings because your project is a deployable application, not a library.
+Project-level SDK configuration. The scaffolded file has two commented-out options:
 
-### `.gitignore`
+```ts
+import type { ElevasConfig } from '@elevasis/sdk'
 
-Pre-configured to exclude:
+export default {
+  // defaultStatus: 'dev',     // Default status for new resources ('dev' | 'prod')
+  // dev: { port: 5170 },      // Local API port (internal development only)
+} satisfies ElevasConfig
+```
 
-- `node_modules/` -- installed packages
-- `.env` -- API key
-- `dist/` -- generated by deploy, never commit
-- `__elevasis_worker.ts` -- temporary file generated during deployment
-- `.claude/settings.local.json` -- local Claude Code overrides
-- `.claude/memory/` -- your personal cross-session project memory (profile, errors, decisions)
+`ElevasConfig` only accepts `defaultStatus` and `dev.port` -- there is no `templateVersion` field here. The template version marker lives in the project-root `.elevasis` file instead.
 
 ---
 
-## Claude Code Integration
-
-The `.claude/` directory and `CLAUDE.md` give Claude Code full awareness of the SDK, CLI, and your project structure from the first session.
+## `ui/`
 
-### `CLAUDE.md`
+The React frontend application.
 
-The most important file for AI-assisted development. It provides Claude Code with:
-
-- **Project orientation** -- what an Elevasis SDK project is and how it works
-- **Project structure** -- which files contain resources, documentation, and configuration
-- **SDK patterns** -- working code examples for descriptor-backed resource definitions, Zod schemas, and the `DeploymentSpec` export
-- **CLI reference** -- all commands with flags (`check`, `deploy`, `exec`, `resources`, `executions`, `execution`, `deployments`, `env list/set/remove`)
-- **Development rules** -- conventions the agent should enforce (source in `src/`, docs in `docs/`, use `@elevasis/sdk` types only)
-
-Do not remove or heavily edit `CLAUDE.md`. It is the primary context source that makes the slash commands work well.
+```
+ui/
+├── src/
+│   ├── assets/
+│   ├── config/
+│   ├── features/
+│   ├── lib/
+│   ├── routes/                 # TanStack Router file-based routes
+│   ├── test-utils/
+│   ├── main.tsx
+│   └── routeTree.gen.ts        # Generated by TanStack Router -- do not edit
+├── public/
+├── index.html
+├── package.json
+├── tsconfig.json
+├── vercel.json
+├── vite.config.ts
+└── vitest.config.ts
+```
 
-### `.claude/settings.json`
+Path aliases: `@/*` maps to `ui/src/*`, `@core/*` maps to `core/*`. Frontend and platform code are separate runtimes -- they share only types via `core/`, and never import each other's `src/` directly.
 
-Configures Claude Code for the workspace: registers a PostToolUse formatting/type-check hook (runs after Write, Edit, and MultiEdit) and a PostToolUseFailure error recovery hook (runs after Bash failures).
+---
 
-### `.claude/memory/`
+## Claude Code Integration (`.claude/`)
 
-Created when you run `/meta init` in Claude Code. The agent asks six onboarding questions about your organization, project goals, integrations, and experience level. Answers are stored here as markdown files and used to personalize subsequent sessions.
+The `.claude/` directory and `CLAUDE.md` give Claude Code full awareness of the SDK, CLI, and project structure from the first session. See [Agent System](agent.mdx) for the full skill and rule inventory. Summary of what lives here:
 
 ```
-.claude/memory/
-├── index.md                    # Root index linking all memory topics
-├── profile/                    # Developer profile (created by /meta init)
-│   ├── index.md
-│   ├── identity.md             # Organization, goals, integrations
-│   ├── skills.md               # Skill dimensions and Growth Log
-│   └── preferences.md          # Verbosity and guidance style
-├── deployment-state.md         # Latest deployment outcomes
-├── decisions.md                # Architecture decisions recorded over time
-└── errors/                     # Error patterns and resolutions
+.claude/
+├── Overview.md      # Template-owned routing map: skills, rules, structure, stack, commands
+├── settings.json    # PostToolUse/PostToolUseFailure hook registrations, statusline command
+├── hooks/            # post-edit-validate.mjs, scaffold-registry-reminder.mjs, tool-failure-recovery.mjs
+├── skills/           # One directory per slash command, each with a SKILL.md
+├── rules/            # Path-scoped pointers to rule bodies bundled with @elevasis/sdk
+├── registries/       # Scaffold, skill-coverage, and knowledge registry data
+└── logs/             # Hook-written runtime state
 ```
 
-This directory is gitignored -- it is personal to you and not shared with collaborators. All cross-session knowledge (profile, errors, deployment state, decisions) lives here as plain markdown.
+`.claude/memory/` is not part of the shipped scaffold -- it is gitignored and created at runtime the first time a skill needs to persist state (for example, `/tutorial` writes `.claude/memory/profile.md` on first invocation).
 
 ---
 
-## Slash Commands
-
-The `.claude/skills/` directory contains skills covering the core development loop:
-
-- **`/setup`** -- First-time project setup: placeholder replacement, deps, verification
-- **`/deploy`** -- Full deploy pipeline: test, build, commit, push
-- **`/elevasis`** -- SDK operations: check, deploy, exec
-- **`/work`** -- Task tracking across sessions: auto-detects intent (create, save, resume); suggests complete
-- **`/status`** -- Quick project health check
-- **`/save`** -- Auto-manage docs from conversation context
-- **`/explore`** -- Codebase exploration anchored to docs
-- **`/continue`** -- Resume in-progress work from docs
-- **`/project`** -- Routes project management to the canonical `elevasis-sdk project:*` commands
-- **`/dsp`** -- Parallel agent dispatch for implementation tasks
-- **`/sync`** -- Pull latest, wipe caches, fresh reinstall
+## `elevasis-sdk deploy` Scope
 
-Boundary summary:
+`elevasis-sdk deploy` (run as `pnpm -C operations deploy` or `pnpm -C operations deploy:prod`) bundles `operations/src/` into a single file via esbuild and uploads it. There is no documentation-upload step in the current deploy path -- `ui/`, `core/`, and `.claude/` are not touched by deploy.
 
-- `/project` updates shared project records
-- `/work` manages docs-backed work tracking
-- `/adev` handles implementation and execution work
+---
 
-For detailed command documentation, see [Agent System](agent).
+## Configuration Files
 
----
+### `.elevasis`
 
-## File Classification
+A flat marker file at the project root recording `projectSlug`, `templateVersion`, `appMode` (`dev-centric` or `client-centric`), and `workosOrgId`. This is the canonical location for the template version -- not `elevasis.config.ts`.
 
-Not all scaffolded files participate in template updates. Files fall into two categories:
+### `.env`
 
-**SCAFFOLD_FILES total: 32**
+Contains `ELEVASIS_PLATFORM_KEY` (and optionally `ELEVASIS_PLATFORM_KEY_DEV`). Gitignored -- never commit it. `ui/` and `operations/` also have their own `.env` files for runtime-specific values.
 
-**INIT_ONLY** -- Written once during initial scaffold, never overwritten by updates:
+### `.npmrc`
 
-- `package.json`, `pnpm-workspace.yaml`, `tsconfig.json`
-- `.env`, `.npmrc`
-- `operations/src/index.ts`, `operations/src/email-notification/index.ts`, `operations/src/email-notification/exports.ts`, `operations/src/example/echo.ts`, `operations/src/example/index.ts`, `core/`
-- `docs/index.md`, `docs/in-progress/.gitkeep`
+Sets `auto-install-peers = true`. The SDK uses Zod as a peer dependency, so this ensures Zod installs automatically.
 
-**MANAGED** -- Written during initial scaffold and updated when the template evolves:
+### `.gitignore`
 
-- `operations/elevasis.config.ts`, `.gitignore`, `CLAUDE.md`, `.claude/settings.json`
-- Two hooks: `.claude/hooks/post-edit-validate.mjs`, `.claude/hooks/tool-failure-recovery.mjs`
-- Skills: `.claude/skills/work/SKILL.md`, `.claude/skills/elevasis/SKILL.md`, `.claude/skills/deploy/skill.md`, `.claude/skills/setup/SKILL.md`
-- Rule files: `.claude/rules/task-tracking.md`, `.claude/rules/platform.md`, `.claude/rules/error-handling.md`, `.claude/rules/docs.md`, `.claude/rules/execution.md`, `.claude/rules/observability.md`
-- One script: `.claude/scripts/statusline-command.js`
+Excludes `node_modules/`, `dist/`, `*.tsbuildinfo`, `.tanstack/`, `.env` and `.env.*` (except `.env.example`), `*.log`, `.claude/settings.local.json`, hook-written state in `.claude/logs/*.state.json`, `operations/dist/`, `operations/__elevasis_worker.ts` (a temporary file generated during deployment), and `tmp/*` (except `.gitkeep`).
 
 ---
 
 ## File Reference
 
-| File                            | When You Edit It                                                    |
-| ------------------------------- | ------------------------------------------------------------------- |
-| `operations/src/index.ts`       | Adding or removing resources                                        |
-| `operations/src/<domain>/*.ts`  | Writing and modifying workflow logic (organized by business domain) |
-| `docs/index.md`                 | Updating project documentation                                      |
-| `docs/resources.md`             | Never -- auto-generated by `/deploy` and `/elevasis deploy`         |
-| `operations/elevasis.config.ts` | Changing project-level settings                                     |
-| `.env`                          | Adding environment variables                                        |
-| `CLAUDE.md`                     | Rarely -- only to add project-specific context                      |
-| `.claude/skills/*/SKILL.md`     | Rarely -- skills work well as scaffolded                            |
+| File / Directory                    | When You Edit It                                                       |
+| ----------------------------------- | ---------------------------------------------------------------------- |
+| `operations/src/index.ts`           | Adding or removing resources, wiring a new domain                      |
+| `operations/src/<domain>/*.ts`      | Writing and modifying workflow or agent logic                          |
+| `operations/src/metadata.ts`        | Adding triggers, integrations, or human-checkpoint queue metadata      |
+| `core/types/index.ts`               | Defining or changing a workflow's Zod contract                         |
+| `core/config/organization-model.ts` | Never directly -- run `/om` instead                                    |
+| `operations/elevasis.config.ts`     | Changing project-level SDK settings (`defaultStatus`, `dev.port`)      |
+| `.elevasis`                         | Never manually -- updated by `/git-sync` and platform tooling          |
+| `.env`                              | Adding environment variables                                           |
+| `CLAUDE.md`                         | Rarely -- project identity and preferences, mostly written by `/setup` |
+| `.claude/skills/*/SKILL.md`         | Never in a derived project -- these arrive via `/git-sync`             |
 
 ---
 
-**Last Updated:** 2026-04-17
+**Last Updated:** 2026-08-06

package/reference/sdk/framework/tutorial-system.mdx

@@ -77,9 +77,9 @@ SECTION B -- Build your first thing                     (5 items)
   8  Going to production                                 [ ]
 
 SECTION C -- The Organization Model                     (3 items)
-  9  /knowledge ceremony -- identity, customers,         [ ]
+  9  /om ceremony -- identity, customers,                [ ]
      offerings via the layered flow
- 10  Features and labels                                 [ ]
+ 10  Systems, actions, and labels                         [ ]
  11  Entity extensions -- BaseProject, BaseDeal          [ ]
 
 SECTION D -- Modules (load on demand)                   (~6 items)

package/reference/sdk/human-in-the-loop.mdx

@@ -0,0 +1,152 @@
+---
+title: Human-in-the-Loop (HITL) Workflows
+description: How a workflow step opens an approval task, how it reaches the command queue, and how selecting an action resumes work -- the story that connects the approval adapter, checkpoint metadata, and the queue CLI.
+---
+
+The platform ships three separate pieces of HITL surface: the `approval` platform adapter, the `humanCheckpoints` entry in `operations/src/metadata.ts`, and the `queue:*` CLI family. Each is documented on its own elsewhere in this bundle, but nothing connects them into one story. This page is that story: a workflow step opens a task, the task lands in the command queue, a human or an agent resolves it, and resolution triggers whatever comes next.
+
+## The Three Pieces, In One Sentence Each
+
+- **`approval`** (`@elevasis/sdk/worker`) -- the typed adapter a step handler calls to open a task. See [Platform Adapters](platform-tools/adapters-platform.mdx).
+- **`humanCheckpoints`** (`operations/src/metadata.ts`) -- optional deployment metadata that gives a checkpoint a friendly name and documents what feeds it and what it hands off to. It does not route anything at runtime.
+- **`queue:*`** (`elevasis-sdk` CLI) -- how a human, or an agent debugging on a human's behalf, lists, inspects, and resolves tasks. See [CLI Management](cli-management.mdx#elevasis-sdk-queue).
+
+## The Story: Workflow to Resolution
+
+### 1. A step calls `approval.create()`
+
+A step handler imports the `approval` adapter from the worker runtime and opens a task. The step that does this is typically the workflow's last step -- once it returns, that execution is done. Calling `approval.create()` does **not** pause or suspend the workflow; there is no built-in mechanism that holds an execution open while a human decides. What happens after a decision is a separate execution, described below.
+
+```typescript
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { approval } from '@elevasis/sdk/worker'
+import { z } from 'zod'
+
+const inputSchema = z.object({
+  dealId: z.string(),
+  amount: z.number()
+})
+const outputSchema = z.object({
+  taskId: z.string()
+})
+
+export const requestDiscountApproval: WorkflowDefinition = {
+  config: {
+    resourceId: 'request-discount-approval',
+    name: 'Request Discount Approval',
+    type: 'workflow',
+    description: 'Opens a queue task for a human to approve or reject a discount',
+    version: '1.0.0',
+    status: 'dev'
+  },
+  contract: { inputSchema, outputSchema },
+  steps: {
+    createTask: {
+      id: 'createTask',
+      name: 'Create Approval Task',
+      description: 'Opens a HITL task for the discount amount',
+      handler: async (rawInput, context) => {
+        const input = rawInput as z.infer<typeof inputSchema>
+
+        const created = await approval.create({
+          actions: [
+            {
+              id: 'approve',
+              label: 'Approve',
+              type: 'primary',
+              target: { resourceType: 'workflow', resourceId: 'apply-discount' }
+            },
+            { id: 'reject', label: 'Reject', type: 'secondary' }
+          ],
+          context: { dealId: input.dealId, amount: input.amount },
+          description: `Approve a $${input.amount} discount for deal ${input.dealId}`,
+          humanCheckpoint: 'discount-review'
+        })
+
+        context.logger.info(`[createTask] Opened approval task ${created.id}`)
+        return { taskId: created.id }
+      },
+      inputSchema,
+      outputSchema,
+      next: null
+    }
+  },
+  entryPoint: 'createTask'
+}
+```
+
+`actions` is the set of buttons a reviewer can choose between. Each action needs `id`, `label`, and `type` (`'primary' | 'secondary' | 'danger' | 'outline'`, a semantic category, not a visual style -- see the constraint below). `target` is optional per action and is what makes resolution do something: it names the resource that runs next when that specific action is selected. `context` is whatever the reviewer needs to decide, shown alongside the task. `humanCheckpoint` is a free-form grouping id, covered in step 3.
+
+An action with no `target` is a valid pattern too -- a plain sign-off with nothing automated after it. Selecting it just marks the task completed; nothing else executes.
+
+### 2. The task lands in the command queue
+
+`approval.create()` inserts a row visible through the `queue:*` CLI immediately -- there is no deploy step in between. A workflow you already deployed starts producing tasks the moment a step calls the adapter.
+
+```bash
+elevasis-sdk queue:list --status pending --pretty
+elevasis-sdk queue:get <id> --pretty
+```
+
+### 3. Declaring the checkpoint (optional, but worth doing)
+
+`humanCheckpoint: 'discount-review'` in the call above is just a string -- the platform never validates it against anything at creation time. Declaring a matching entry in `operations/src/metadata.ts` is what gives that string a friendly name and a description in `queue:status` output, and documents the checkpoint in your Organization Model:
+
+```typescript
+import type { HumanCheckpointDefinition } from '@elevasis/sdk'
+
+export const humanCheckpoints: HumanCheckpointDefinition[] = [
+  {
+    resourceId: 'discount-review',
+    type: 'human',
+    name: 'Discount Review',
+    description: 'Review discounts above the auto-approve threshold',
+    version: '1.0.0',
+    status: 'prod',
+    links: [{ nodeId: 'system:sales.crm', kind: 'applies_to' }],
+    requestedBy: { workflows: ['request-discount-approval'] },
+    routesTo: { workflows: ['apply-discount'] }
+  }
+]
+```
+
+`requestedBy` and `routesTo` are documentation fields for the graph -- they record which resources typically create tasks at this checkpoint and which ones typically pick them up. **Neither field drives execution.** The actual continuation is decided per-action by that action's own `target`, from step 1. A checkpoint entry with a `routesTo.workflows` list that no action actually targets is a documentation mismatch, not a broken pipeline -- it will not stop anything from running, but it will describe a story your code does not tell.
+
+### 4. A human -- or an agent debugging on a human's behalf -- resolves the task
+
+```bash
+elevasis-sdk queue:get <id> --pretty
+elevasis-sdk queue:select <id> --action-id approve --pretty
+```
+
+Always run `queue:get` before `queue:select` on a task you did not just create -- read the context before you act on it. `queue:select` accepts `--payload` for structured input the continuation needs (a rejection reason, an adjusted amount) and `--notes` for a free-text decision note. See [CLI Management](cli-management.mdx#elevasis-sdk-queue) for the full flag reference and `@json:<path>` payload syntax.
+
+### 5. Resolution triggers the selected action's target
+
+Selecting `approve` executes the resource named in that action's `target` -- in the example above, the `apply-discount` workflow. This is a **new execution of a different resource**, not the original workflow resuming. Its input is the task's `context` merged with `actionId` and `actionPayload`:
+
+{/* doc-snippet:skip: illustrative excerpt, not a standalone compilable file */}
+
+```typescript
+// what apply-discount's entry step receives, shaped roughly like:
+const continuationInput = {
+  dealId: '...',
+  amount: 500,
+  actionId: 'approve',
+  actionPayload: {} // whatever --payload carried, or {}
+}
+```
+
+If the continuation's `inputSchema` does not declare `actionId` or `actionPayload`, Zod strips them by default -- only declare the ones you actually read.
+
+## Constraint: Never Pass `variant`
+
+The action shape accepts `id`, `label`, `type`, `icon`, `color`, `target`, `form`, `requiresConfirmation`, `confirmationMessage`, and `description`. There is no `variant` field, and the Command Center always renders every action button with a fixed `'light'` variant regardless of `type` or `color`. Do not add a `variant` property to an action object -- it is not part of the adapter's type and does not control anything the UI renders.
+
+The rendering lives in `CommandQueueDetailPage` in `@repo/ui`'s operations feature, where the action list maps to Mantine `Button`s with `variant` hardcoded and `color` resolved as `action.color || (action.type === 'danger' ? 'red' : 'blue')`. So the two levers you do have are real: use `type` to categorize the action semantically (`'danger'` for a destructive path), and `color` to override the derived color directly.
+
+## Related Reading
+
+- [Platform Adapters](platform-tools/adapters-platform.mdx) -- the full adapter catalog, including `approval`
+- [CLI Management](cli-management.mdx#elevasis-sdk-queue) -- every `queue:*` command and flag
+- [Resources](resources/index.mdx) -- `WorkflowDefinition` shape and step routing