@sanity/workflow-cli 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,150 @@
 # @sanity/workflow-cli
 
+## 0.33.0
+
+### Minor Changes
+
+- 225e0fb: **BREAKING:** Workflows App SDK and Studio integrations now require `@sanity/sdk` 3.1 or later in the 3.x line, and `@sanity/workflow-sdk` requires the matching `@sanity/sdk-react` 3.1 line when its React entry is used. The previous SDK 2 peer contract is no longer supported. The exported `WorkflowClient`, `TelemetryIntakeClient`, `ProjectUserProfileClient`, and `StudioUserClient` request contracts now pass their target in `url`; the previous `uri` request target is no longer used. The engine's effective client config also accepts the broader `{type: string, id: string}` resource descriptors returned by Sanity client 8.
+
+  Before upgrading Workflows, upgrade `@sanity/sdk` and `@sanity/sdk-react` together to 3.1 or later. Applications that stay on SDK 2 must stay on an earlier Workflows release. If you implement any of the request contracts named above, update it to read the request target from `url` instead of `uri`; otherwise its request-backed reads will fail. Existing `WorkflowClient.config()` implementations need no change when their resource descriptor already has string `type` and `id` fields. No separate CLI upgrade action is required; its definition-sharing and telemetry requests adopt `url` internally.
+
+  Before installing, override SDK 3's `@sanity/mutate` dependency to `0.18.2` in your application's root package-manager configuration, reinstall, and commit the updated lockfile. SDK 3.1.0 allows Mutate 0.18.1, which can leave document reads pending with client 8. For npm, set `overrides["@sanity/sdk"]["@sanity/mutate"]` to `"0.18.2"` in `package.json`. For pnpm, set `overrides['@sanity/sdk@3>@sanity/mutate']` to `0.18.2` in `pnpm-workspace.yaml`. Keep the override until your SDK release requires Mutate 0.18.2 or later. Complete examples and verification steps are in the Installation section of the published `@sanity/workflow-sdk` README.
+
+  Malformed project-member responses now report an inaccessible directory and can recover on a later lookup, instead of being cached as a missing user. No additional upgrade action is required for this correction.
+
+  **Docs impact:** Update the App SDK and Studio integration installation guidance, package compatibility references, and examples to require Sanity App SDK 3.1 and the consumer Mutate override described in the published `@sanity/workflow-sdk` README; update the client API references for `request({url})`, effective resource descriptors, and directory-response failures.
+
+- ba031fe: **Experimental, and not ready for production use in this release.** Both commands are available so you can try the generated runtime and give feedback; their flags and their output may still change. What you would hit today:
+  - The start watcher runs on every create and update of a subject type, not only on writes that can actually start a workflow, so it wakes for documents that already have an instance or match no definition. The heartbeat is scheduled every minute and evaluates every in-flight instance in the tag when it runs; how often the platform runs it is a plan limit.
+  - `sanity-workflows deploy` does not check the generated tree, so drift between your definitions and the tree on disk is caught only by `blueprint generate --check` in CI.
+  - Definitions and functions deploy in two steps, definitions first, until the Blueprints service registers the `sanity.workflow` resource.
+  - A generated file cannot be taken over: editing one is drift, and the next generation rewrites it.
+  - A retry policy is not checked against its function's timeout at generation, so an effect can be configured to retry for longer than its function may run.
+
+  All of these are tracked, and the next release is the bar for using this in production.
+
+  `sanity-workflows blueprint generate` generates the Sanity Blueprints runtime your definitions require and writes it next to `sanity.workflow.ts`. It prints the needs analysis first — which effects force a drain function, which `$now` condition forces a scheduled heartbeat, which autonomous definition forces a start watcher, and the explicit "no functions needed" answer for a purely interactive workflow — then writes `workflows.blueprint.ts`, one function module and manifest per derived need, the effect-handler registry, and one handler stub per declared effect name. Handler stubs are yours: they are scaffolded once and never overwritten. Your own `sanity.blueprint.ts` receives the `workflowResources` import and spread once. The command deletes nothing; a handler for an effect you removed, a scaffold blocked by a path differing only in case, and a blueprint it could not wire are reported as warnings for you to resolve. The generated tree is one artifact for the whole config, so the command always covers every deployment.
+
+  `sanity-workflows blueprint generate --check` is the CI drift gate. It renders the same runtime in memory, compares it with the files on disk, writes nothing, and exits zero when they match. Otherwise it exits 1 and lists every file with its reason — `missing`, `differs`, an orphaned handler, or a blueprint that is not wired — so a CI log says what to fix without anyone reading source. A declared effect with no handler file on disk reports as `missing`, which is the handler-coverage check.
+
+  **No upgrade action required.** Both commands are new and nothing else changes. To use them, your `sanity.workflow.ts` must export each deployment under its own `name`, and that export must be the deployment object itself — `export const production = {name: 'production', …} satisfies WorkflowDeploymentInput`, then `export default defineWorkflowConfig({deployments: [production]})` — because every generated module imports its deployment from `./sanity.workflow` by that name; a config that only default-exports fails the command with the export to add rather than writing a tree that cannot compile. The command checks the name only, so make sure each export is the deployment the config lists: a typecheck of the generated modules catches a wrong export only where a generated function uses it, and a deployment that needs no functions emits none. Your `sanity.workflow.ts` must also be importable inside a deployed function, because every generated module imports it and each function bundles it: reading an absent variable there yields `undefined`, but a config that throws when a variable is missing, or requires one to build the deployment, fails every deployed function on init. Keep the deployment's resource coordinates literal in that file and read secrets inside your handlers. Deploy your definitions with `sanity-workflows deploy` before `npx sanity blueprints deploy`, because the generated blueprint carries the definitions entry commented out until the Blueprints service accepts the `sanity.workflow` resource type, and a function that starts or advances an instance resolves its definition from the Content Lake. A generated heartbeat is a scheduled function, which the platform only accepts on an organization-scoped stack, and how often it may run is a plan limit. Also install `@sanity/blueprints`, `@sanity/functions`, and `@sanity/workflow-blueprint` in your project: each generated function's manifest copies the specifications your project declares for `@sanity/functions`, `@sanity/workflow-blueprint`, and `@sanity/workflow-engine`, and a package you declare nowhere fails the command instead of being stamped with a guessed range. `typescript` is now a dependency of the CLI, because parsing `sanity.blueprint.ts` to insert the wiring uses the TypeScript compiler.
+
+  **Docs impact:** Rewrite the cookbook chapter on running workflows on a server so it drives the runtime through these two commands rather than describing hand-written functions, and cover the CI drift check there. Update the CLI command reference with both commands, and the Blueprints concept page where it explains who writes the generated tree.
+
+### Patch Changes
+
+- 393ac71: CLI and MCP telemetry now includes `context.surface` (`cli` or `mcp`) and
+  execution mode in each event's `context.environment`. Dashboards can include
+  shell and engine activity while distinguishing it from SDK events marked
+  `sdk`. Existing command trace context is preserved.
+
+  All three surfaces report `production` for `NODE_ENV=production`, and
+  `development` for `development` or `test`. Unset, empty, and unrecognized values
+  default to `production` for CLI and MCP execution mode, and `development` for
+  SDK build mode. SDK environment classification is unchanged. When comparing
+  activity across surfaces, group or filter by surface alongside environment.
+  Environment does not identify a production dataset or deployment; API host,
+  dataset name, and workflow tag do not set it.
+
+  **No upgrade action required.** Existing telemetry consent and opt-out
+  settings still apply. Historical events are unchanged.
+
+  **Docs impact:** Update CLI, MCP, and SDK telemetry guidance to explain surface
+  context, build versus execution mode, the explicit defaults, and how to
+  interpret environment when comparing activity across surfaces.
+
+- 8874c50: **BREAKING:** A `subject`, `doc.ref`, or `doc.refs` field marked `required: true`
+  now requires its selected documents to remain readable after initialization.
+  Previously, the flag checked only that an initial value was supplied. Missing
+  required targets now produce a fault and prevent normal actions, triggered
+  actions, and transitions from advancing, even without an activity requirement
+  reading those targets. Abort and direct edits to editable fields remain
+  available. Optional references fault only when an unmet runtime condition needs
+  their content; completed workflows remain completed.
+
+  `StuckCause` adds `document-missing`. Update exhaustive handlers before upgrading,
+  or their typechecks fail and renderers have no matching branch. Evaluation
+  identifies the affected field and reference in `missingDocuments`, with its title
+  and completed availability evidence; `blockingMissingDocuments` selects the
+  references that prevent progress. The engine checks draft, published, and release
+  representations before distinguishing deletion from inaccessible content or
+  content outside the workflow perspective. Studio, CLI, and MCP use that same
+  result. Failed availability checks report unreadable content and log the cause;
+  optional references still permit unrelated actions. Incomplete reads do not
+  claim deletion, and an existing task fault keeps
+  its recovery controls. The fault clears when the required content becomes
+  readable; this release adds no undo-delete operation and does not automatically
+  abort workflows.
+
+  Upgrade every Workflows runtime sharing affected data, including Studio, CLI,
+  MCP servers, and deployed Functions, before relying on continued required-target
+  availability. Then set the deployment's reviewed `expectedMinReaderModel` to
+  `10` before deploying definitions with required content references. Writers stamp
+  model 10; this feature requires reader model 10, while documents without it keep
+  the floor required by their other features, normally 4, 8, or 9. Existing
+  instances remain readable without a backfill and adopt the rule under upgraded
+  engines. Their stored floor rises on the next full write, so an older runtime
+  can still advance an unstamped existing instance until the fleet is upgraded.
+  See `packages/workflow-engine/DATAMODEL.md` for the complete rollout contract.
+
+  The rendered CLI `show` command evaluates running instances. If evaluation fails,
+  it warns and displays stored state; terminal instances and `show --json` retain
+  their stored-state behavior.
+
+  **Docs impact:** Update field requiredness and initialization guidance, required
+  reference repair examples, the model-10 readers-first rollout, the diagnostics
+  reference for `StuckCause` and `MissingDocument`, CLI `show` and `diagnose`, MCP
+  workflow-state guidance, and the Workflows tool and document-view guides for
+  loading, deletion, permissions, and perspectives.
+
+- 3b42bdc: The Workflows CLI command-trace now sets the oclif command id as trace context (`groupOrCommand`) when the built-in telemetry shell starts, so telemetry reporting can break invocations down by command the same way it can for other Sanity CLI commands. The id remains in the log payload as `command` for config-provided telemetry loggers.
+
+  **No upgrade action required.** Existing CLI installs begin emitting the queryable context after upgrading; historical rows are unchanged.
+
+  **Docs impact:** None — internal telemetry envelope shape for an existing event; no public API or user-facing CLI behavior change.
+
+- 7eb9eca: Correct the API references for field initialization and edits, start requirements,
+  transitions, reference IDs, effect handling, reactive state, member controls,
+  Studio mappings, test helpers, and GROQ condition outcomes. The references state
+  caller constraints and defaults that were missing or incorrect. Package setup
+  guidance identifies the public npm packages and supported deployment command;
+  the MCP validation description distinguishes validation from deployment checks.
+  Runtime behavior and API signatures are unchanged.
+
+  **No upgrade action required.**
+
+  **Docs impact:** After release and reference sync, reconcile the modeling,
+  runtime, reactive UI, Studio, testing, deployment, MCP, and evaluation-insight
+  guides and references with the corrected contracts. Fix affected examples and
+  replace redundant API inventories with verified symbol links while preserving
+  useful teaching and the CLI/MCP reference material not exposed by TypeDoc.
+
+- 2cef086: Internal maintenance consolidates engine action/edit handling and Studio document
+  and workflow title sorting. Action and field-edit calls retain their inputs and
+  results, and document and workflow titles retain their ordering. Action
+  availability, telemetry, and persisted document formats are unchanged.
+
+  **No upgrade action required.**
+
+  **Docs impact: None** because public APIs, configuration, and workflow behavior
+  are unchanged.
+
+- Updated dependencies [8874c50]
+- Updated dependencies [b3b2797]
+- Updated dependencies [393ac71]
+- Updated dependencies [8874c50]
+- Updated dependencies [ba031fe]
+- Updated dependencies [0555271]
+- Updated dependencies [b3b2797]
+- Updated dependencies [225e0fb]
+- Updated dependencies [b7510cc]
+- Updated dependencies [7eb9eca]
+- Updated dependencies [2cef086]
+- Updated dependencies [232f811]
+- Updated dependencies [ba031fe]
+  - @sanity/workflow-blueprint@0.33.0
+  - @sanity/workflow-engine@0.33.0
+
 ## 0.32.0
 
 ### Minor Changes

package/README.md

@@ -3,23 +3,31 @@
 Command-line tool for deploying, inspecting, and administering Sanity workflow
 definitions and instances.
 
-> [!WARNING]
-> Early access, restricted. The commands below talk to a real Sanity dataset,
-> configured by a `sanity.workflow.ts` file and authenticated with
-> `sanity login`.
+The package is in early access and is publicly available on npm. Commands that
+access Sanity use the resources in `sanity.workflow.ts` and authenticate with a
+login session or an API token. `deploy --check` validates definitions offline.
 
 ## Run
 
-```bash
-pnpm --filter @sanity/workflow-cli dev <command> [...args]
+Use Node.js 20.12 or later. Install the CLI and its engine peer from the same
+Workflows release in your project:
 
-# Examples:
-pnpm --filter @sanity/workflow-cli dev --help
-pnpm --filter @sanity/workflow-cli dev deploy --dry-run
-pnpm --filter @sanity/workflow-cli dev list --include-completed
-pnpm --filter @sanity/workflow-cli dev show wf-instance.abc123
+```sh
+npm install --save-dev @sanity/workflow-cli @sanity/workflow-engine
+npx @sanity/workflow-cli --help
 ```
 
+After authentication and [configuration](#configuration), run commands through
+the project-local package:
+
+```sh
+npx @sanity/workflow-cli deploy --dry-run
+npx @sanity/workflow-cli list --include-completed
+npx @sanity/workflow-cli show INSTANCE_ID
+```
+
+Replace `INSTANCE_ID` with the workflow instance ID returned by `list`.
+
 The package is an [oclif](https://oclif.io) plugin: every command's canonical
 id nests under the `workflows` topic
 (`sanity-workflows workflows deploy`), so mounting the package into
@@ -32,9 +40,9 @@ binary's stable surface — its production and development entrypoints
 resolves the command. Those short forms are **not** registered as oclif aliases,
 so a host mount does not pollute the host root.
 
-Authenticate once with `sanity login` (the CLI reads that session token); for
-CI, set `SANITY_AUTH_TOKEN` instead. Then create a `sanity.workflow.ts` in the
-directory you run from — see [Configuration](#configuration).
+Authenticate with `npx sanity@latest login`; the CLI reads that session token.
+For CI, set `SANITY_AUTH_TOKEN` instead. Create a `sanity.workflow.ts` in the
+directory you run from, as described in [Configuration](#configuration).
 
 The token must span **every resource the workflow references**, not just the
 workflow resource. Runtime commands build one client from the deployment
@@ -52,28 +60,29 @@ the directory you run from. It exports a config built with
 environment):
 
 ```ts
+import type {WorkflowDeploymentInput} from '@sanity/workflow-engine'
 import {defineWorkflowConfig} from '@sanity/workflow-engine/define'
 
 import {articleReview, urlDraft} from './src/workflows.ts'
 
-export default defineWorkflowConfig({
-  deployments: [
-    {
-      expectedMinReaderModel: 4,
-      name: 'production', // the deployment's unique identity (lowercase letters, digits, dashes)
-      tag: 'prod', // the environment partition the engine's docs are scoped to
-      workflowResource: {type: 'dataset', id: 'acme.workflows'}, // where those docs live
-      resourceAliases: [
-        // binds each `@<handle>:` a definition references to a physical resource
-        // in a DIFFERENT dataset from `workflowResource` (same-resource content
-        // needs no alias — see below)
-        {name: 'content', resource: {type: 'dataset', id: 'acme.content'}},
-        {name: 'assets', resource: {type: 'dataset', id: 'acme.assets'}},
-      ],
-      definitions: [articleReview, urlDraft], // the batch this deployment ships
-    },
+// Export each deployment under its own `name`, then list the exports in the
+// config. `blueprint generate` requires these named exports; nothing else does.
+export const production = {
+  expectedMinReaderModel: 4,
+  name: 'production', // the deployment's unique identity (lowercase letters, digits, dashes)
+  tag: 'prod', // the environment partition the engine's docs are scoped to
+  workflowResource: {type: 'dataset', id: 'acme.workflows'}, // where those docs live
+  resourceAliases: [
+    // binds each `@<handle>:` a definition references to a physical resource
+    // in a DIFFERENT dataset from `workflowResource` (same-resource content
+    // needs no alias — see below)
+    {name: 'content', resource: {type: 'dataset', id: 'acme.content'}},
+    {name: 'assets', resource: {type: 'dataset', id: 'acme.assets'}},
   ],
-})
+  definitions: [articleReview, urlDraft], // the batch this deployment ships
+} satisfies WorkflowDeploymentInput
+
+export default defineWorkflowConfig({deployments: [production]})
 ```
 
 `name` is the deployment's identity: unique across the config and constrained
@@ -82,16 +91,20 @@ repeat, as long as no two deployments share both a `workflowResource` and a
 `tag` — that pair is the storage partition, and the config rejects the
 collision naming both entries.
 
-Pick a deployment with `--deployment <name>`; with a single deployment configured you
-can omit it. `--tag <tag>` also works on single-deployment commands while the
-tag names exactly one deployment — on `deploy` it targets every deployment
-carrying the tag (a tag is an environment group). With several configured, a
-bare interactive run presents a keyboard-driven deployment selector (by name,
-tag alongside) — on `deploy`, `start`, and `definition diff`/`delete`, and on
-the instance-targeted commands (`abort`, `set-stage`, `reset-activity`,
-`fire-action`, `diagnose`) when the config spans several resources. In CI or another
-non-interactive shell, the command fails asking for `--deployment` or `--tag`
-(`deploy` also suggests `--all-tags`) instead of blocking for input.
+For `deploy`, `start`, `definition diff`, and `definition delete`, select a
+deployment with `--deployment <name>`. With one deployment configured, you can
+omit the selector. `--tag <tag>` selects one deployment when the tag is unique;
+on `deploy`, it targets every deployment carrying the tag. With several
+deployments and no selector, these commands prompt for a deployment in an
+interactive terminal. In a non-interactive shell, they fail asking for
+`--deployment` or `--tag`; `deploy` also suggests `--all-tags`.
+
+The instance-targeted commands `abort`, `set-stage`, `reset-activity`,
+`fire-action`, and `diagnose` locate the instance by ID across configured
+resources. They do not prompt for a deployment. Their optional `--deployment`
+and `--tag` flags narrow the resources searched; the operation's tag comes from
+the loaded instance.
+
 `--all-tags` deploys every deployment in the config in one run: a failure in one doesn't
 stop the rest — the run continues, prints a summary of what failed, and exits
 non-zero. The client's project + dataset are derived from the deployment's
@@ -173,6 +186,8 @@ Invoke as `sanity-workflows <command>` (or `sanity workflows <command>` once the
 | `set-stage <instance-id> --to <stage>`          | Move an instance to a stage, skipping declared transitions. The target stage's enter lifecycle still runs.                                                                   |
 | `reset-activity <instance-id> <activity>`       | Re-run a failed activity, or `--skip` it so a gated transition can fire.                                                                                                     |
 | `fire-action <instance-id>`                     | Fire an action on a waiting activity. Omit `--action` to list what can be fired.                                                                                             |
+| `blueprint generate`                            | Write the Sanity Blueprints runtime the definitions require next to `sanity.workflow.ts`.                                                                                    |
+| `blueprint generate --check`                    | Verify that runtime still matches the definitions. Writes nothing; exits non-zero on any difference.                                                                         |
 | `definition list`                               | List deployed definitions.                                                                                                                                                   |
 | `definition show <name>`                        | Show a deployed definition (latest version, or `--version`).                                                                                                                 |
 | `definition diff <name>`                        | Diff the in-code definition against what is deployed.                                                                                                                        |
@@ -180,6 +195,182 @@ Invoke as `sanity-workflows <command>` (or `sanity workflows <command>` once the
 | `nuke --deployment <name>` / `nuke --tag <tag>` | Dev reset: delete every engine-owned document for that tag (instances, definitions, guards). Prints a plan, then asks for confirmation. Content documents are never touched. |
 | `nuke --instance <id>`                          | Dev reset: delete one finished instance and its guards. Refuses in-flight instances (abort first).                                                                           |
 
+## Generating the Blueprints runtime
+
+**Experimental, and not ready for production use in this release.** Both
+commands are available so you can try the generated runtime and give feedback;
+their flags and their output may still change. What you would hit today:
+
+- The start watcher runs on every create and update of a subject type, not only
+  on writes that can actually start a workflow, so it wakes for documents that
+  already have an instance or match no definition. The heartbeat is scheduled
+  every minute and evaluates every in-flight instance in the tag when it runs;
+  how often the platform runs it is the plan limit described below.
+- `sanity-workflows deploy` does not check the generated tree, so drift between
+  your definitions and the tree on disk is caught only by
+  `blueprint generate --check` in CI.
+- Definitions and functions deploy in two steps, definitions first, until the
+  Blueprints service registers the `sanity.workflow` resource.
+- A generated file cannot be taken over: editing one is drift, and the next
+  generation rewrites it.
+- A retry policy is not checked against its function's timeout at generation, so
+  an effect can be configured to retry for longer than its function may run.
+
+All of these are tracked, and the next release is the bar for using this in
+production.
+
+A definition that declares an effect, reads `$now`, or starts autonomously needs
+server-side code: something has to run the effect handlers, sample deadlines, and
+start instances from document writes. `blueprint generate` derives that runtime
+from the definitions and writes it next to `sanity.workflow.ts`, so
+`npx sanity blueprints deploy` has something to deploy. A purely interactive
+workflow needs none of it, and the command says so.
+
+Five prerequisites:
+
+- **Each deployment is exported under its own `name`, and the export is the
+  deployment object itself**, as the [Configuration](#configuration) example
+  does: every generated module imports its deployment from `./sanity.workflow`
+  by that name. The command refuses to write anything until each name is
+  exported, and names the export to add. It checks the name only, so make sure
+  each export is the deployment your config lists. A typecheck of the generated
+  modules catches a wrong export only where a generated function uses it, and a
+  deployment that needs no functions emits none.
+- **`sanity.workflow.ts` is importable inside a deployed function.** Every
+  generated module imports it, and each function bundles it, so the file runs
+  where your shell and your `.env` do not exist. Reading an absent variable
+  there yields `undefined`; what fails is a config that **throws** when a
+  variable is missing, or requires one to build the deployment, because that
+  runs on init before your handler is reached. Keep the deployment's resource
+  coordinates literal in the file and read secrets inside your handlers.
+- **The Blueprints packages the generated modules import are installed**,
+  alongside the CLI and its peers.
+- **Your definitions are deployed before the functions.** The generated
+  `workflows.blueprint.ts` carries the definitions entry commented out, because
+  the Blueprints service does not accept the `sanity.workflow` resource type
+  yet, so `npx sanity blueprints deploy` does not deploy them. Run
+  `npx @sanity/workflow-cli deploy` first: a function that starts or advances an
+  instance resolves its definition from the Content Lake, and finds nothing
+  until that deploy has run.
+- **A generated heartbeat needs an organization-scoped stack.** The heartbeat is
+  a scheduled function, and the platform only accepts one on a stack in
+  organization scope. A project-scoped stack refuses it, and with it the whole
+  deploy. See
+  [Promote a stack to organization scope](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope).
+  How often it may run is a plan limit rather than something the generator
+  chooses — see [the schedule](#the-generated-heartbeats-schedule) below.
+
+```sh
+npm install --save-dev @sanity/blueprints @sanity/functions @sanity/workflow-blueprint
+npx @sanity/workflow-cli blueprint generate
+npx @sanity/workflow-cli deploy
+npx sanity blueprints deploy
+```
+
+Each generated function's `package.json` copies the specifications your project
+declares for `@sanity/functions`, `@sanity/workflow-blueprint`, and
+`@sanity/workflow-engine`. A package you declare nowhere fails the command
+rather than being stamped with a guessed range.
+
+The command prints what the definitions need and why, then every file it wrote:
+
+```
+$ npx @sanity/workflow-cli blueprint generate
+Runtime needs:
+
+▸ prod (prod)
+  hosting: this deployment declares function, and each level below inherits it
+    → function workflow(s): article-review
+    → function effect(s): notify-reviewer
+  effects: 1 declared — notify-reviewer
+    → drain function wf-prod-drain-effects runs notify-reviewer
+      triggered by instance writes matching _type == "sanity.workflow.instance" && tag == "prod" && count(pendingEffects[!defined(claim)]) > 0
+  clock: samples $now deadlines; sweeps stale effect claims left by a dead drain
+      article-review · working · action-when · $fields.subject.embargoAt <= $now
+    → scheduled function wf-prod-heartbeat on * * * * *
+      a scheduled function runs at most as often as your organization's plan allows — every minute on Enterprise, hourly on Growth, daily on Free (https://www.sanity.io/docs/functions/functions-introduction) — and a schedule below that threshold is deployed and never invoked
+  autonomous starts: 1 definition(s) — article-review
+    → start watcher wf-prod-start-workflows on acme.workflows matching _type in ["article"]
+
+Generated tree:
+  created    workflows.blueprint.ts
+  created    functions/wf-prod-drain-effects/index.ts
+  created    functions/wf-prod-drain-effects/package.json
+  created    functions/wf-prod-heartbeat/index.ts
+  created    functions/wf-prod-heartbeat/package.json
+  created    functions/wf-prod-start-workflows/index.ts
+  created    functions/wf-prod-start-workflows/package.json
+  created    effect-handlers/all.ts
+  created    effect-handlers/notify-reviewer.ts  yours now — implement the effect
+  created    sanity.blueprint.ts  the workflow resources spread
+```
+
+Fill in each `effect-handlers/<effect name>.ts`: they are yours, scaffolded once
+and never overwritten. Everything marked `created`, `updated`, or `unchanged`
+under `workflows.blueprint.ts`, `functions/`, and `effect-handlers/all.ts` is
+regenerated on every run, so edits there do not survive. Your own
+`sanity.blueprint.ts` receives the `workflowResources` import and spread once;
+after that the command leaves it alone. The command never deletes a file. A
+handler for an effect you removed, a scaffold blocked by a path that differs
+only in case, and a blueprint it could not wire are reported for you to resolve.
+
+The command covers every deployment in the config, because the emitted
+`workflows.blueprint.ts` declares them all.
+
+### Where each workflow runs
+
+The report opens with the hosting each `runtime` block resolved to, after every
+level has inherited from the one above it. It matters because a name listed
+under `durableFunction` or `selfHosted` has no emitted function to point at:
+
+- `function` — the drain, heartbeat, and start watcher above.
+- `durableFunction` — nothing is emitted yet. The rest of the deployment emits
+  normally around it.
+- `selfHosted` — nothing is emitted, and the report ends with what your own
+  process must do instead: which deadlines to tick, which effects to drain,
+  which parents to re-evaluate when a child settles, and which autonomous
+  definitions to start. A self-hosted deadline is never a reason to emit a
+  heartbeat, so it is listed there and not under `clock`; an emitted heartbeat
+  ticks every in-flight instance in the tag, whatever hosts each workflow.
+
+### The generated heartbeat's schedule
+
+The heartbeat is emitted on `* * * * *`, one run a minute, and how often the
+platform will actually run it is a plan limit rather than something the
+generator can choose: Sanity documents the threshold as
+[Free daily, Growth hourly, Enterprise minutely](https://www.sanity.io/docs/functions/functions-introduction).
+Below Enterprise the platform accepts the scheduled function and does not run
+it, so a workflow whose deadlines depend on the heartbeat does not advance and
+nothing reports an error. Check your plan's cadence before relying on a `$now`
+deadline in a deployed workflow.
+
+### Checking for drift in CI
+
+`blueprint generate --check` renders the same runtime in memory and compares it
+with the files on disk. It writes nothing and exits zero when they match:
+
+```
+$ npx @sanity/workflow-cli blueprint generate --check
+✔ the generated tree matches the definitions
+```
+
+Otherwise it exits `1` and names every file, so the log alone says what to fix:
+
+```
+$ npx @sanity/workflow-cli blueprint generate --check
+✖ The generated tree does not match the definitions (1):
+    differs    effect-handlers/all.ts
+  Run `sanity-workflows blueprint generate` to bring it back in line.
+$ echo $?
+1
+```
+
+A file reports `missing` when nothing is at its path, `differs` when the file
+there has other contents, and a handler for a declared effect reports `missing`
+when you have not written it yet. Add the command to the job that builds your
+blueprint and a definition change can no longer ship without the runtime it
+needs.
+
 ## Telemetry
 
 The CLI collects usage telemetry through Sanity's standard pipeline: a
@@ -193,6 +384,17 @@ is passed — see [Definition sharing](#definition-sharing)),
 and a session that isn't logged in sends nothing. A one-time notice on stderr
 discloses collection on first use.
 
+Each event includes `context.surface: 'cli'` and its process execution mode
+in `context.environment`. `NODE_ENV=production` reports `production`;
+`development` and `test` report `development`. Unset, empty, and unrecognized
+values default to `production` for installed CLI and MCP runs. The SDK reports
+build mode and defaults to `development` instead.
+
+When comparing activity across surfaces, group or filter by `context.surface`
+alongside `context.environment`. Environment does not identify a production
+dataset or deployment; the API host, dataset name, and deployment tag do not
+set it. Existing telemetry consent and opt-out settings still apply.
+
 One extension point: supply your own logger as `telemetry` in
 `sanity.workflow.ts` and the built-in pipeline is not constructed at all —
 every event flows to your implementation unconditionally (CI included), and

package/dist/commands/workflows/blueprint/generate.d.ts

@@ -0,0 +1,9 @@
+import { WorkflowCommand } from '../../../lib/base-command.ts';
+export default class BlueprintGenerate extends WorkflowCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        check: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/workflows/blueprint/generate.js

@@ -0,0 +1,28 @@
+import { Flags } from '@oclif/core';
+import { WorkflowCommand } from "../../../lib/base-command.js";
+import { checkBlueprint, generateBlueprint } from "../../../lib/blueprint-emit.js";
+import { loadWorkflowConfigModule } from "../../../lib/load-config.js";
+export default class BlueprintGenerate extends WorkflowCommand {
+    static description = 'Experimental: generate the Sanity Blueprints runtime the definitions require, next to sanity.workflow.ts. Writes the workflow resources, one function per derived need, the effect-handler registry, and a handler stub per declared effect. Covers every deployment in the config, because the emitted resources module declares them all. These flags and this output may change before the Blueprints backend accepts the sanity.workflow resource.';
+    static examples = [
+        '<%= config.bin %> workflows blueprint generate',
+        '<%= config.bin %> workflows blueprint generate --check',
+    ];
+    static flags = {
+        check: Flags.boolean({
+            description: 'Experimental: verify the tree on disk still matches the definitions; write nothing and exit non-zero on any difference. The CI drift gate.',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(BlueprintGenerate);
+        const root = process.cwd();
+        const { config, configFile, exportedNames } = await loadWorkflowConfigModule(root);
+        const log = (line) => this.log(line);
+        if (flags.check) {
+            checkBlueprint({ root, config, configFile, exportedNames, log });
+            return;
+        }
+        generateBlueprint({ root, config, configFile, exportedNames, log });
+    }
+}

package/dist/commands/workflows/diagnose.d.ts

@@ -1,4 +1,4 @@
-import { type Diagnosis, type DiagnoseInput, type SuggestedRemediation, type WorkflowEvaluation } from '@sanity/workflow-engine';
+import { type Diagnosis, type DiagnoseInput, type MissingDocument, type SuggestedRemediation, type WorkflowEvaluation } from '@sanity/workflow-engine';
 import { WorkflowCommand } from '../../lib/base-command.ts';
 /** The `--json` transitions payload: raw derived state (atom GROQ, negation,
  *  pivotality, solvable requirement) — structure for scripts, never baked
@@ -23,10 +23,12 @@ export declare function rawTransitionProjection(evaluation: WorkflowEvaluation):
  * {@link SuggestedRemediation}s rather than re-deriving them, so the rendered
  * fix block and the `--json` output stay one computation.
  */
-export declare function renderDiagnosis({ diagnosis, input, remediations, explanations, }: {
+export declare function renderDiagnosis({ diagnosis, input, remediations, explanations, allMissingDocuments, }: {
     diagnosis: Diagnosis;
     input: DiagnoseInput;
     remediations: SuggestedRemediation[];
+    /** Full evaluation evidence, including references outside the blocking subset. */
+    allMissingDocuments?: MissingDocument[] | undefined;
     /** Insight summaries per unsatisfied transition name — rendered under the
      *  transition line so "stuck" reads as "stuck until X". */
     explanations?: ReadonlyMap<string, string> | undefined;