@sanity/workflow-cli 0.32.0 → 0.34.0

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,24 +195,320 @@ 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
-per-command trace (`Workflows CLI Command Executed` — the command id, the
-names of declared flags used, never their values, and a success flag) plus
-the engine's adoption events from the operations it drives. Consent is the
-account-wide status managed by `npx sanity telemetry enable|disable|status`;
-CI and trueish `DO_NOT_TRACK` suppress everything (except a deploy that may share
+The CLI collects usage telemetry through Sanity's standard pipeline. Consent
+is the account-wide status managed by `npx sanity telemetry enable|disable|status`.
+CI and trueish `DO_NOT_TRACK` suppress everything except a deploy that may share
 new definitions, which forces that deploy's telemetry unless `--no-share-defs`
-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.
+is passed — see [Definition sharing](#definition-sharing). A session that isn't
+logged in sends nothing. A one-time notice on stderr discloses collection on
+first use.
+
+Payloads never include customer-authored strings: no flag values, argv
+tokens, error text, definition names, stage names, GROQ, or document content.
+The one instance-scoped exception the engine already ships is `instanceId`
+(the instance document `_id`). Effect events also carry the author-chosen
+effect name. Definition sharing sends the definition document to a first-party
+feedback endpoint, not through this pipeline; telemetry only records the
+content-free markers below.
+
+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
 consent, suppression, and destination become its business.
 
+### Session properties
+
+The built-in store attaches these user properties once per invocation (joined
+to events by session id). User identity is not in the payload; the intake
+service resolves the sender from the authenticated session.
+
+| Property          | What it is                                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------------------ |
+| `surface`         | Always `'cli'`.                                                                                  |
+| `machinePlatform` | Node `process.platform` (for example `darwin`, `linux`).                                         |
+| `cpuArchitecture` | Node `process.arch`.                                                                             |
+| `runtime`         | Always `'node'` for this CLI.                                                                    |
+| `runtimeVersion`  | Node `process.version`.                                                                          |
+| `cliVersion`      | The CLI package version, when oclif supplied it.                                                 |
+| `projectId`       | Project id of the first dataset-backed deployment in `sanity.workflow.ts`.                       |
+| `dataset`         | Dataset of that same deployment.                                                                 |
+| `orgId`           | Organization id for that project, when the lookup succeeds before the command flushes. Optional. |
+
+### CLI events
+
+These events are defined by this package.
+
+#### `Workflows CLI Command Executed` (version 1)
+
+One trace per workflows command. The built-in store starts the trace in the
+prerun hook with `groupOrCommand` set to the oclif command id (for example
+`workflows:deploy`, `workflows:definition:list`, `workflows:fire-action`) and
+completes it in the finally hook. A config-supplied logger receives the same
+payload as a log, with no trace. Host commands outside the `workflows` topic
+do not emit.
+
+| Field     | Type       | What is collected                                                                                                                                                       |
+| --------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `command` | `string`   | The oclif command id (`workflows:…`). Never argv free-text.                                                                                                             |
+| `flags`   | `string[]` | Names of **declared** flags present on the invocation, sorted. Long form, `--no-name`, and short chars. Never values, never undeclared tokens, never tokens after `--`. |
+| `success` | `boolean`  | `true` when the command finished without an oclif error.                                                                                                                |
+
+#### `Workflows Definition Shared` (version 1)
+
+One content-free marker per newly created definition version that actually
+reached Sanity's definition-feedback endpoint. Unchanged redeploys, dry runs,
+and `--check` never emit it. The document itself is not in this event.
+
+| Field              | Type       | What is collected                                                                                    |
+| ------------------ | ---------- | ---------------------------------------------------------------------------------------------------- |
+| `contentHash`      | `string`   | Content fingerprint of the donated definition.                                                       |
+| `deployId`         | `string`   | Random run id shared with that invocation's `Workflows Definition Deployed` events.                  |
+| `stageCount`       | `number`   | Declared stages.                                                                                     |
+| `activityCount`    | `number`   | Activities across those stages.                                                                      |
+| `actionCount`      | `number`   | Actions across those activities.                                                                     |
+| `transitionCount`  | `number`   | Declared transitions.                                                                                |
+| `fieldCount`       | `number`   | Declared field entries at workflow, stage, and activity scope.                                       |
+| `activityKinds`    | `string[]` | Distinct effective activity kinds, sorted: `user`, `service`, `script`, `manual`, `receive`.         |
+| `fieldKinds`       | `string[]` | Distinct declared field kinds, sorted (engine field kinds such as `string`, `subject`, `assignees`). |
+| `guardCount`       | `number`   | Guards declared on stages.                                                                           |
+| `effectCount`      | `number`   | Effects declared on actions.                                                                         |
+| `subworkflowCount` | `number`   | Actions that carry a `spawn` block.                                                                  |
+| `lifecycle`        | `string`   | `'standalone'` or `'child'`.                                                                         |
+
+#### `Workflows Definition Sharing Decided` (version 2)
+
+One event per `deploy` that created at least one new definition version,
+whether or not anything was donated. Measures opt-out rate without carrying
+the document.
+
+| Field             | Type      | What is collected                                                                                                             |
+| ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `decision`        | `string`  | `'opt-in'` (`--share-defs`), `'opt-out'` (`--no-share-defs`), or `'default'` (neither flag).                                  |
+| `shared`          | `boolean` | Whether a donation POST reached the endpoint. `false` for any non-sharing decision, and for a chosen share whose POST failed. |
+| `definitionCount` | `number`  | Newly created definition versions this invocation could have donated.                                                         |
+
+### Engine events the CLI records
+
+Write commands pass the CLI logger into the engine, so a successful operation
+also records the engine's adoption events on the same session. Read commands
+(`list`, `show`, `diagnose`, `tail`, `definition list` / `show` / `diff`) do
+not emit engine events. `nuke` deletes engine-owned documents outside those
+verbs and does not emit them either.
+
+Every instance-scoped engine event includes:
+
+| Field                   | Type     | What is collected                                                                                  |
+| ----------------------- | -------- | -------------------------------------------------------------------------------------------------- |
+| `definitionContentHash` | `string` | Content fingerprint of the pinned definition. Omitted when the definition predates fingerprinting. |
+| `instanceId`            | `string` | Instance document `_id`.                                                                           |
+
+| Event                           | Version | When the CLI emits it                                               | Additional payload                                                                                                                                                                                                                      |
+| ------------------------------- | ------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Workflows Definition Deployed` | 1       | `deploy` for each definition (created or unchanged)                 | Same structural counts as `Workflows Definition Shared`, plus `status`: `'created'` or `'unchanged'`.                                                                                                                                   |
+| `Workflows Instance Started`    | 1       | `start`, and a `fire-action` that spawns a child                    | `initialFieldCount` (number of caller-supplied initial fields), `viaSpawn` (`true` only for a spawned child), `lifecycle`.                                                                                                              |
+| `Workflows Stage Transitioned`  | 1       | A committed hop from `fire-action`, `start` cascade, or `set-stage` | `fromStageIndex`, `toStageIndex` (indexes into `stages[]`, never names), `toIsTerminal`, `isRevisit`, `dwellMs` (milliseconds in the exited stage, omitted if that entry is missing), `via`: `'transition'` or `'setStage'`. Unsampled. |
+| `Workflows Action Fired`        | 1       | `fire-action`                                                       | `activityKind` (optional; derived kind of the fired activity), `hasParams` (whether params were supplied — not the params), `cascaded` (auto-transitions in the post-action cascade).                                                   |
+| `Workflows Instance Aborted`    | 1       | `abort`                                                             | `changed`: `false` if the instance was already terminal.                                                                                                                                                                                |
+| `Workflows Stage Set`           | 1       | `set-stage`                                                         | `changed`: `false` if already at the target stage.                                                                                                                                                                                      |
+| `Workflows Activity Reset`      | 1       | `reset-activity`                                                    | `changed`: `false` if already at the target status, or the instance was terminal.                                                                                                                                                       |
+| `Workflows Definition Deleted`  | 1       | `definition delete`                                                 | `deletedVersionCount`, `cascadeAbortedCount`, `deletedGuardCount` (guards only when the last version goes).                                                                                                                             |
+| `Workflows Effect Completed`    | 1       | `abort` cancelling a pending effect                                 | `effect` (author-chosen name), `status` (`'done'`, `'failed'`, or `'cancelled'`), `origin` (`'action'`), `cascaded`.                                                                                                                    |
+
+The engine also defines `Workflows Field Edited`, `Workflows Instance Ticked`,
+`Workflows Effects Drained`, and `Workflows Effect State Reported`. This CLI
+does not call those verbs, so it does not record those events. Field-edit and
+tick events are sampled at most once per 60 seconds when some other shell
+does emit them.
+
 ## Definition sharing
 
 Separate from telemetry, a `deploy` that creates new definition versions

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;