@elevasis/sdk 1.44.3 → 1.46.0

package/reference/sdk/cli-management.mdx

@@ -5,6 +5,8 @@ description: elevasis-sdk management commands -- project, note, acquisition, cli
 
 This page covers the domain management commands for `elevasis-sdk`. For core SDK commands (check, deploy, exec, resources, executions, describe, creds, rename), see [CLI Reference](cli.mdx).
 
+Every command family on this page -- `project`, `note`, `acquisition`, `client`, `agent`, `session`, `queue`, `schedule`, `om:doctor`, and `request` -- also accepts `--prod` to target production, overriding `NODE_ENV=development` (live as of `@elevasis/sdk` 1.45.0). See [CLI Reference's Global Flags](cli.mdx#global-flags) for the full description; per-command flag tables below list `--api-url` and other command-specific flags only, not `--prod` or `--json`.
+
 ---
 
 ## JSON-valued options
@@ -94,10 +96,16 @@ elevasis-sdk project:task:get <id>
 elevasis-sdk project:task:create --project <id> --title "Implement API"
 elevasis-sdk project:task:create --project <id> --title "Implement API" --checklist @json:tmp/task-checklist.json
 elevasis-sdk project:task:update <id> --status in_progress
+elevasis-sdk project:task:update <id> --parent <parent-task-id>
+elevasis-sdk project:task:update <id> --clear-milestone
 elevasis-sdk project:task:update <id> --checklist @json:tmp/task-checklist.json
 elevasis-sdk project:task:delete <id>
 ```
 
+`milestone_id` and `parent_task_id` are nullable, and `--clear-milestone` / `--clear-parent` are how they are set to null. Each is mutually exclusive with its set-flag and exits `CONFLICTING_FLAGS` if both are passed, matching `project:update --client` / `--clear-client`. An empty string does **not** clear either one -- `--milestone ""` fails UUID validation rather than detaching.
+
+`--sequence <n>` on `project:milestone:create` and `project:milestone:update` writes the display order that `project:milestone:list` sorts by. It takes a non-negative integer and rejects anything else with `INVALID_SEQUENCE` before the request is sent.
+
 Task commands also expose agent-oriented resume state:
 
 ```bash
@@ -186,9 +194,9 @@ elevasis-sdk request:get <id>
 
 Most `project:*` commands support:
 
-| Flag              | Description                                        |
-| ----------------- | -------------------------------------------------- |
-| `--pretty`        | Human-readable terminal output instead of raw JSON |
+| Flag                | Description                                        |
+| ------------------- | -------------------------------------------------- |
+| `--pretty`          | Human-readable terminal output instead of raw JSON |
 | `--api-url <url>` | Override the API base URL                          |
 
 For exact required flags and accepted enum values, see the command source under `packages/sdk/src/cli/commands/project/`.
@@ -416,7 +424,22 @@ JWT-gated routes at the original unprefixed paths remain for the Command Center.
 
 Full CRUD management for client records. The `client:*` family covers create, read, update, and delete operations at `/api/external/clients`.
 
-For complete field definitions, filter options, and relationship semantics, see the [Clients feature documentation](/technical/features/operations/clients).
+**Field definitions** (`ClientProfileSchema` in `@elevasis/core/organization-model`):
+
+| Field          | Shape                                                                                          |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| `id`           | UUID                                                                                           |
+| `slug`         | stable model id                                                                                |
+| `name`         | display label                                                                                  |
+| `status`       | `active | onboarding | paused | completed | churned` (default `onboarding`)                |
+| `source`       | optional lowercase source key                                                                  |
+| `identity`     | `organizationName`, `shortName`, `clientBrief`, `geographicFocus[]`, `timeZone`                |
+| `branding`     | `voice`, `tagline`, `values[]`                                                                 |
+| `workspace`    | `kind` (`external-project | internal-project | none`), `owner`, `projectId`, `workspacePath` |
+| `links`        | `projectIds[]`, `primaryCompanyId`, `primaryContactId`, `sourceDealId`                         |
+| `prompts`      | `defaultContext`                                                                               |
+| `config`       | free-form JSON record                                                                          |
+| `customValues` | free-form JSON record                                                                          |
 
 **Quick reference:**
 
@@ -506,12 +529,12 @@ must be exposed as a separate explicit command.
 
 **`session:turn` flags:**
 
-| Flag                        | Description                                  |
-| --------------------------- | -------------------------------------------- |
-| `-i, --input <json>`      | Turn input as JSON                           |
-| `-f, --input-file <path>` | Read turn input from a JSON file             |
-| `--json`                    | Output as JSON                               |
-| `--api-url <url>`         | Override the API base URL                    |
+| Flag                        | Description                      |
+| --------------------------- | -------------------------------- |
+| `-i, --input <json>`      | Turn input as JSON               |
+| `-f, --input-file <path>` | Read turn input from a JSON file |
+| `--json`                    | Output as JSON                   |
+| `--api-url <url>`         | Override the API base URL        |
 
 **`session:messages` flags:**
 
@@ -547,7 +570,7 @@ must be exposed as a separate explicit command.
 
 ## elevasis-sdk queue:\*
 
-Manage HITL command queue tasks. See the [Command Queue CLI Guide](/technical/development/agent-driven-development/cli-operations) for the full command reference.
+Manage HITL command queue tasks.
 
 **Quick reference:**
 
@@ -583,13 +606,42 @@ elevasis-sdk queue:status --pretty
 | `--pretty`           | Human-readable output instead of raw JSON |
 | `--api-url <url>`  | Override the API base URL                 |
 
+**Shared flags (`queue:get`, `queue:expire`, `queue:status`):**
+
+| Flag                | Description                               |
+| ------------------- | ----------------------------------------- |
+| `--pretty`          | Human-readable output instead of raw JSON |
+| `--api-url <url>` | Override the API base URL                 |
+
 **Auth:** Calls `/api/external/command-queue/*` with API-key auth.
 
 ---
 
 ## elevasis-sdk schedule:\*
 
-Manage recurring, relative, and absolute task schedules. See the [Schedule CLI Guide](/technical/development/agent-driven-development/cli-operations) for the full command reference including schedule config JSON shapes.
+Manage recurring, relative, and absolute task schedules. `schedule:create` and `schedule:update --schedule-config` accept raw JSON; the CLI does not parse natural-language or shorthand cron flags.
+
+**`--schedule-config` JSON shapes:**
+
+```json
+// recurring, fixed interval
+{ "type": "recurring", "interval": "weekly", "time": "09:00", "timezone": "America/Los_Angeles", "payload": {} }
+```
+
+```json
+// recurring, cron expression
+{ "type": "recurring", "cron": "0 9 * * 1", "timezone": "America/Los_Angeles", "payload": {} }
+```
+
+```json
+// relative to an anchor time
+{ "type": "relative", "anchorAt": "2026-06-01T00:00:00Z", "payload": {} }
+```
+
+```json
+// absolute, one or more fixed run times
+{ "type": "absolute", "items": [{ "runAt": "2026-06-01T09:00:00Z", "payload": {}, "label": "Launch" }] }
+```
 
 **Quick reference:**
 
@@ -623,9 +675,14 @@ At least one field must be provided. `--description` and `--clear-description` a
 
 ## elevasis-sdk om:\*
 
-Knowledge map inspection. The `om:*` (Organization Model) commands expose knowledge graph traversal via the CLI.
+Knowledge graph inspection, plus an Organization Model write surface (`om:scaffold:*`, `om:rename`, `om:deprecate`). The `om:*` (Organization Model) commands expose knowledge graph traversal via the CLI. `om:*` and `knowledge:*` are aliases of the same subcommands for the read-only surface described below -- the write commands are registered under `om:*` only, with no `knowledge:*` alias.
 
-For the full command reference, flag details, and graph architecture, see the [knowledge:\* CLI documentation](/technical/features/knowledge/cli-and-skill).
+**Path axes for `knowledge:ls` / `om:ls`:** `/by-system/<id>`, `/by-ontology/<ontologyId>`, `/by-kind/<kind>`, `/by-owner/<ownerId>`, `/by-domain/<domain>` (enumerate all items in a domain: `clients`, `roles`, `policies`, `customers`, `offerings`, `goals`), `/by-item/<domain>/<itemId>` (single domain-item profile), `/graph/<nodeId>/governs`, `/graph/<nodeId>/governed-by`, `/<nodeId>` (single node), `/all-systems`, `/all-resources`, `/all-roles`.
+
+- `knowledge:ls <path>` -- list nodes/edges for the mount; default output is an id + summary table, `--json` returns `{ path, mount, args, results }`.
+- `knowledge:cat <id>` -- render a node's `body` MDX to stdout; `--json` returns the full node object (body, links, owners, timestamps).
+- `knowledge:graph <id>` -- show outgoing + incoming edges grouped by edge kind.
+- `om:doctor` -- validate Organization Model integrity against published `@elevasis/core/organization-model` primitives. This is a deliberately reduced 3-check command: two of the monorepo platform CLI's five checks assert monorepo-only paths that do not exist in a tenant project, so they are not ported. `--json` output includes `checksRun: 3` so a caller can tell it apart from the platform CLI's 5-check version.
 
 In tenant projects, SDK read commands load `core/config/organization-model.ts` through the SDK's layout-aware TypeScript loader. The temporary bundle and dependency resolution are anchored at the package root that owns SDK dependencies, so hoisted pnpm workspaces resolve `esbuild` and `@elevasis/core` correctly. Missing org-model files still return the default model; malformed files or files with no usable export emit diagnostics. `knowledge:generate` / `om:generate` is the exception because it reads MDX and codegen inputs directly.
 
@@ -639,6 +696,7 @@ elevasis-sdk knowledge:search <query>
 elevasis-sdk knowledge:describe <nodeId>
 elevasis-sdk knowledge:skills <nodeId>
 elevasis-sdk knowledge:generate
+elevasis-sdk om:doctor --org <OrgName>
 ```
 
 These are registered as `knowledge:*` subcommands on `elevasis-sdk`. Both the SDK CLI (`elevasis-sdk knowledge:*`) and the platform CLI (`elevasis knowledge:*`) call the same query functions in `@repo/core/knowledge/queries`.
@@ -715,6 +773,81 @@ elevasis-sdk knowledge:generate [--source <path>] [--output <path>] [--flags-out
 elevasis-sdk om:generate
 ```
 
+### om:scaffold:\*
+
+Six scaffolders that splice new Organization Model entries into project source files: `om:scaffold:system`, `om:scaffold:resource`, `om:scaffold:role`, `om:scaffold:knowledge`, `om:scaffold:ontology`, `om:scaffold:fill`. There is no `knowledge:scaffold:*` alias.
+
+```bash
+elevasis-sdk om:scaffold:system --id sales.pipeline --title "Sales Pipeline" --kind operational
+elevasis-sdk om:scaffold:resource --id lead-discovery-workflow --system-path sales.pipeline --title "Lead Discovery"
+elevasis-sdk om:scaffold:role --id ops-lead --title "Ops Lead" --responsibility "Own weekly pipeline review"
+elevasis-sdk om:scaffold:knowledge --id outreach-playbook --kind playbook --system-path sales.pipeline
+elevasis-sdk om:scaffold:ontology --id deal --system-path sales.pipeline --kind object
+elevasis-sdk om:scaffold:fill --gaps tmp/conformance-gaps.json
+```
+
+**Default is dry-run.** Every `om:scaffold:*` command previews its change and writes nothing unless `--write` is passed (the one exception, `om:scaffold:ontology`, never writes at all -- see below). This inverted from earlier behavior, where these commands applied by default. An existing invocation that does not pass `--write` now only previews and silently stops applying -- this is the single most important thing to know about this command family.
+
+**`--dry-run` is not a flag on any `om:scaffold:*` command.** It exists only as a deprecated programmatic/TypeScript option consumed internally by the handler functions; passing `--dry-run` on the command line is an unrecognized-option error. `om:rename` and `om:deprecate`, documented in the next section, are different commands with their own real `--dry-run` flag -- do not carry that convention over here.
+
+**Splice targets:**
+
+| Subcommand              | Writes                                                                                                                                    |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `om:scaffold:system`    | Splices `core/config/organization-model/systems.ts`                                                                                       |
+| `om:scaffold:resource`  | Splices `core/config/organization-model/systems.ts` -- **known-broken, see below**                                                        |
+| `om:scaffold:role`      | Splices `core/config/organization-model/profile.ts`                                                                                       |
+| `om:scaffold:knowledge` | Writes a new `core/config/knowledge/nodes/<id>.mdx` file (no splice)                                                                    |
+| `om:scaffold:ontology`  | Print-only by design -- writes nothing, and carries no `--write` flag                                                                     |
+| `om:scaffold:fill`      | Writes new `core/config/organization-model/api-interfaces/<systemPath>.ts` const files and splices the import + field into `systems.ts` |
+
+**`om:scaffold:resource` is currently non-functional against all three real project layouts.** Its splice anchor never received the anchor-scoping fix that landed for `om:scaffold:role` on 2026-08-11, so it still searches for the resource-descriptors closing brace unscoped -- in a real file that closing-brace shape recurs, and it splices into the wrong one, producing invalid TypeScript. The command's own post-write validation catches this and rolls the file back, so it fails safely, but it does not currently produce a usable result. Do not rely on it until the anchor fix ships.
+
+**Common flag:**
+
+| Flag      | Description                                                                  |
+| --------- | ---------------------------------------------------------------------------- |
+| `--write` | Apply the change. Default (omitted) is a dry-run preview -- no files written |
+
+`om:scaffold:ontology` has no `--write` flag; it is always print-only. Each subcommand also has its own identifying flags (`--id`, `--title`, `--system-path`, and so on) -- omit any of them to be prompted interactively. `om:scaffold:fill` is the exception: it is non-interactive and requires `--gaps <path>` pointing at a conformance-gap JSON file.
+
+### om:rename / om:deprecate
+
+Plan or apply an Organization Model system rename cascade, or a lifecycle transition (deprecate/archive). Neither has a `knowledge:*` alias.
+
+```bash
+elevasis-sdk om:rename sales.crm sales.pipeline
+elevasis-sdk om:rename sales.crm sales.pipeline --write
+
+elevasis-sdk om:deprecate sales.crm --to deprecated
+elevasis-sdk om:deprecate sales.crm --to archived --force --confirm archive:sales.crm --write
+```
+
+**Unlike `om:scaffold:*`, both commands default to preview via a real `--dry-run` flag, not the absence of `--write`.** `--write` applies the edit, regenerates knowledge nodes when needed, and runs `om:doctor`. The two conventions on this page name their default state differently -- `om:scaffold:*` has no flag describing its default at all, while `om:rename` / `om:deprecate` spell it out with `--dry-run` -- so do not assume one family's flag shape from the other.
+
+`om:rename` cannot re-parent a system: root-to-nested or nested-to-root moves must be done by hand.
+
+**`om:rename <oldPath> <newPath>` flags:**
+
+| Flag        | Description                                                              |
+| ----------- | ------------------------------------------------------------------------ |
+| `--dry-run` | Preview only (default)                                                   |
+| `--write`   | Apply edits, regenerate knowledge nodes when needed, and run `om:doctor` |
+| `--json`    | Output JSON                                                              |
+
+**`om:deprecate <systemPath>` flags:**
+
+| Flag                  | Description                                                                |
+| --------------------- | -------------------------------------------------------------------------- |
+| `--to <lifecycle>`  | Target lifecycle: `deprecated` or `archived`. Default: `deprecated`        |
+| `--dry-run`           | Preview only (default)                                                     |
+| `--write`             | Apply the lifecycle edit and run `om:doctor`                               |
+| `--force`             | Allow archiving despite live dependents when paired with exact `--confirm` |
+| `--confirm <token>` | Exact archive confirmation token: `archive:<systemPath>`                   |
+| `--json`              | Output JSON                                                                |
+
+**Implementation:** `packages/sdk/src/cli/commands/om/rename.ts`, `packages/sdk/src/cli/commands/om/deprecate.ts` -- registered in `packages/sdk/src/cli/index.ts`
+
 ---
 
 ## elevasis-sdk ui:use-local / ui:use-published
@@ -761,25 +894,25 @@ The same coverage gate runs inside `elevasis-sdk check` when the coverage regist
 
 Current status of all SDK CLI domains. Domains marked `deferred` have no CLI commands yet.
 
-| Domain      | CLI surface                                                               | API surface                                                    | Status                        |
-| ----------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------- |
-| platform    | top-level SDK commands                                                    | mixed platform APIs                                            | implemented                   |
-| project     | `project:*`                                                               | `apps/api/src/projects/`                                       | implemented                   |
-| knowledge   | `knowledge:*`                                                             | file/generated knowledge data                                  | implemented                   |
-| creds       | `creds *` nested Commander group                                          | credentials API                                                | implemented                   |
-| ui          | `ui:*`                                                                    | local project file edits                                       | implemented                   |
-| request     | `request:submit`, `request:list`, `request:get`                           | requests API                                                   | implemented read/write scope  |
-| error       | `error resolve`, `error resolve-execution`                                | execution error APIs                                           | partial                       |
-| acquisition | `acquisition:list:*`, `acquisition:deal:*`                                | `/api/external/acquisition/lists*`, `/api/external/deals*`     | implemented read-only scope   |
-| client      | `client:*`                                                                | `/api/external/clients`                                        | implemented read/write scope  |
-| agent       | `agent:list`, `agent:get`                                                 | `/api/external/agents*`                                        | implemented read-only scope   |
+| Domain      | CLI surface                                                                                        | API surface                                                    | Status                        |
+| ----------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------- |
+| platform    | top-level SDK commands                                                                             | mixed platform APIs                                            | implemented                   |
+| project     | `project:*`                                                                                        | `apps/api/src/projects/`                                       | implemented                   |
+| knowledge   | `knowledge:*`                                                                                      | file/generated knowledge data                                  | implemented                   |
+| creds       | `creds *` nested Commander group                                                                   | credentials API                                                | implemented                   |
+| ui          | `ui:*`                                                                                             | local project file edits                                       | implemented                   |
+| request     | `request:submit`, `request:list`, `request:get`                                                    | requests API                                                   | implemented read/write scope  |
+| error       | `error resolve`, `error resolve-execution`                                                         | execution error APIs                                           | partial                       |
+| acquisition | `acquisition:list:*`, `acquisition:deal:*`                                                         | `/api/external/acquisition/lists*`, `/api/external/deals*`     | implemented read-only scope   |
+| client      | `client:*`                                                                                         | `/api/external/clients`                                        | implemented read/write scope  |
+| agent       | `agent:list`, `agent:get`                                                                          | `/api/external/agents*`                                        | implemented read-only scope   |
 | session     | `session:create`, `session:turn`, `session:messages`, `session:list`, `session:get`, `session:end` | `/api/external/sessions*`                                      | implemented multi-turn scope  |
-| queue       | `queue:list`, `queue:get`, `queue:select`, `queue:expire`, `queue:status` | `/api/external/command-queue*`                                 | implemented                   |
-| schedule    | `schedule:list`, `schedule:get`, `schedule:create`, `schedule:update`     | `/api/external/task-scheduler/schedules*`                      | implemented                   |
-| skill       | `skill:scaffold`, `skill:check-coverage`                                  | local CLI catalog and `.claude/registries/skill-coverage.json` | implemented developer tooling |
-| content     | none                                                                      | not scoped here                                                | deferred                      |
-| seo         | none                                                                      | not scoped here                                                | deferred                      |
-| monitoring  | none                                                                      | not scoped here                                                | deferred                      |
+| queue       | `queue:list`, `queue:get`, `queue:select`, `queue:expire`, `queue:status`                          | `/api/external/command-queue*`                                 | implemented                   |
+| schedule    | `schedule:list`, `schedule:get`, `schedule:create`, `schedule:update`                              | `/api/external/task-scheduler/schedules*`                      | implemented                   |
+| skill       | `skill:scaffold`, `skill:check-coverage`                                                           | local CLI catalog and `.claude/registries/skill-coverage.json` | implemented developer tooling |
+| content     | none                                                                                               | not scoped here                                                | deferred                      |
+| seo         | none                                                                                               | not scoped here                                                | deferred                      |
+| monitoring  | none                                                                                               | not scoped here                                                | deferred                      |
 
 ### Promotion Criteria
 
@@ -792,4 +925,4 @@ A domain should meet all four criteria before gaining a `*:list` / `*:get` surfa
 
 ---
 
-**Last Updated:** 2026-05-19
+**Last Updated:** 2026-08-12

package/reference/sdk/cli.mdx

@@ -39,11 +39,7 @@ elevasis-sdk check
   - Relationship declarations referencing non-existent resources
 - Exits with code 0 on success, code 1 on validation failure
 
-**Flags:**
-
-| Flag                | Description               |
-| ------------------- | ------------------------- |
-| `--api-url <url>` | Override the API base URL |
+`check` declares no `--api-url` flag -- it validates project source locally and never calls the API, so there is no base URL to override.
 
 **Example output (success):**
 
@@ -88,10 +84,10 @@ elevasis-sdk deploy
 
 **Flags:**
 
-| Flag                | Description                                                               |
-| ------------------- | ------------------------------------------------------------------------- |
-| `--api-url <url>` | Override the API base URL (default: production)                           |
-| `--prod`            | Force production target, overriding `NODE_ENV=development` (internal use) |
+| Flag                | Description                                                |
+| ------------------- | ---------------------------------------------------------- |
+| `--api-url <url>` | Override the API base URL (default: production)            |
+| `--prod`            | Force production target, overriding `NODE_ENV=development` |
 
 **Environment variables:**
 
@@ -320,6 +316,84 @@ elevasis-sdk execution onboard-client exec_abc001
 
 ---
 
+## elevasis-sdk execution:cancel
+
+Cancel a running execution.
+
+**Synopsis:**
+
+```
+elevasis-sdk execution:cancel <resourceId> <executionId>
+```
+
+**Behavior:**
+
+- Calls `POST /api/external/executions/:resourceId/:executionId/cancel`
+- The result reports which method was used: an in-memory signal if the execution's worker process is still reachable, or a database fallback if not
+- A 409 response means the execution is not in a running state -- it already finished. That is a normal race, not a command failure
+
+**Flags:**
+
+| Flag                | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `--prod`            | Target production (overrides `NODE_ENV=development`) |
+| `--api-url <url>` | Override the API base URL                            |
+| `--json`            | Output raw JSON response                             |
+
+**Example:**
+
+```bash
+elevasis-sdk execution:cancel my-workflow 9c47c944-67eb-4c84-98cb-bb951d05ede3
+```
+
+```
+  Execution cancelled
+    Resource:     my-workflow
+    Execution ID: 9c47c944-67eb-4c84-98cb-bb951d05ede3
+    Method:       in-memory signal
+```
+
+**Implementation:** `packages/sdk/src/cli/commands/execution-cancel.ts`, registered in `packages/sdk/src/cli/index.ts`
+
+---
+
+## elevasis-sdk executions:delete
+
+Delete a resource's execution history (destructive).
+
+**Synopsis:**
+
+```
+elevasis-sdk executions:delete <resourceId> [--force]
+```
+
+**Behavior:**
+
+- Calls `DELETE /api/external/executions/:resourceId`
+- Requires a typed `DELETE` confirmation at an interactive prompt unless `--force` is passed
+- `--resource-status <status>` (`dev` or `prod`) scopes the delete to runs from one deployment lane only
+- `--json` without `--force` is a hard error -- it throws `executions:delete requires --force when --json is set`, because a JSON caller is assumed non-interactive and there is nothing to answer the confirmation prompt
+
+**Flags:**
+
+| Flag                           | Description                                                  |
+| ------------------------------ | ------------------------------------------------------------ |
+| `--prod`                       | Target production (overrides `NODE_ENV=development`)         |
+| `--api-url <url>`            | Override the API base URL                                    |
+| `--resource-status <status>` | Only delete runs from this deployment lane (`dev` | `prod`) |
+| `--force`                      | Skip the typed confirmation prompt                           |
+| `--json`                       | Output raw JSON response                                     |
+
+**Example:**
+
+```bash
+elevasis-sdk executions:delete my-workflow --force
+```
+
+**Implementation:** `packages/sdk/src/cli/commands/executions-delete.ts`, registered in `packages/sdk/src/cli/index.ts`
+
+---
+
 ## elevasis-sdk deployments
 
 List all deployments for your organization.
@@ -541,7 +615,8 @@ elevasis-sdk cli [domain] [--format markdown|json]
 | --------------------- | ----------------------------------------------------------- |
 | `--domain <domain>` | Filter output to one domain (alternative to positional arg) |
 | `--format <format>` | Output format: `markdown` (default) or `json`               |
-| `--api-url <url>`   | Override the API base URL                                   |
+
+`cli` declares no `--api-url` flag -- it walks the locally registered Commander command graph and never calls the API.
 
 **Examples:**
 
@@ -579,7 +654,7 @@ Check that your Elevasis project is correctly configured.
 **Synopsis:**
 
 ```
-elevasis-sdk doctor [--verbose]
+elevasis-sdk doctor [--verbose] [--prod]
 ```
 
 **Behavior:**
@@ -596,6 +671,7 @@ Runs four sequential checks and reports `[OK]` / `[FAIL]` / `[WARN]` for each. E
 | Flag        | Description                                                         |
 | ----------- | ------------------------------------------------------------------- |
 | `--verbose` | Print full paths, response bodies, and error details for each check |
+| `--prod`    | Report against production (overrides `NODE_ENV=development`)        |
 
 **Example output (all passing):**
 
@@ -623,14 +699,15 @@ These flags are accepted by all commands:
 | ------------------- | --------------------------------------------------------------------------------------------------- |
 | `--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`                                                |
 
 **API base URL resolution:**
 
 - Production (default): `https://api.elevasis.io`
 - Development (`NODE_ENV=development`): `http://localhost:<port>`
 - Override: set `ELEVASIS_API_URL` or pass `--api-url`
-- Force production: pass `--prod` on `deploy` (overrides `NODE_ENV=development`)
+- Force production: pass `--prod` after the command name on any authenticated command (overrides `NODE_ENV=development`). Live as of `@elevasis/sdk` 1.45.0; `--api-url https://api.elevasis.io` is the equivalent form on older installs.
 
 ---
 
-**Last Updated:** 2026-05-19
+**Last Updated:** 2026-08-12

package/reference/sdk/concepts.mdx

@@ -75,6 +75,8 @@ The Elevasis SDK uses [Zod](https://zod.dev) for schema definition. Zod is a Typ
 
 `z.infer` creates a TypeScript type from a schema so the type system can check your code. You define the schema once and get both runtime validation and compile-time checking. Without it, you would have to define the same shape twice -- once as a Zod schema and once as a TypeScript type.
 
+{/* doc-snippet:skip: illustrative excerpt -- omits `import { z } from 'zod'` since the point is z.infer's behavior, not a runnable module */}
+
 ```ts
 const myInput = z.object({ name: z.string(), age: z.number() });
 type MyInput = z.infer<typeof myInput>;

package/reference/sdk/define-builders.mdx

@@ -0,0 +1,76 @@
+---
+title: When to Reach for the define* Builders
+description: defineWorkflow, defineStep, defineContract, defineResource, and defineTopology exist for two different reasons -- this page teaches which reason applies before you pick a builder over a plain object literal.
+---
+
+`@elevasis/sdk`'s root export includes a family of `define*` functions: `defineWorkflow`, `defineStep`, `defineContract`, `defineWorkflowConfig`, `defineResource`, `defineResources`, `defineResourceOntology`, `defineTopology`, `defineTopologyRelationship`, plus the `topologyRelationship` / `topologyRef` helpers. Every existing recipe in this bundle teaches the plain object-literal shape instead (a `WorkflowDefinition` written out by hand with a `: WorkflowDefinition` annotation), which is completely valid TypeScript -- but it means the builders are never actually demonstrated, so there is nothing here to tell you when reaching for one buys you something real versus when it is just a different way to write the same object. This page is that judgment call. For the full list of what `@elevasis/sdk` exports, see the [Export Catalog](exports.mdx).
+
+The family splits into two groups that do genuinely different things, and the judgment call is different for each.
+
+## Group 1: Workflow Builders Are Type Inference, Not Validation
+
+`defineWorkflow`, `defineStep`, and `defineContract` do nothing at runtime. Their entire implementation is an identity function constrained by a generic:
+
+{/* doc-snippet:skip: source excerpt (WorkflowDefinition intentionally unimported), not a standalone compilable file */}
+
+```typescript
+export function defineWorkflow<TWorkflow extends WorkflowDefinition>(workflow: TWorkflow): TWorkflow {
+  return workflow
+}
+```
+
+`defineStep` and `defineContract` are the same three lines against `WorkflowStep` and `Contract`. Calling one of these does not validate, transform, or check anything beyond what TypeScript's structural typing already does on the argument you pass it.
+
+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.
+
+`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).
+
+## Group 2: Resource and Topology Builders Do Real Work
+
+`defineResource`, `defineResources`, `defineResourceOntology`, `defineTopology`, and `defineTopologyRelationship` are a different animal entirely -- each one calls a Zod schema's `.parse()` on its way out:
+
+{/* doc-snippet:skip: source excerpt (ResourceEntry/ResourceEntrySchema intentionally unimported), not a standalone compilable file */}
+
+```typescript
+export function defineResource<const TResource extends ResourceEntry>(resource: TResource): TResource {
+  return ResourceEntrySchema.parse(resource) as TResource
+}
+```
+
+A hand-typed object that satisfies the `ResourceEntry` TypeScript interface skips that check entirely at the point you write it. It is not unvalidated forever -- the whole Organization Model gets parsed eventually -- but a mistake surfaces later, at whole-model validation, as a less specific error than the one `defineResource` would have raised on the exact line that defined the bad resource.
+
+`defineTopology` and `defineTopologyRelationship` go a step further: they compile human-authored references into the canonical shape the graph actually stores. A relationship's `from` / `to` can be written as an already-typed node ref, or as a resource descriptor object handed to you by another part of the model -- `compileTopologyNodeRef` resolves either into the canonical `{ kind, id }` form. This is not something a plain object literal can replicate without reimplementing that resolution step by hand:
+
+{/* doc-snippet:skip: illustrative excerpt (someWorkflowResourceDescriptor intentionally undefined), not a standalone compilable file */}
+
+```typescript
+import { defineTopology, topologyRef, topologyRelationship } from '@elevasis/sdk'
+
+const topology = defineTopology({
+  'trigger-handles-webhook': topologyRelationship.triggers(
+    topologyRef.trigger('inbound-webhook'),
+    someWorkflowResourceDescriptor, // a resource object, resolved for you
+    { systemPath: 'sales.lead-gen', required: true }
+  )
+})
+```
+
+For this group, reaching for the builder is not a style preference -- it is the only path that gets you both the validation and the reference compilation. Do not hand-author the parsed topology shape (`{ from: { kind: 'resource', id: '...' }, to: ... }`) directly; author against the helpers and let them produce it.
+
+**Tenant caveat:** these builders live in the Organization Model authoring layer. In a template-based project, `core/config/organization-model.ts` and its split sibling files are edited through the `/om` command, not by hand -- so day to day you are unlikely to call `defineResource` or `defineTopology` yourself even though they are part of the published surface. Understanding what they do is still useful: it is why hand-editing those files instead of going through `/om` is risky, since you would be reproducing Zod validation and reference compilation by hand and likely getting one of them wrong.
+
+## Quick Decision Guide
+
+- Writing a workflow, step, or contract, and nothing downstream needs the literal types back -- use the plain annotated object literal. This is what the scaffolded template ships.
+- Writing a workflow, step, or contract, and something downstream reads the value back and needs its literal types preserved -- wrap it in `defineWorkflow` / `defineStep` / `defineContract`.
+- Deriving a workflow's `config` from an OM resource descriptor that already has `ontology.primaryAction` set -- use `defineWorkflowConfig`.
+- Authoring an Organization Model resource, resource ontology binding, or topology relationship directly (Elevasis's own workspace-internal model, or inside the tooling `/om` itself runs) -- always use `defineResource` / `defineResourceOntology` / `defineTopology` / `defineTopologyRelationship`, never the raw parsed shape.
+- Authoring a tenant project's own Organization Model -- go through `/om`; you generally will not call the Group 2 builders yourself.
+
+## Documentation
+
+- [Export Catalog](exports.mdx) -- the generated, per-subpath inventory of everything `@elevasis/sdk` exports
+- [Resources](resources/index.mdx) -- the `WorkflowDefinition` / `AgentDefinition` shape these builders wrap
+- [The Deployment Spec Pattern](project-deployment-spec.mdx) -- `defineWorkflowConfig` and `projectDeploymentSpec` in context

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

@@ -54,6 +54,8 @@ Every resource you deploy becomes a node in the graph. Some nodes are executable
 
 Relationships are edges in the graph. Declare them in `DeploymentSpec`:
 
+{/* doc-snippet:skip: illustrative excerpt -- DeploymentSpec, scoreLeadWorkflow, sendProposalWorkflow are shown as already-defined resources from elsewhere in the project, not a standalone compilable file */}
+
 ```typescript
 const org: DeploymentSpec = {
   workflows: [scoreLeadWorkflow, sendProposalWorkflow],
@@ -126,7 +128,9 @@ The Command Queue surfaces all pending Human-in-the-Loop (HITL) approval request
 - Approve or reject with an optional comment
 - See the history of past decisions
 
-**How it connects to your code:** Approval requests appear when a workflow step calls `approval.create()`. The workflow pauses at that step and waits for a decision.
+**How it connects to your code:** Approval requests appear when a workflow step calls `approval.create()`. The step then **completes normally — the workflow does not pause.** Resolving the request later triggers a **new** execution of whichever resource the selected action's `target` names. Structure the work accordingly: everything that must happen after the decision belongs in that target resource, not in later steps of the workflow that raised the request.
+
+{/* 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'
@@ -141,7 +145,7 @@ const task = await approval.create({
 })
 ```
 
-> **SDK takeaway:** Use `approval.create()` to create approval gates. Provide rich `context` so reviewers have what they need to decide.
+> **SDK takeaway:** Use `approval.create()` to raise an approval request, and put the post-decision work in the resource each action targets. Provide rich `context` so reviewers have what they need to decide. See [Human-in-the-Loop Workflows](../human-in-the-loop.mdx) for the full path from workflow to checkpoint to queue resolution.
 
 ---