feat(docs): document Goal Runs API

content/guides/changelog.mdx

@@ -5,6 +5,42 @@ description: Track CALL-E Developer API and SDK product updates.
 
 Product updates for the CALL-E Developer API and server SDKs.
 
+## July 22, 2026
+
+### Phone-only Goal Run requests in API 0.6
+
+Create Goal Run requests now use a top-level `phone` plus `variables`. The `target` wrapper and per-Run `region`, `locale`, and `display_name` fields have been removed. Voice region and callee locale are fixed by the published Goal; recipient names needed by the conversation belong in the Goal's input schema and are supplied through `variables`.
+
+The TypeScript and Python SDK source candidates now implement the matching
+`client.goals` surface at version `0.6.0`, including Goal discovery, Run
+creation, Run reads, and result-or-error polling. Existing Calls and Webhooks
+surfaces remain compatible; registry packages stay on their current stable
+versions until the 0.6.0 release is published.
+
+### Simplified Goal Runs API 0.5
+
+1. Useful Goal metadata: Goal list and get responses now include the current published `title` and `description` alongside the input and result schemas.
+
+2. Smaller response: Goal and Goal Run responses expose RunSpec ids and versions without content fingerprints.
+
+3. One result contract: a Goal Run returns the parsed object directly in `result`, or one unified `error` when execution or result processing fails. When both are null, clients continue polling.
+
+4. Goal discovery: `GET /v1/goals` lists the authenticated owner's active, listed, published Goal interfaces with opaque cursor pagination. The API 0.5 SDK design adds `client.goals.list(...)` in both TypeScript and Python while keeping stable 0.2 packages Calls-only until a matching SDK minor is released.
+
+## July 21, 2026
+
+### Goal Runs API preview
+
+1. Published Goal interface: Read the current normalized input schema, result schema, and RunSpec identity with `GET /v1/goals/{goal_id}`.
+
+2. Goal Run creation: Create one singleton Run with `POST /v1/goals/{goal_id}/runs`. Requests supply one target, scalar variables, and a required business-stable `Idempotency-Key`; they cannot replace the published schemas or choose a RunSpec version. Initial acceptance and exact replay both return `201`.
+
+3. Result polling: Read execution and schema-bound results with `GET /v1/goals/{goal_id}/runs/{goal_run_id}`. The Goal Run preserves the exact RunSpec version pinned when CALL-E accepted it.
+
+4. SDK transition: The Goal Runs guide defines TypeScript and Python parity on `client.goals`, with `get`, `run`, get-Run, wait, and run-and-wait helpers using each language's naming convention. Stable 0.2 SDK packages continue to support the one-shot Calls API until matching next-minor packages are released.
+
+See [Goal Runs](/goal-runs) for request, polling, version-pinning, and SDK examples.
+
 ## June 8, 2026
 
 ### What's New: Developer API and server SDKs

content/guides/errors.mdx

@@ -3,7 +3,7 @@ title: Errors
 description: Handle stable API errors and recovery paths.
 ---
 
-CALL-E returns stable error envelopes for call task API failures.
+CALL-E returns stable error envelopes for Developer API request failures.
 
 ## Error envelope
 
@@ -37,6 +37,11 @@ SDK methods raise typed SDK errors while preserving the stable API error code an
 - `result_schema_invalid`
 - `recipient_result_schema_invalid`
 - `idempotency_conflict`
+- `goal_not_published`
+- `goal_not_executable`
+- `goal_not_ready`
+- `schema_override_not_allowed`
+- `variables_invalid`
 - `provider_unavailable`
 - `internal_error`
 - `not_found`
@@ -67,8 +72,18 @@ See [Authentication](/authentication) for API key setup, server-only usage, and
 
 `idempotency_conflict` means the same idempotency key was reused with a different request body. Reuse keys only for the same external workflow operation.
 
+`not_found` means a call, Goal, or Goal Run does not exist or is not visible to the current API key. Owner mismatch and hidden Goals use the same code.
+
+`goal_not_published` means an active Goal has no published RunSpec. `goal_not_executable` means the Goal is draft, paused, or retired. Existing Goal Run ids remain readable after a lifecycle change.
+
+`goal_not_ready` means the exact published RunSpec or provider contract does not currently pass the execution gate.
+
+`schema_override_not_allowed` means the Goal Run request attempted to supply a task, RunSpec selector, schema, materialization setting, or provider configuration owned by the published Goal.
+
+`variables_invalid` means the scalar variables do not satisfy the input schema of the RunSpec pinned by the Goal Run.
+
 `call_not_ready` means the call task has not reached a terminal state.
 
-`provider_unavailable` and `internal_error` are retryable only when the workflow can safely tolerate retry.
+`provider_unavailable` applies only before durable Goal Run acceptance. After acceptance, dispatch, call, or result-processing failures are reported in the existing Goal Run resource's top-level `error` field. Retry transport failures only when the workflow can preserve the same idempotency key and request.
 
-`not_found` means the call task id does not exist or is not visible to the current API key.
+`internal_error` is retryable only when the workflow can safely tolerate retry.