@elevasis/sdk 1.49.0 → 1.51.0

package/reference/sdk/cli.mdx

@@ -43,10 +43,10 @@ elevasis-sdk check
 
 **Flags:**
 
-| Flag               | Description                                        |
-| ------------------ | -------------------------------------------------- |
-| `--entry <path>` | Path to the entry file (default: `./src/index.ts`) |
-| `--skip-coverage`  | Skip the skill coverage gate                       |
+| Flag              | Description                                        |
+| ----------------- | -------------------------------------------------- |
+| `--entry <path>`  | Path to the entry file (default: `./src/index.ts`) |
+| `--skip-coverage` | Skip the skill coverage gate                       |
 
 **Example output (success):**
 
@@ -91,14 +91,14 @@ elevasis-sdk deploy
 
 **Flags:**
 
-| Flag                | Description                                                  |
-| ------------------- | ------------------------------------------------------------ |
+| 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`) |
+| `--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:**
 
@@ -156,13 +156,13 @@ elevasis-sdk exec <resource> --input '{...}'
 
 **Flags:**
 
-| Flag                        | Description                                                                                                               |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| 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`)                                                                      |
+| `--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.
@@ -218,9 +218,9 @@ elevasis-sdk resources
 
 **Flags:**
 
-| Flag                | Description               |
-| ------------------- | ------------------------- |
-| `--json`            | Output raw JSON           |
+| Flag              | Description               |
+| ----------------- | ------------------------- |
+| `--json`          | Output raw JSON           |
 | `--api-url <url>` | Override the API base URL |
 
 **Example output:**
@@ -254,11 +254,11 @@ elevasis-sdk executions [resource]
 
 **Flags:**
 
-| Flag                  | Description                                                     |
-| --------------------- | --------------------------------------------------------------- |
+| Flag                | Description                                                     |
+| ------------------- | --------------------------------------------------------------- |
 | `--limit <n>`       | Maximum number of executions to return (default: 50)            |
 | `--status <status>` | Filter by status: `running`, `completed`, `failed`, `cancelled` |
-| `--json`              | Output raw JSON                                                 |
+| `--json`            | Output raw JSON                                                 |
 | `--api-url <url>`   | Override the API base URL                                       |
 
 **Example:**
@@ -296,13 +296,13 @@ elevasis-sdk execution <resource> <id>
 
 **Flags:**
 
-| 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                             |
+| 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:**
@@ -361,11 +361,11 @@ elevasis-sdk execution:cancel <resourceId> <executionId>
 
 **Flags:**
 
-| Flag                | Description                                          |
-| ------------------- | ---------------------------------------------------- |
-| `--prod`            | Target production (overrides `NODE_ENV=development`) |
+| Flag              | Description                                          |
+| ----------------- | ---------------------------------------------------- |
+| `--prod`          | Target production (overrides `NODE_ENV=development`) |
 | `--api-url <url>` | Override the API base URL                            |
-| `--json`            | Output raw JSON response                             |
+| `--json`          | Output raw JSON response                             |
 
 **Example:**
 
@@ -403,13 +403,13 @@ elevasis-sdk executions:delete <resourceId> [--force]
 
 **Flags:**
 
-| Flag                           | Description                                                  |
-| ------------------------------ | ------------------------------------------------------------ |
-| `--prod`                       | Target production (overrides `NODE_ENV=development`)         |
+| 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                                     |
+| `--force`                    | Skip the typed confirmation prompt                           |
+| `--json`                     | Output raw JSON response                                     |
 
 **Example:**
 
@@ -438,10 +438,10 @@ elevasis-sdk deployments
 
 **Flags:**
 
-| Flag                | Description                                          |
-| ------------------- | ---------------------------------------------------- |
-| `--prod`            | Target production (overrides `NODE_ENV=development`) |
-| `--json`            | Output raw JSON                                      |
+| Flag              | Description                                          |
+| ----------------- | ---------------------------------------------------- |
+| `--prod`          | Target production (overrides `NODE_ENV=development`) |
+| `--json`          | Output raw JSON                                      |
 | `--api-url <url>` | Override the API base URL                            |
 
 **Example output:**
@@ -480,9 +480,9 @@ elevasis-sdk describe <resource>
 
 **Flags:**
 
-| Flag                | Description               |
-| ------------------- | ------------------------- |
-| `--json`            | Output raw JSON response  |
+| Flag              | Description               |
+| ----------------- | ------------------------- |
+| `--json`          | Output raw JSON response  |
 | `--api-url <url>` | Override the API base URL |
 
 **Example:**
@@ -520,7 +520,7 @@ Manage credentials for your organization. Credentials store API keys and secrets
 
 ```
 elevasis-sdk creds list
-elevasis-sdk creds create --name <name> --type <type> [--value <json>]
+elevasis-sdk creds create --name <name> --type <type> --value <json>
 elevasis-sdk creds update <name> --value <json>
 elevasis-sdk creds rename <name> --to <newName>
 elevasis-sdk creds delete <name> [--force]
@@ -536,23 +536,36 @@ elevasis-sdk creds delete <name> [--force]
 
 **Flags:**
 
-| Flag                | Description                                                                     |
-| ------------------- | ------------------------------------------------------------------------------- |
+| 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)               |
+| `--type <type>`   | Credential type (create: required). See the table below                         |
 | `--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`)                            |
+| `--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).
+**Keep long-lived secrets out of `--value`.** A value passed literally survives in shell history and in the transcript of whatever ran the command. Write the JSON to a file and pass `--value @json:tmp/credential.json` instead -- the `@json:` prefix works on any flag of any `elevasis-sdk` command, resolves relative paths against the project root, and expands inside the CLI process, so the secret never appears in the invocation. Delete the file afterwards.
+
+**Credential types.** The accepted values are the platform's own `CredentialTypeSchema`, minus `oauth`:
+
+| Type             | Shape                                              |
+| ---------------- | -------------------------------------------------- |
+| `api-key`        | Single-field API key                               |
+| `api-key-secret` | Key and secret pair                                |
+| `webhook-secret` | Webhook signing secret                             |
+| `clickup`        | ClickUp personal token                             |
+| `instagram`      | `{ accessToken, igUserId }` for Content Publishing |
+
+OAuth credentials cannot be created through the CLI -- they need a `provider`, which the external create route does not accept, and they require the Command Center's browser OAuth flow. See [Command Center](deployment/command-center.mdx#credentials).
 
 **Examples:**
 
 ```bash
 elevasis-sdk creds list
 elevasis-sdk creds create --name openai-key --type api-key --value '{"key":"sk-proj-***"}'
+elevasis-sdk creds create --name my-instagram --type instagram --value @json:tmp/ig.json --prod
 elevasis-sdk creds update openai-key --value '{"key":"sk-proj-new"}'
 elevasis-sdk creds rename openai-key --to openai-prod-key
 elevasis-sdk creds delete openai-prod-key --force
@@ -590,11 +603,11 @@ elevasis-sdk rename <old-id> --to <new-id> [--execute] [--prod]
 
 **Flags:**
 
-| Flag                | Description                             |
-| ------------------- | --------------------------------------- |
+| Flag              | Description                             |
+| ----------------- | --------------------------------------- |
 | `--to <new-id>`   | Required. The new resource ID           |
-| `--execute`         | Perform the rename (default is dry-run) |
-| `--prod`            | Target the production environment       |
+| `--execute`       | Perform the rename (default is dry-run) |
+| `--prod`          | Target the production environment       |
 | `--api-url <url>` | Override the API base URL               |
 
 **Example (dry-run):**
@@ -644,11 +657,12 @@ elevasis-sdk cli [domain] [--format markdown|json]
 - When `domain` is omitted, all domains are listed
 - `--format json` returns a structured array suitable for programmatic use; `--format markdown` (default) renders a human-readable table
 - The runtime catalog is always up to date with what is actually registered -- it does not parse TypeScript source
+- This is the only catalog. `elevasis-sdk --help` no longer carries a hand-maintained `Commands:` list in `program.description()`; it prints a short pointer to `elevasis-sdk cli` plus Commander's own list of registered commands, so there is nothing left to drift
 
 **Flags:**
 
-| Flag                  | Description                                                 |
-| --------------------- | ----------------------------------------------------------- |
+| Flag                | Description                                                 |
+| ------------------- | ----------------------------------------------------------- |
 | `--domain <domain>` | Filter output to one domain (alternative to positional arg) |
 | `--format <format>` | Output format: `markdown` (default) or `json`               |
 
@@ -701,7 +715,9 @@ Runs five sequential checks and reports `[OK]` / `[FAIL]` / `[WARN]` for each. E
 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.
+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: a stale deployed snapshot, an unsatisfied `readinessContract`, or a malformed declaration.
+
+The roster is built from the platform catalog, not from your own declarations, so a System you have **not** adopted still gets a row. A System you declared locally that is missing from the deployed snapshot is treated as drift and renders `[FAIL]`, not `[WARN]`. If the API cannot be reached, the roster renders a single `[WARN]` line and leaves Checks 1-4 with their own results. `--verbose` prints each row's issue codes and messages.
 
 **Flags:**
 
@@ -720,25 +736,31 @@ 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
+[OK]   Systems: sales.lead-gen/api: ready
+[OK]   Systems: sales.crm/api: ready
+[OK]   Systems: sales.lead-gen/crm-handoff: ready
+[WARN] Systems: content/api: not adopted
 
 All checks passed. Your Elevasis project is correctly configured.
 ```
 
+A `[WARN]` roster row never changes the exit code. `doctor` still exits `0` with an unadopted System in the list.
+
 **Implementation:** `packages/sdk/src/cli/commands/doctor.ts`
 
+**Related:** [Common Errors -- System Readiness Errors](troubleshooting.mdx#system-readiness-errors-503) for what a `503` refusal from one of these Systems looks like at the terminal and how to clear it.
+
 ---
 
 ## Global Flags
 
 These flags are accepted by all commands:
 
-| Flag                | Description                                                                                                                      |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| 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`                                                                             |
+| `--json`          | Output raw JSON (available on most commands)                                                                                     |
+| `--prod`          | Target production, overriding `NODE_ENV=development`                                                                             |
 
 **API base URL resolution:**
 

package/reference/sdk/deployment/index.mdx

@@ -82,13 +82,14 @@ Each deploy creates a new deployment record. The previous active deployment is a
 
 The CLI validates your resources before bundling. Validation uses the same `ResourceRegistry` as the platform, so errors caught locally are the same errors that would be caught at deploy time.
 
-**Validation checks:**
+**Validation checks that abort the deploy:**
 
 - Duplicate `resourceId` within your organization
 - Invalid model configuration (temperature and token bounds out of range)
 - `ExecutionInterface` form fields not matching `inputSchema`
-- Broken workflow step chains (`next` referencing a step that does not exist)
 - Relationship declarations referencing resources that do not exist
+- Structural failures in your `organizationModel`
+- A System with API-backed resources but no `apiInterface` declaration
 
 **Validation failure output:**
 
@@ -100,6 +101,18 @@ The CLI validates your resources before bundling. Validation uses the same `Reso
   Deploy aborted.
 ```
 
+Every issue is reported in one run. Governance and System Interface readiness failures no longer stop at the first problem, so thirty issues cost one deploy round trip rather than thirty.
+
+**Checks that warn without aborting:**
+
+Workflow-graph problems -- a `next` target that does not exist, an `entryPoint` that names no step, a cycle, or a step unreachable from the entry point -- are reported as warnings so an existing project carrying a latent invalid graph is not blocked on its next deploy. **They still throw at execution**, when the workflow is constructed. Treat a graph warning as a defect with a deadline, not as advisory.
+
+The platform runs its own checks on the server after upload and reports these as warnings too: the `apiInterface` conformance check, agent grammar and token-floor validation, and a cross-check of every declared `IntegrationDefinition.credentialName` against the credentials your organization actually holds. A missing credential is a warning at deploy and a `credentials_missing` failure at execution, so create it before the resource runs. Only credential names are checked; values never leave the command center.
+
+**Downgrading checks temporarily:**
+
+`ELEVASIS_RESOURCE_VALIDATOR=warn-only` downgrades resource governance, contract-ref resolution, System Interface readiness, and the agent grammar and cheap-assertion checks to warnings. Every downgraded check still runs and still prints its issue; it never bypasses the structural schema parse or the conformance gate.
+
 Run `elevasis-sdk check` at any time to validate without deploying.
 
 ---
@@ -121,13 +134,16 @@ The `ElevasConfig` type is exported from `@elevasis/sdk`. You can leave the conf
 
 ## Environment Variables
 
-| Variable                | Required | Description                                                                 |
-| ----------------------- | -------- | --------------------------------------------------------------------------- |
-| `ELEVASIS_PLATFORM_KEY` | Yes      | Your `sk_...` API key. Used for authentication and organization resolution. |
-| `ELEVASIS_API_URL`      | No       | Override the API base URL. Useful for pointing at a staging environment.    |
+| Variable                    | Required | Description                                                                         |
+| --------------------------- | -------- | ----------------------------------------------------------------------------------- |
+| `ELEVASIS_PLATFORM_KEY`     | Yes      | Your `sk_...` API key. Used for authentication and organization resolution.         |
+| `ELEVASIS_API_URL`          | No       | Override the API base URL. Useful for pointing at a staging environment.            |
+| `ELEVASIS_PLATFORM_KEY_DEV` | No       | Key used instead when the request targets a local API. Falls back to the key above. |
 
 The CLI also accepts a `--api-url` flag on every command, which takes priority over `ELEVASIS_API_URL`.
 
+**Which key a request uses is derived from the URL it is sent to**, not from `--prod` or `NODE_ENV` read separately. Both the authentication step and the bundle upload go through the same resolver, so pointing `--api-url` at production while `NODE_ENV=development` is set can no longer authenticate with one key and upload with the other.
+
 **API URL resolution order:**
 
 1. `--api-url` flag (highest priority)
@@ -289,3 +305,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 the full platform service adapter catalog
+- [Common Errors](../troubleshooting.mdx#deploy-errors-elevasis-sdk-deploy) - Deploy failure catalog, warning meanings, and System readiness refusals

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

@@ -23,4 +23,4 @@ Platform adapters are singletons — import them directly, no credential require
 | Execution | `execution` | `trigger`, `triggerAsync` | Execution — trigger other workflows or agents within the same organization. |
 | Email | `email` | `send` | Email — send platform emails (from notifications@elevasis.io) to organization members. |
 | Artifacts | `artifacts` | `listArtifacts`, `createArtifact`, `getActive` | Artifacts — org-scoped governing-document store, keyed by owner and kind, for acquisition's audits, proposals, and ICP docs. |
-| Content | `content` | `createItem`, `getItem`, `listItems`, `updateItem`, `addItemSourceAsset`, `removeItemSourceAsset`, `reorderItemSourceAssets`, `updateItemSourceAsset`, `createAttempt`, `listAttempts`, `updateAttempt`, `createSourceAsset`, `getSourceAsset`, `listSourceAssets`, `updateSourceAsset`, `getDistribution`, `listDistributions`, `createDistribution`, `updateDistribution` | Content — create, read, and update content_items/content_item_attempts/content_distributions/content_source_assets rows for the content pipeline. |
+| Content | `content` | `createItem`, `getItem`, `listItems`, `updateItem`, `addItemSourceAsset`, `removeItemSourceAsset`, `reorderItemSourceAssets`, `updateItemSourceAsset`, `createAttempt`, `listAttempts`, `updateAttempt`, `createSourceAsset`, `getSourceAsset`, `listSourceAssets`, `updateSourceAsset`, `getDistribution`, `listDistributions`, `createDistribution`, `updateDistribution`, `appendDistributionMetrics`, `listDistributionMetrics` | Content — create, read, and update content_items/content_item_attempts/content_distributions/content_source_assets rows for the content pipeline. |

package/reference/sdk/troubleshooting.mdx

@@ -38,6 +38,42 @@ This is the static SDK-level error catalog. Check `.claude/memory/errors/` first
 
 ---
 
+## System Readiness Errors (503)
+
+### API request refused (503): `<system>`/`<interface>` is not ready
+
+**Message:** starts with `API request refused (503)` and continues `This IS the API rejecting the request -- it is not a gateway hiccup, and re-running it will not help.`
+
+**Cause:** The route you called is gated on a System Interface, and your organization's deployed Organization Model has not satisfied it. This is the API deliberately refusing, not a transport fault -- retrying will not help.
+
+**Fix:** Read the `Issues:` block in the message. Those entries are the API's own explanation and name the specific missing thing. The guidance line above them tells you the general shape of the fix:
+
+- **The System has not been adopted** -- declare it in `core/config/organization-model/systems.ts` with an `apiInterface` block, then deploy. Omitting the block entirely is the supported opt-out; an empty `apiInterface.resourceIds` array is not and will throw.
+- **The interface is declared but disabled** -- set its lifecycle back to active and redeploy.
+- **The `readinessContract` is unsatisfied** -- the issues name the missing `requiredObjects` or `requiredCatalogs` refs. Add them and redeploy.
+- **A cross-System handoff is not ready** -- check the counterpart System as well as the one named.
+- **The deployed snapshot is missing or stale** -- run `elevasis-sdk deploy`. The message already carries this instruction.
+- **The stored snapshot could not be read** -- deploy again first. No field of your declaration is known to be wrong.
+
+Then run `elevasis-sdk doctor` to see what else is not ready. Its Systems roster checks every platform-cataloged System, including ones you have not adopted.
+
+### This CLI does not recognize readiness code `{CODE}`
+
+**Cause:** The API returned a readiness family your installed `@elevasis/sdk` predates. Tenants run a published SDK that lags the deployed API, so this is expected after a platform release and not a defect.
+
+**Fix:**
+
+1. Read the `Issues:` block -- it is family-independent and remains the authoritative part of the message
+2. Run `pnpm update @elevasis/sdk` and re-run the command for the full guidance
+
+### 503 with "work may still be running server-side"
+
+**Cause:** This is the gateway message, not the readiness message. It means a proxy or load balancer returned the `503` with no readiness body -- a genuine transport fault.
+
+**Fix:** Retry. Unlike a readiness refusal, this class is transient and the request may have reached the API.
+
+---
+
 ## Validation Errors (elevasis-sdk check)
 
 ### Duplicate resource ID
@@ -64,6 +100,41 @@ This is the static SDK-level error catalog. Check `.claude/memory/errors/` first
 
 ---
 
+## Deploy Errors (elevasis-sdk deploy)
+
+### ORGANIZATION_MODEL_MISSING (400)
+
+**Cause:** The deploy carried no organization model, so the platform had nothing to persist as a snapshot.
+
+**Fix:** Export an `organizationModel` from your deployment spec and deploy again. This is a hard failure by design -- a deploy without a model used to report success, write no snapshot, and then refuse every subsequent API request with a readiness `503`.
+
+### `sdkVersion` is required (400)
+
+**Cause:** The multipart `metadata` part failed schema validation before the deploy pipeline started. `sdkVersion` is the only required field.
+
+**Fix:** Deploy through `elevasis-sdk deploy`, which always sends it. A hand-rolled `POST /api/external/deploy` must include it.
+
+### Deploy succeeded but warnings were printed
+
+Deploy warnings never block the deploy. Each one names something that will fail later if left alone:
+
+- **Workflow graph warnings** -- a dangling `next` target, a missing `entryPoint`, a cycle, or a step unreachable from the entry point. These are warnings at deploy so an existing project carrying a latent invalid graph is not blocked, but the same checks **throw at execution** when the workflow is constructed. Fix them before the workflow next runs.
+- **Missing credential** -- an `IntegrationDefinition.credentialName` you declared has no matching credential in your organization. Create it in the command center; otherwise the first execution fails with a `credentials_missing` tooling error. Only credential names are checked and logged, never values.
+- **Missing `apiInterface` declaration** -- a System with API-backed resources has no `apiInterface` block. Run `elevasis-sdk om:scaffold:fill` for the affected system path.
+- **Unresolvable contract refs** -- contract refs are declared but no `contractRegistry` is exported from your entry.
+
+### Validation reported only one error, but there are more
+
+Governance and System Interface readiness failures now report **every** issue in one deploy, not just the first. If you see a single issue, that is the whole list. Set `ELEVASIS_RESOURCE_VALIDATOR=warn-only` to downgrade governance, contract-ref resolution, readiness, and the agent grammar checks to warnings so a deploy can proceed while you work through them -- it never bypasses the structural schema parse or the OM conformance gate.
+
+### The deploy authenticated but the upload was rejected
+
+**Cause:** Historically the auth step and the upload step resolved the API key two different ways, so pointing `--api-url` at production with `NODE_ENV=development` set authenticated with one key and uploaded with the other.
+
+**Fix:** Update `@elevasis/sdk`. Both steps now derive the key from the URL the request is actually sent to. If you are pinning `NODE_ENV=development` and targeting production, set `ELEVASIS_PLATFORM_KEY` to the production key and use `--prod` or `--api-url`.
+
+---
+
 ## Schema Validation Errors
 
 ### Schema validation failed (input)
@@ -219,4 +290,4 @@ Status values: `Resolved` (fixed this session), `Recurring` (seen 2+ times), `Pr
 
 ---
 
-**Last Updated:** 2026-02-26
+**Last Updated:** 2026-08-20