@elevasis/sdk 1.47.0 → 1.49.0

package/reference/sdk/cli.mdx

@@ -13,7 +13,7 @@ pnpm add @elevasis/sdk
 
 After installation, the `elevasis-sdk` binary is available in your project's `node_modules/.bin/`. Most commands require `ELEVASIS_PLATFORM_KEY` to be set in your environment or a `.env` file.
 
-For management commands (project:\*, note:\*, acquisition:\*, client:\*, agent:\*, session:\*, queue:\*, schedule:\*, om:\*, ui:\*, skill:\*), see [CLI Management](cli-management.mdx).
+For management commands (project:\*, note:\*, error:\*, acquisition:\*, client:\*, agent:\*, session:\*, queue:\*, schedule:\*, om:\*, ui:\*, skill:\*, content:\*, request:\*, grant:\*), see [CLI Management](cli-management.mdx).
 
 ---
 
@@ -41,6 +41,13 @@ elevasis-sdk check
 
 `check` declares no `--api-url` flag -- it validates project source locally and never calls the API, so there is no base URL to override.
 
+**Flags:**
+
+| Flag               | Description                                        |
+| ------------------ | -------------------------------------------------- |
+| `--entry <path>` | Path to the entry file (default: `./src/index.ts`) |
+| `--skip-coverage`  | Skip the skill coverage gate                       |
+
 **Example output (success):**
 
 ```
@@ -84,10 +91,14 @@ elevasis-sdk deploy
 
 **Flags:**
 
-| Flag                | Description                                                |
-| ------------------- | ---------------------------------------------------------- |
-| `--api-url <url>` | Override the API base URL (default: production)            |
-| `--prod`            | Force production target, overriding `NODE_ENV=development` |
+| Flag                | Description                                                  |
+| ------------------- | ------------------------------------------------------------ |
+| `--api-url <url>` | Override the API base URL (default: production)              |
+| `--entry <path>`  | Path to the entry file (default: `./src/index.ts`)           |
+| `--prod`            | Force production target, overriding `NODE_ENV=development`   |
+| `--major`           | Bump the major version before deploying (`1.0.0` -> `2.0.0`) |
+| `--minor`           | Bump the minor version before deploying (`1.0.0` -> `1.1.0`) |
+| `--patch`           | Bump the patch version before deploying (`1.0.0` -> `1.0.1`) |
 
 **Environment variables:**
 
@@ -141,15 +152,20 @@ elevasis-sdk exec <resource> --input '{...}'
 - Use `--async` to return an `executionId` immediately and poll for completion
 - `--input` accepts a JSON string matching the resource's `inputSchema`
 - Organization is derived from your API key -- no org prefix needed
+- On a lost connection during a synchronous run, the CLI looks up the most recent running execution for the resource and resumes polling rather than failing outright
 
 **Flags:**
 
-| Flag                | Description                                             |
-| ------------------- | ------------------------------------------------------- |
-| `--input <json>`  | JSON input matching the resource's input schema         |
-| `--async`           | Execute asynchronously, return execution ID immediately |
-| `--json`            | Output raw JSON instead of formatted display            |
-| `--api-url <url>` | Override the API base URL                               |
+| Flag                        | Description                                                                                                               |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `-i, --input <json>`      | JSON input matching the resource's input schema                                                                           |
+| `-f, --input-file <path>` | Read input from a JSON file instead of `--input` (avoids shell escaping). Relative paths resolve against the project root |
+| `--async`                   | Execute asynchronously, return execution ID immediately                                                                   |
+| `--cleanup-input`           | Delete the input file after a successful execution (only files under `<projectRoot>/tmp/` are eligible)                 |
+| `--prod`                    | Target production (overrides `NODE_ENV=development`)                                                                      |
+| `--api-url <url>`         | Override the API base URL                                                                                                 |
+
+`exec` does not declare a `--json` flag -- output is always the formatted display shown below.
 
 **Example:**
 
@@ -240,7 +256,7 @@ elevasis-sdk executions [resource]
 
 | Flag                  | Description                                                     |
 | --------------------- | --------------------------------------------------------------- |
-| `--limit <n>`       | Maximum number of executions to return (default: 20)            |
+| `--limit <n>`       | Maximum number of executions to return (default: 50)            |
 | `--status <status>` | Filter by status: `running`, `completed`, `failed`, `cancelled` |
 | `--json`              | Output raw JSON                                                 |
 | `--api-url <url>`   | Override the API base URL                                       |
@@ -273,15 +289,21 @@ elevasis-sdk execution <resource> <id>
 
 **Behavior:**
 
-- Shows the complete execution record: input, output, logs, duration, and error (if any)
+- Shows the complete execution record: input, result, logs, duration, and error (if any)
+- `--input` and `--result` force those sections to print even when the CLI would otherwise omit them; both print automatically when the execution carries input data, or is `completed` with a result
+- `--logs-only` prints only the execution logs and skips the rest of the record
 - Use `--json` to get the raw JSON response for programmatic use
 
 **Flags:**
 
-| Flag                | Description               |
-| ------------------- | ------------------------- |
-| `--json`            | Output raw JSON           |
-| `--api-url <url>` | Override the API base URL |
+| Flag                | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `--logs-only`       | Show only execution logs                             |
+| `--input`           | Force the Input section to print                     |
+| `--result`          | Force the Result section to print                    |
+| `--prod`            | Target production (overrides `NODE_ENV=development`) |
+| `--json`            | Output raw JSON response                             |
+| `--api-url <url>` | Override the API base URL                            |
 
 **Example:**
 
@@ -290,10 +312,12 @@ elevasis-sdk execution onboard-client exec_abc001
 ```
 
 ```
-  Resource:   onboard-client
-  Status:     completed
-  Started:    2026-02-25 14:32:01
-  Duration:   1.2s
+  Resource:     onboard-client
+  Execution ID: exec_abc001
+  Status:       COMPLETED
+  Started:      2026-02-25 14:32:01
+  Ended:        2026-02-25 14:32:02
+  Duration:     1.2s
 
   Input:
   {
@@ -301,17 +325,20 @@ elevasis-sdk execution onboard-client exec_abc001
     "email": "jane@example.com"
   }
 
-  Output:
+  Result:
   {
     "success": true,
     "clientId": "client_1708521600000",
     "welcomeEmailSent": true
   }
 
-  Logs:
+  Execution Logs:
+
   [14:32:01.123]  Starting onboard-client workflow
   [14:32:01.456]  Created client record
   [14:32:01.891]  Welcome email sent to jane@example.com
+
+  Total logs: 3
 ```
 
 ---
@@ -406,24 +433,31 @@ elevasis-sdk deployments
 
 **Behavior:**
 
-- Shows deployment history with status, timestamp, and resource count
-- Active deployment is marked; previous deployments show as `stopped`
+- Shows deployment history with status, SDK version, and creation timestamp
+- Status is one of `deploying`, `active`, `failed`, `rolled_back`, or `stopped`
 
 **Flags:**
 
-| Flag                | Description               |
-| ------------------- | ------------------------- |
-| `--json`            | Output raw JSON           |
-| `--api-url <url>` | Override the API base URL |
+| Flag                | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `--prod`            | Target production (overrides `NODE_ENV=development`) |
+| `--json`            | Output raw JSON                                      |
+| `--api-url <url>` | Override the API base URL                            |
 
 **Example output:**
 
 ```
 $ elevasis-sdk deployments
 
-  deploy_abc123   active    2026-02-25 14:00:00   4 resources
-  deploy_abc122   stopped   2026-02-24 09:30:00   3 resources
-  deploy_abc121   stopped   2026-02-23 11:15:00   3 resources
+1. [ACTIVE] deploy_abc123
+   SDK Version: 1.45.0
+   Created: 2/25/2026, 2:00:00 PM
+
+2. [STOPPED] deploy_abc122
+   SDK Version: 1.44.2
+   Created: 2/24/2026, 9:30:00 AM
+
+2 deployment(s)
 ```
 
 ---
@@ -495,21 +529,24 @@ elevasis-sdk creds delete <name> [--force]
 **Subcommands:**
 
 - `list` -- display all credentials (metadata only, no secret values)
-- `create` -- create a new credential; `--name` and `--type` are required; `--value` is an optional JSON string for the initial value
+- `create` -- create a new credential; `--name`, `--type`, and `--value` are all required
 - `update <name>` -- replace the value of an existing credential; `--value` (JSON) is required
 - `rename <name>` -- rename a credential; `--to <newName>` is required
 - `delete <name>` -- delete a credential; pass `--force` to skip the confirmation prompt
 
 **Flags:**
 
-| Flag                | Description                                        |
-| ------------------- | -------------------------------------------------- |
-| `--name <name>`   | Credential name (create: required)                 |
-| `--type <type>`   | Credential type, e.g. `api-key` (create: required) |
-| `--value <json>`  | Credential value as a JSON string                  |
-| `--to <newName>`  | New name (rename: required)                        |
-| `--force`           | Skip confirmation prompt (delete)                  |
-| `--api-url <url>` | Override the API base URL                          |
+| Flag                | Description                                                                     |
+| ------------------- | ------------------------------------------------------------------------------- |
+| `--name <name>`   | Credential name: lowercase letters, digits, and hyphens only (create: required) |
+| `--type <type>`   | Credential type: `api-key` or `webhook-secret` (create: required)               |
+| `--value <json>`  | Credential value as a JSON string (create and update: required)                 |
+| `--to <newName>`  | New name (rename: required)                                                     |
+| `--force`           | Skip confirmation prompt (delete)                                               |
+| `--prod`            | Target production (overrides `NODE_ENV=development`)                            |
+| `--api-url <url>` | Override the API base URL                                                       |
+
+OAuth credentials cannot be created through the CLI -- they require the Command Center's browser OAuth flow. See [Command Center](deployment/command-center.mdx#credentials).
 
 **Examples:**
 
@@ -540,16 +577,16 @@ elevasis-sdk rename <old-id> --to <new-id> [--execute] [--prod]
 - Dry-run by default -- shows all affected rows per table without modifying any data
 - Pass `--execute` to perform the rename
 - Org-scoped: only updates rows belonging to your organization
-- Updates resource references across 6 tables:
+- Refuses to run if the new resource ID already has execution history in your organization, to prevent a data collision
+- Updates resource references across 5 tables:
 
-| Table                | Column(s) updated |
-| -------------------- | ----------------- |
-| `executions`         | `resource_id`     |
-| `sessions`           | `resource_id`     |
-| `workflow_configs`   | `resource_id`     |
-| `workflow_schedules` | `resource_id`     |
-| `execution_events`   | `resource_id`     |
-| `session_events`     | `resource_id`     |
+| Table               | Column(s) updated                          |
+| ------------------- | ------------------------------------------ |
+| `execution_logs`    | `resource_id`                              |
+| `execution_metrics` | `resource_id`                              |
+| `sessions`          | `resource_id`                              |
+| `command_queue`     | `origin_resource_id`                       |
+| `task_schedules`    | `origin_resource_id`, `target_resource_id` |
 
 **Flags:**
 
@@ -570,14 +607,13 @@ elevasis-sdk rename ist-upload-workflow --to ist-upload-contacts-workflow
   Dry run — no changes made.
 
   Rows that would be updated:
-    executions          6
-    sessions            0
-    workflow_configs    0
-    workflow_schedules  0
-    execution_events    0
-    session_events      0
+    execution_logs       6
+    execution_metrics    6
+    sessions             0
+    command_queue        0
+    task_schedules       0
 
-  Total: 6 rows
+  Total: 12 rows
 
   Re-run with --execute to apply changes.
 ```
@@ -659,12 +695,13 @@ elevasis-sdk doctor [--verbose] [--prod]
 
 **Behavior:**
 
-Runs four sequential checks and reports `[OK]` / `[FAIL]` / `[WARN]` for each. Exits with code 1 if any check fails. Later checks are skipped when a prerequisite fails.
+Runs five sequential checks and reports `[OK]` / `[FAIL]` / `[WARN]` for each. Exits with code 1 if any check fails. Later checks are skipped when a prerequisite fails.
 
 1. Project root resolved -- locates the `.elevasis` marker file from the current working directory
 2. `.env` found at project root
 3. `ELEVASIS_PLATFORM_KEY` present and non-empty
 4. API reachable and key valid -- calls `GET /api/external/health`
+5. Systems roster -- every platform-cataloged System Interface, checked against the deployed readiness snapshot. Reuses the key and connectivity Check 4 already proved. A System the project has not adopted renders `[WARN]`, never `[FAIL]` -- partial adoption is the designed opt-out. `[FAIL]` is reserved for adopted-but-broken Systems.
 
 **Flags:**
 
@@ -683,6 +720,8 @@ Running Elevasis SDK doctor checks...
 [OK]   API key: Set (length: 56)
 [OK]   API: Reachable. Workspace: Acme Corp (ws_abc123)
 [WARN] SDK compat: server minSdkVersion is 1.25.0; check is advisory in v1.
+[OK]   Systems: platform.projects/delivery: ready
+[WARN] Systems: sales.crm/pipeline: not adopted
 
 All checks passed. Your Elevasis project is correctly configured.
 ```
@@ -695,11 +734,11 @@ All checks passed. Your Elevasis project is correctly configured.
 
 These flags are accepted by all commands:
 
-| Flag                | Description                                                                                         |
-| ------------------- | --------------------------------------------------------------------------------------------------- |
-| `--api-url <url>` | Override the API base URL. Priority: flag > `ELEVASIS_API_URL` env var > `NODE_ENV`-based default |
-| `--json`            | Output raw JSON (available on most commands)                                                        |
-| `--prod`            | Target production, overriding `NODE_ENV=development`                                                |
+| Flag                | Description                                                                                                                      |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `--api-url <url>` | Override the API base URL. Priority: `--api-url` flag > `--prod` flag > `ELEVASIS_API_URL` env var > `NODE_ENV`-based default |
+| `--json`            | Output raw JSON (available on most commands)                                                                                     |
+| `--prod`            | Target production, overriding `NODE_ENV=development`                                                                             |
 
 **API base URL resolution:**
 
@@ -710,4 +749,4 @@ These flags are accepted by all commands:
 
 ---
 
-**Last Updated:** 2026-08-12
+**Last Updated:** 2026-08-17

package/reference/sdk/define-builders.mdx

@@ -23,7 +23,7 @@ export function defineWorkflow<TWorkflow extends WorkflowDefinition>(workflow: T
 
 What it buys you is narrower inference. Annotate a literal `const echo: WorkflowDefinition = { ... }` and TypeScript widens every field to the interface's declared type -- `config.resourceId` becomes `string`, not `'echo'`. Pass the same object to `defineWorkflow({ ... })` with no annotation and `TWorkflow` is inferred from the literal you wrote, so `defineWorkflow(...).config.resourceId` keeps the literal type `'echo'`. That distinction only matters if something downstream reads the value back and wants the narrower type -- a test asserting on `resourceId`, a lookup table keyed by it, a second resource that imports the first and needs its literal id. A workflow file that is only ever consumed by the deploy pipeline, which just needs it to satisfy `WorkflowDefinition`, gets nothing extra from the wrapper.
 
-That is a real, but narrow, upside -- and it is honestly reflected in what ships. The scaffolded template's own workflow files (`echo.ts`, `email-notification.ts`) use the plain annotated-literal form, not `defineWorkflow`. The builder is real, exported, and demonstrated in the SDK's own test fixtures with exactly the calling convention above -- it is simply not the house style the template ships with. Use the annotated literal by default, matching what a scaffolded project already contains; reach for `defineWorkflow` / `defineStep` / `defineContract` specifically when you want the object's literal types preserved past its own definition.
+That is a real, but narrow, upside -- and it is honestly reflected in what ships. The scaffolded template's own workflow files (`example/echo.ts`, `email-notification/index.ts`) use the plain annotated-literal form, not `defineWorkflow`. The builder is real, exported, and demonstrated in the SDK's own test fixtures with exactly the calling convention above -- it is simply not the house style the template ships with. Use the annotated literal by default, matching what a scaffolded project already contains; reach for `defineWorkflow` / `defineStep` / `defineContract` specifically when you want the object's literal types preserved past its own definition.
 
 `defineWorkflowConfig` is a different kind of helper in this same group -- it derives `config` fields from an Organization Model resource descriptor instead of preserving literal types. It has its own page: see [The Deployment Spec Pattern](project-deployment-spec.mdx#defineworkflowconfig-deriving-config-from-one-om-descriptor).
 

package/reference/sdk/deployment/command-center.mdx

@@ -105,8 +105,8 @@ Keep relationships in sync with your handler code. When you add an `execution.tr
 **Validation error examples:**
 
 ```
-ERROR  Relationship target 'send-proposal' not found in organization resources
-ERROR  Duplicate resource ID 'score-lead' in deployment
+ERROR  [acme-corp] Resource 'score-lead' triggers non-existent workflow: send-proposal
+ERROR  Duplicate resource ID 'score-lead' in deployment. Each resource must have a unique ID.
 ```
 
 ### Graph Serialization

package/reference/sdk/deployment/index.mdx

@@ -288,4 +288,4 @@ Dashboard appears before Business in the primary sidebar. Business is a navigati
 
 - [Command Center](command-center.mdx) - Resource graph, relationships, node types, and post-deployment UI reference
 - [Execution Reference](execution-reference.mdx) - REST endpoints for executing resources, managing deployments, and React UI components for custom Run dialogs
-- [Platform Adapters](../platform-tools/adapters-platform.mdx) - `approval.create()` and all platform service adapters
+- [Platform Adapters](../platform-tools/adapters-platform.mdx) - `approval.create()` and the full platform service adapter catalog

package/reference/sdk/exports.mdx

@@ -8,7 +8,7 @@ description: "Auto-generated catalog of all published @elevasis/sdk subpath expo
 
 | Import | Title | Group | Description |
 | --- | --- | --- | --- |
-| `@elevasis/sdk` | SDK | Getting Started |  |
-| `@elevasis/sdk/worker` | Worker Runtime | Runtime |  |
-| `@elevasis/sdk/test-utils` | Test Utils | Testing |  |
-| `@elevasis/sdk/node` | Node Build Tooling | Tooling |  |
+| `@elevasis/sdk` | SDK | Getting Started | Default entry: defineWorkflow, defineStep, defineContract, contract-ref resolution, shared types, and workflow utilities. |
+| `@elevasis/sdk/worker` | Worker Runtime | Runtime | worker_threads runtime plus the typed platform and integration adapters a step handler calls at execution time. |
+| `@elevasis/sdk/test-utils` | Test Utils | Testing | Workflow test harness, resource registry helpers, and mock adapters for unit-testing definitions without the platform. |
+| `@elevasis/sdk/node` | Node Build Tooling | Tooling | Node-only build-time codegen for knowledge nodes and bodies. Requires fs/path/process -- not browser-safe. |

package/reference/sdk/framework/agent.mdx

@@ -36,6 +36,7 @@ The template ships these skills, all committed to version control:
 | Skill             | Purpose                                                                                          |
 | ----------------- | ------------------------------------------------------------------------------------------------ |
 | `/client`         | Client portfolio management -- list, resolve, inspect, and maintain client records               |
+| `/content`        | Content pipeline operations -- list items, inspect, board view, review queue, distributions      |
 | `/deploy`         | Test, build, fix issues, then commit and push                                                    |
 | `/dsp`            | Dispatch subagents in parallel for implementation tasks                                          |
 | `/elevasis`       | SDK operations -- check, deploy, execute, inspect, and debug resources                           |
@@ -77,11 +78,11 @@ The gate is **outgoing commits**, checked with `git rev-list --count @{u}..HEAD`
 
 ## The Ambient Vibe Layer
 
-External projects run an always-on natural-language intent classifier -- there is no `/vibe` command and no activation phrase. Every message is silently classified into one of seven intents (Capture, Query, Describe, Transition, Navigate, Codify, Toggle) before the agent responds. Codify and Toggle detect intent and delegate immediately to `/om`; the classifier never runs the organization-model ceremony itself. The full classifier definition and fixture tables ship with the SDK at `operations/node_modules/@elevasis/sdk/reference/rules/vibe.md`. Vibe is explicitly off inside the monorepo, which uses the task-class routing in `agent-start-here.md` instead.
+External projects run an always-on natural-language intent classifier -- there is no `/vibe` command and no activation phrase. Every message is silently classified into one of eight intents (Capture, Query, Describe, Transition, Navigate, Codify, Toggle, Operate) before the agent responds. Codify and Toggle detect intent and delegate immediately to `/om`; Operate delegates to `/elevasis` (`elevasis-sdk describe` then a confirmed `exec`); the classifier never runs the organization-model ceremony or executes a deployed resource itself. The full classifier definition and fixture tables ship with the SDK at `operations/node_modules/@elevasis/sdk/reference/rules/vibe.md` and the per-intent detail at `operations/node_modules/@elevasis/sdk/reference/rules/vibe-intents.md`. Vibe is explicitly off inside the monorepo, which uses the task-class routing in `agent-start-here.md` instead.
 
 ## The Rules Layer
 
-`.claude/rules/` in the git-tracked template holds short pointer files with `paths:` frontmatter that Claude Code auto-loads for matching files. The authoritative rule bodies ship with the installed `@elevasis/sdk` package at `operations/node_modules/@elevasis/sdk/reference/rules/` and update whenever the SDK dependency is bumped. Rules include `agent-start-here.md` (always-loaded), `vibe.md` (always-loaded), `organization-os.md`, `deployment.md`, `error-handling.md`, `execution.md`, `frontend.md`, `observability.md`, `operations.md`, `organization-model.md`, `platform.md`, `shared-types.md`, `task-tracking.md`, `ui.md`, and `active-change-index.md` (which flags areas under active platform change).
+`.claude/rules/` in the git-tracked template holds short pointer files with `paths:` frontmatter that Claude Code auto-loads for matching files. The authoritative rule bodies ship with the installed `@elevasis/sdk` package at `operations/node_modules/@elevasis/sdk/reference/rules/` and update whenever the SDK dependency is bumped. The bundle carries 19 rules: `agent-start-here.md` (always-loaded), `vibe.md` (always-loaded), `vibe-intents.md`, `agent-runtime.md`, `content.md`, `organization-os.md`, `deployment.md`, `error-handling.md`, `execution.md`, `frontend.md`, `observability.md`, `operations.md`, `organization-model.md`, `package-taxonomy.md`, `platform.md`, `shared-types.md`, `task-tracking.md`, `ui.md`, and `active-change-index.md` (which flags areas under active platform change). The template also ships a small number of project-authored, System-specific rules directly under `.claude/rules/` -- for example `crm.md` and `lead-gen.md` -- that are not part of the bundled set.
 
 ## Template Version Tracking
 
@@ -89,4 +90,4 @@ The scaffold's version marker is `templateVersion` in the project-root `.elevasi
 
 ---
 
-**Last Updated:** 2026-08-06
+**Last Updated:** 2026-08-17

package/reference/sdk/framework/index.mdx

@@ -83,7 +83,7 @@ See [Tutorial System](tutorial-system.mdx) for the full lesson breakdown, track
 
 ## Documentation
 
-- [Project Structure](project-structure.mdx) - Directory-by-directory walkthrough of the scaffolded project
+- [Project Structure](project-structure.mdx) - Directory-by-directory walkthrough of the scaffolded project's structure and layout
 - [Agent System](agent.mdx) - Skill inventory, rules layer, ambient vibe classifier, and session bootstrap
 - [Tutorial System](tutorial-system.mdx) - Two-track onboarding (8 vibe-coder + 19 technical lessons), track persistence, and progress tracking
 

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

@@ -22,7 +22,7 @@ The scaffold is a workspace with `ui/`, `operations/`, and `core/` packages plus
 ├── .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)
+├── .npmrc                # ignore-workspace-root-check + auto-install-peers (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)
@@ -43,11 +43,17 @@ Cross-runtime types, schemas, constants, and organization-model configuration sh
 ```
 core/
 ├── config/
-│   ├── organization-model.ts                 # Canonical model + resource descriptor resolvers
+│   ├── organization-model.ts                 # Entry barrel -- assembly, public exports, knowledge wiring
+│   ├── organization-model/
+│   │   ├── profile.ts                          # defineOrganizationModel() body (/om codify target)
+│   │   ├── systems.ts                          # Operational graph, resource descriptors, governance model
+│   │   └── navigation.ts                       # Sidebar tree, projectTemplateNavigationSurfaces
 │   ├── organization-model.test.ts
 │   ├── organization-model.contract.test.ts
-│   ├── extensions/                            # Project-specific model extensions
-│   ├── knowledge/                              # Knowledge graph nodes
+│   ├── extensions/                            # Project-specific model extensions (deal-ecom.ts.example, index.ts)
+│   ├── knowledge/
+│   │   ├── nodes/                                # Hand-authored knowledge node MDX (welcome.mdx)
+│   │   └── _generated/                           # Compiled knowledge bodies and search index -- do not edit
 │   └── README.md
 ├── test-utils/
 │   └── core-contract-factories.ts
@@ -63,7 +69,7 @@ core/
 
 ### `core/config/organization-model.ts`
 
-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`.
+The entry file for the organization model, split into a thin assembly barrel plus three sibling files under `core/config/organization-model/`: `profile.ts` (the `/om` codify target -- identity, customers, offerings, roles, goals), `systems.ts` (the operational graph: Systems, resources, the resource-descriptor getters `getTemplateWorkflowResourceDescriptor` and `getTemplateAgentResourceDescriptor`, and governance model), and `navigation.ts` (the sidebar tree). `organization-model.ts` resolves the canonical model (`canonicalOrganizationModel`, via `resolveOrganizationModel()`) and re-exports every public symbol from the split files so `operations/src/index.ts` and other consumers keep importing from the single entry path. Direct edits to any of these files are discouraged -- the resolver runs Zod cross-reference validation that a syntactically valid edit can still fail. All edits go through `/om`.
 
 ### `core/types/index.ts`
 
@@ -86,13 +92,18 @@ operations/
 │   ├── metadata.ts                    # Trigger/integration/human-checkpoint metadata (starts empty)
 │   ├── resource-registry.test.ts
 │   ├── README.md
+│   ├── __tests__/
+│   │   └── sdk-test-utils.compat.ts   # Shared test helpers -- assertResourceRegistry, runWorkflow
 │   ├── example/
 │   │   ├── echo.ts                    # Starter workflow
+│   │   ├── echo.test.ts
 │   │   ├── example-agent.ts           # Starter agent
+│   │   ├── example-agent.test.ts
 │   │   └── index.ts                   # Domain barrel (exports workflows + agents)
 │   ├── email-notification/
 │   │   ├── exports.ts                 # Domain barrel
 │   │   ├── index.ts                   # Multi-step workflow using the notifications adapter
+│   │   ├── email-notification.test.ts
 │   │   └── adapter-contract.test.ts
 │   └── shared/                        # Empty by default (.gitkeep) -- code shared across domains
 ├── elevasis.config.ts                 # Project-level SDK config
@@ -111,7 +122,7 @@ Convention seed for deployment mechanics that are not resource identity: trigger
 
 ### `operations/src/example/echo.ts`
 
-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.
+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 -- a minimal single-shot (non-session) `AgentDefinition` with no tools and no memory. Each has a matching `*.test.ts` file exercising it through the shared test helpers in `operations/src/__tests__/sdk-test-utils.compat.ts`.
 
 ### `operations/src/email-notification/index.ts`
 
@@ -173,7 +184,7 @@ The `.claude/` directory and `CLAUDE.md` give Claude Code full awareness of the
 ├── 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
+├── registries/       # Skill-coverage and knowledge registry data (skill-coverage.json, graph-skills.json, knowledge-flags.json)
 └── logs/             # Hook-written runtime state
 ```
 
@@ -183,7 +194,7 @@ The `.claude/` directory and `CLAUDE.md` give Claude Code full awareness of the
 
 ## `elevasis-sdk deploy` Scope
 
-`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.
+`elevasis-sdk deploy` (run as `pnpm -C operations run deploy` or `pnpm -C operations run deploy:prod` -- the explicit `run` matters, because `pnpm -C operations deploy` without it invokes pnpm's own builtin `deploy` command instead of the project script) 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.
 
 ---
 
@@ -199,29 +210,29 @@ Contains `ELEVASIS_PLATFORM_KEY` (and optionally `ELEVASIS_PLATFORM_KEY_DEV`). G
 
 ### `.npmrc`
 
-Sets `auto-install-peers = true`. The SDK uses Zod as a peer dependency, so this ensures Zod installs automatically.
+Sets `ignore-workspace-root-check=true` (isolates this project so pnpm does not walk up and find the monorepo's `pnpm-workspace.yaml`) and `auto-install-peers=true` (the SDK uses Zod as a peer dependency, so this ensures Zod installs automatically).
 
 ### `.gitignore`
 
-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`).
+Excludes `node_modules/`, `dist/`, `*.tsbuildinfo`, `.tanstack/`, `.env` and `.env.*` (except `.env.example`), `*.log`, `.DS_Store`, `.claude/settings.local.json`, hook-written state in `.claude/logs/*.state.json`, `operations/dist/`, `operations/__elevasis_worker.ts` (a temporary file generated during deployment), `tmp/*` (except `.gitkeep`), and `.vercel`.
 
 ---
 
 ## File Reference
 
-| 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`             |
+| 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` and `core/config/organization-model/**` | 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-08-06
+**Last Updated:** 2026-08-17

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

@@ -82,7 +82,7 @@ SECTION C -- The Organization Model                     (3 items)
  10  Systems, actions, and labels                         [ ]
  11  Entity extensions -- BaseProject, BaseDeal          [ ]
 
-SECTION D -- Modules (load on demand)                   (~6 items)
+SECTION D -- Modules (load on demand)                   (6 items)
  12  HITL                                                [ ]
  13  Schedules                                           [ ]
  14  Notifications + integrations                        [ ]