@sanity/workflow-cli 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @sanity/workflow-cli
 
+## 0.12.0
+
+### Minor Changes
+
+- e3a7ba2: `start` gains `--instance-id` — for retries: the id is the start's idempotency key, so passing the id of a start that failed partway resumes it instead of creating a duplicate (an already-settled start replays as a no-op). A start whose first auto-advance fails after the instance was created and primed (`StartNotSettledError`) now reports as STARTED with the cause and the retry id — a warn, not the "Start rejected" failure path — and the `--json` payload carries `{instanceId, notSettled: true, detail}`. A start that fails before priming (`StartNotPrimedError`) still fails, with the `--instance-id` retry hint appended so the operator can resume instead of duplicating.
+- a8ace4d: New `nuke --tag <tag>` command — the dev-period big red button that deletes every engine-owned document for a deployment tag: instances, definitions, and guard docs (matched by instance-id prefix, so guards orphaned by earlier partial deletions are swept too) across the deployment's workflow resource and every alias-bound resource. Content documents are never touched. The command always prints a per-dataset dry-run plan, then requires typing back every involved `project.dataset` target; `--force` skips the prompt for scripts/CI (the plan still prints). Unlike `definition delete` (the governed lifecycle path), `nuke` deletes raw docs without reading them, so it works on pre-amendment shapes a newer engine can no longer read — the sanctioned reset while the versioned upgrade framework doesn't exist.
+- 5a1a9fe: Direct reads of engine-owned documents adopt the data-model gate (`assertReadableModel`): the CLI's instance and definition reads (`show`, `tail`, `list`, `definition show`, `definition list`, deploy lookups, the share read-back) and the MCP tools that interpret rows from the ungated `engine.query` escape hatch (`list_workflow_definitions`, `list_workflow_instances`, the definition lookup behind `start_workflow` / `get_workflow_definition`). A document written by a newer engine data model now fails with the governed "upgrade `@sanity/workflow-engine`" error instead of rendering unchecked; list projections carry the stamp pair so projected rows gate too.
+
+### Patch Changes
+
+- 092a0d4: **BREAKING:** runtime-supplied refs written into field state are gated on the deployment's declared resource surface.
+  - A `doc.ref` / `doc.refs` / `release.ref` value a caller or effect handler supplies — start `initialFields` input, an action's param-sourced op values, `editField` values, effect-completion ops — must target a declared resource: the `workflowResource` itself or a resource the `resourceClients` resolver serves. An off-surface ref throws the new `RefResourceUndeclaredError` and the commit aborts, instead of writing cleanly and failing later when something dereferences it. The check is advisory like every engine check; stored documents are unchanged.
+  - Definition-authored refs are exempt: literal `initialValue` seeds, `type: 'query'` texts, spawn `with` projections, and op values that bind no action param were validated (and alias-expanded) at deploy, so they materialize into field state without re-checking.
+  - Resource aliases stay a deploy-time abstraction: `deployDefinitions({definitions, resourceAliases?})` expands every `@<alias>:` reference to its physical GDR before fingerprinting, and nothing alias-shaped survives past deploy — the runtime holds no alias map, and an alias-shaped ref supplied to a runtime verb is rejected as malformed like any other non-GDR string.
+  - `createBench` takes `serveResources` (dataset siblings served — and thereby declared — straight from the bench's own store) plus a raw `resourceClients` resolver for anything beyond same-store siblings. The engine also exports `sameResource` alongside the existing GDR helpers.
+  - The CLI wires no `resourceClients`, so refs supplied at runtime through it (`start --field`, `fire-action` ref params) admit the workflow resource only.
+
+- Updated dependencies [f9389e5]
+- Updated dependencies [d0c62ea]
+- Updated dependencies [c3eed2e]
+- Updated dependencies [df4bd80]
+- Updated dependencies [092a0d4]
+- Updated dependencies [5a1a9fe]
+- Updated dependencies [e3a7ba2]
+- Updated dependencies [30fed9e]
+- Updated dependencies [1321ba5]
+- Updated dependencies [e683875]
+- Updated dependencies [a8ace4d]
+  - @sanity/workflow-engine@0.17.0
+
+## 0.11.0
+
+### Minor Changes
+
+- e5f5b77: **BREAKING:** rendering and the `--json` diagnose payload follow the engine's actions-only payload model.
+  - `fire-action`'s list mode renders a cascade-fired action as automation (`⚡ … [automation]` with the engine's canonical cascade-fired detail), never as a fireable command; other disabled reasons keep the shared `actionDisabledDetail` rendering.
+  - `diagnose` renders transitions by their `when` trigger (`whenSatisfied` replaces `filterSatisfied` in the `--json` transitions payload), narrates a waiting activity by its caller-fireable actions only (an all-automation activity reads "waiting on automation"), and words failed-effect causes by their action origin.
+  - The activity status glyphs drop `pending` — activities are active from stage entry.
+
+- 7510fd5: **BREAKING:** `list` speaks the engine's filter vocabulary: the `--in-flight` flag (default: list everything) is replaced by `--include-completed` (default: in-flight only) — the same name, polarity, and default the engine and MCP list surfaces use. `list` also gains `--document <gdr-uri>` to list the instances that reference a document.
+
+  Fixes: expected failures (rejected write verbs, validation errors, the 401 arm) now exit by throwing through the oclif lifecycle instead of a raw `process.exit`, so the telemetry `finally` hook still completes the command trace and flushes batched events; `tail` serializes its notification handling (a burst of commits could double-print history entries and regress the high-water mark); and an untagged `definition show` whose name exists in several tag partitions of one dataset now errors listing the partitions — it previously picked the highest version across partitions, which could show a prod operator the dev definition.
+
+- 6e7f42d: **BREAKING:** Definition sharing on `deploy` flips from opt-in to opt-out, and the flag is renamed. `--share-definitions-with-sanity` becomes the negatable `--share-defs` / `--no-share-defs`. A deploy that creates new definition versions now donates them by default; `--no-share-defs` opts out.
+
+  With neither flag, an interactive terminal is asked **once** — a blocking acknowledgement whose answer persists in the Sanity user config, so it never repeats — before anything is sent, since notice must precede the send. Every later flagless deploy prints a one-line reminder of the current state and the flag to change it, so an ongoing donation is never silent. Unattended runs (CI, `DO_NOT_TRACK`, non-TTY) can't prompt and donate nothing by default; opt in per run with `--share-defs`.
+
+  An explicit `--share-defs` also sends that deploy's telemetry regardless of CI / `DO_NOT_TRACK` (a command-line arg beats env vars; account-level `sanity telemetry disable` still applies). Telemetry gains a content-free `Editorial Workflows Definition Sharing Decided` event per invocation — how the decision was reached and what it was (`opt-in` / `opt-out` / `prompt-accepted` / `prompt-declined` / `remembered-share` / `remembered-decline` / `unattended`), whether anything reached the endpoint, and how many versions were eligible — so adoption dashboards can separate explicit opt-outs, prompt declines, and unattended runs and measure the true opt-out rate. The per-definition `Editorial Workflows Definition Shared` marker and the one-POST feedback transport are unchanged.
+
+### Patch Changes
+
+- Updated dependencies [11e2d6f]
+- Updated dependencies [7510fd5]
+- Updated dependencies [01e8042]
+- Updated dependencies [79c54db]
+- Updated dependencies [6a46db1]
+- Updated dependencies [35b9b85]
+- Updated dependencies [e5f5b77]
+- Updated dependencies [01e8042]
+  - @sanity/workflow-engine@0.16.0
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -16,7 +16,7 @@ pnpm --filter @sanity/workflow-cli dev <command> [...args]
 # Examples:
 pnpm --filter @sanity/workflow-cli dev --help
 pnpm --filter @sanity/workflow-cli dev deploy --dry-run
-pnpm --filter @sanity/workflow-cli dev list --in-flight
+pnpm --filter @sanity/workflow-cli dev list --include-completed
 pnpm --filter @sanity/workflow-cli dev show wf-instance.abc123
 ```
 
@@ -74,11 +74,20 @@ config fails with a clean, path-prefixed error before the command runs.
 `resourceAliases` is only for content that lives in a _different_ resource from
 `workflowResource`. A definition can reference a document in the **same**
 resource by bare id, no alias needed — bare ids root at `workflowResource` at
-runtime. Rule of thumb: **different resource → bind an alias and reference it as
-`@<handle>:<id>`; same resource → use a bare id and omit `resourceAliases`
+runtime. Bindings exist at deploy time only: `deploy` expands each `@<handle>:`
+reference to its bound physical GDR, and nothing alias-shaped survives into the
+deployed definition or the runtime. Rule of thumb: **different resource →
+bind an alias; same resource → use a bare id and omit `resourceAliases`
 entirely.** So the simplest single-dataset setup is just a `workflowResource`
 and `definitions`, with no `resourceAliases` at all.
 
+Refs supplied at runtime (`start --field`, `fire-action` ref params) are gated
+separately: they may target the `workflowResource` itself, and anything else is
+rejected at the write with `RefResourceUndeclaredError`. The CLI wires no
+`resourceClients` resolver, so it has no way to widen that surface — a runtime
+foreign-resource ref goes through an engine consumer that serves the target
+resource, not through the CLI.
+
 | Var                 | Purpose                                                                                              |
 | ------------------- | ---------------------------------------------------------------------------------------------------- |
 | `SANITY_AUTH_TOKEN` | Explicit token for CI / scripted use — wins over the `sanity login` session (editor role for writes) |
@@ -118,25 +127,26 @@ stale compiled output.
 
 ## Command status
 
-| Command                                | Status                                                                                                                      |
-| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `deploy`                               | wired — calls `workflow.deployDefinitions` over the selected deployment's definitions                                       |
-| `deploy --all-tags`                    | wired — deploys every deployment in the config, continuing past per-deployment failures                                     |
-| `deploy --check`                       | wired — runs `validateDefinition` over the local batch + a duplicate-name check                                             |
-| `deploy --dry-run`                     | wired — fetches existing docs and renders a coloured JSON diff per change                                                   |
-| `deploy --only <name>`                 | wired — filters deploy/check/dry-run to one definition by `name`                                                            |
-| `start <name>`                         | wired — calls `workflow.startInstance` (`--field` for input fields)                                                         |
-| `list`                                 | wired — `client.fetch` over `sanity.workflow.instance` documents (`--definition <name>` to filter)                          |
-| `show <instance-id>`                   | wired — `client.getDocument`                                                                                                |
-| `diagnose <instance-id>`               | wired — calls `workflow.diagnose`, classifies why the instance is/isn't progressing                                         |
-| `tail <instance-id>`                   | wired — `client.listen()` over the instance, prints new history entries                                                     |
-| `abort <instance-id>`                  | wired — calls `workflow.abortInstance` (hard stop: cancels pending effects, lifts guards)                                   |
-| `set-stage <instance-id> --to <stage>` | wired — calls `workflow.setStage` (admin override: skips declared transitions/filters; enter lifecycle + cascade still run) |
-| `fire-action <instance-id>`            | wired — `workflow.availableActions` lists actions; `workflow.fireAction` fires one                                          |
-| `definition list`                      | wired — `client.fetch` over `sanity.workflow.definition` documents                                                          |
-| `definition show <name>`               | wired — `client.fetch`, latest version unless `--version`                                                                   |
-| `definition diff <name>`               | wired — diffs the in-code definition against the deployed latest (`--version` to pin)                                       |
-| `definition delete <name>`             | wired — calls `workflow.deleteDefinition` (refuses on live instances unless `--cascade`)                                    |
+| Command                                | Status                                                                                                                                                                                           |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `deploy`                               | wired — calls `workflow.deployDefinitions` over the selected deployment's definitions                                                                                                            |
+| `deploy --all-tags`                    | wired — deploys every deployment in the config, continuing past per-deployment failures                                                                                                          |
+| `deploy --check`                       | wired — runs `validateDefinition` over the local batch + a duplicate-name check                                                                                                                  |
+| `deploy --dry-run`                     | wired — fetches existing docs and renders a coloured JSON diff per change                                                                                                                        |
+| `deploy --only <name>`                 | wired — filters deploy/check/dry-run to one definition by `name`                                                                                                                                 |
+| `start <name>`                         | wired — calls `workflow.startInstance` (`--field` for input fields)                                                                                                                              |
+| `list`                                 | wired — `client.fetch` over `sanity.workflow.instance` documents (`--definition <name>` to filter)                                                                                               |
+| `show <instance-id>`                   | wired — `client.getDocument`                                                                                                                                                                     |
+| `diagnose <instance-id>`               | wired — calls `workflow.diagnose`, classifies why the instance is/isn't progressing                                                                                                              |
+| `tail <instance-id>`                   | wired — `client.listen()` over the instance, prints new history entries                                                                                                                          |
+| `abort <instance-id>`                  | wired — calls `workflow.abortInstance` (hard stop: cancels pending effects, lifts guards)                                                                                                        |
+| `set-stage <instance-id> --to <stage>` | wired — calls `workflow.setStage` (admin override: skips declared transitions/filters; enter lifecycle + cascade still run)                                                                      |
+| `fire-action <instance-id>`            | wired — `workflow.availableActions` lists actions; `workflow.fireAction` fires one                                                                                                               |
+| `definition list`                      | wired — `client.fetch` over `sanity.workflow.definition` documents                                                                                                                               |
+| `definition show <name>`               | wired — `client.fetch`, latest version unless `--version`                                                                                                                                        |
+| `definition diff <name>`               | wired — diffs the in-code definition against the deployed latest (`--version` to pin)                                                                                                            |
+| `definition delete <name>`             | wired — calls `workflow.deleteDefinition` (refuses on live instances unless `--cascade`)                                                                                                         |
+| `nuke --tag <tag>`                     | wired — dev-period reset (exists only until the versioned upgrade framework): deletes every engine-owned doc for the tag (instances, definitions, guards across resources); plan + typed confirm |
 
 ## Telemetry
 
@@ -145,9 +155,10 @@ per-command trace (`Editorial Workflows CLI Command Executed` — the command id
 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, and a session that isn't
-logged in sends nothing. A one-time notice on stderr discloses collection on
-first use.
+CI and trueish `DO_NOT_TRACK` suppress everything (except a `deploy --share-defs`,
+which forces that deploy's telemetry — 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.
 
 One extension point: supply your own logger as `telemetry` in
 `sanity.workflow.ts` and the built-in pipeline is not constructed at all —
@@ -156,20 +167,27 @@ consent, suppression, and destination become its business.
 
 ## Definition sharing
 
-Separate from telemetry, `deploy --share-definitions-with-sanity` donates the
-definition documents the deploy newly created to Sanity — verbatim (structure,
-names, titles, GROQ filters, effect configuration, seeded values), plus their
-deployment coordinates (project and dataset, or resource id) — never content
-documents, instances, or your auth token. The documents go to Sanity's
-first-party definition-feedback endpoint, not the telemetry pipeline;
-telemetry carries only a content-free marker (content hash plus structural
-counts) per shared definition.
-
-Sharing is opt-in by the flag alone, per invocation: the CLI never prompts
-and nothing persists. An interactive deploy that created new definition
-versions without the flag logs a one-line stderr hint pointing at it — CI /
-non-TTY runs stay silent. Telemetry consent and `DO_NOT_TRACK` play no part:
-sharing is its own explicit consent, given per deploy.
+Separate from telemetry, a `deploy` that creates new definition versions
+donates those documents to Sanity — verbatim (structure, names, titles, GROQ
+filters, effect configuration, seeded values), plus their deployment
+coordinates (project and dataset, or resource id) — never content documents,
+instances, or your auth token. The documents go to Sanity's first-party
+definition-feedback endpoint, not the telemetry pipeline; telemetry carries
+only a content-free marker (content hash plus structural counts) per shared
+definition and a per-invocation decision event.
+
+Sharing is **opt-out**. Pass `--share-defs` to donate without being asked, or
+`--no-share-defs` to decline. With neither flag, an interactive terminal is
+asked **once** — the answer is remembered in your Sanity user config, so the
+prompt never repeats — before anything is sent; notice always precedes the
+send. Every later flagless deploy then prints a one-line reminder of the
+current state (sharing, or not) and the flag to change it, so an ongoing
+donation is never silent. Unattended runs (CI, `DO_NOT_TRACK`, a non-TTY pipe)
+can't prompt: by default they donate nothing (opt in per run with
+`--share-defs`). An explicit `--share-defs` also sends that deploy's telemetry
+regardless of CI / `DO_NOT_TRACK` — a command-line arg beats env vars;
+account-level `sanity telemetry disable` still applies. A failed share only
+warns, never failing a completed deploy.
 
 ## Known gaps
 

package/dist/commands/definition/list.d.ts

@@ -5,6 +5,7 @@ interface DefinitionListFlags {
     limit: number;
 }
 export interface DefinitionListRow {
+    _id: string;
     name: string;
     version: number;
     title: string;
@@ -13,6 +14,8 @@ export interface DefinitionListRow {
     inFlightCount: number;
     totalInstances: number;
     _createdAt: string;
+    modelVersion?: number | null;
+    minReaderModel?: number | null;
 }
 export declare function buildDefinitionListQuery(flags: DefinitionListFlags): {
     groq: string;

package/dist/commands/definition/list.js

@@ -1,5 +1,5 @@
 import { Flags } from '@oclif/core';
-import { WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, tagScopeFilter, } from '@sanity/workflow-engine';
+import { WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, assertReadableModel, inFlightFilter, tagScopeFilter, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveReadTargets } from "../../lib/context.js";
@@ -25,13 +25,16 @@ export function buildDefinitionListQuery(flags) {
     }
     const instanceMatch = instanceFilters.join(' && ');
     const groq = `*[${filters.join(' && ')}] | order(name asc, version desc) [0...$limit]{
+      _id,
       name,
       version,
       title,
       tag,
       _createdAt,
+      modelVersion,
+      minReaderModel,
       "stageCount": count(stages),
-      "inFlightCount": count(*[${instanceMatch} && !defined(completedAt)]),
+      "inFlightCount": count(*[${instanceMatch} && ${inFlightFilter()}]),
       "totalInstances": count(*[${instanceMatch}])
     }`;
     return { groq, params };
@@ -60,9 +63,9 @@ export default class DefinitionList extends WorkflowCommand {
             targets,
             log: (line) => this.log(line),
             run: async ({ client }) => {
-                const fetched = await client.fetch(groq, params, {
+                const fetched = (await client.fetch(groq, params, {
                     tag: 'definition.list',
-                });
+                })).map(assertReadableModel);
                 if (!fetched.length) {
                     this.log(`${logSymbols.info} no definitions found`);
                     return;

package/dist/commands/definition/show.d.ts

@@ -12,6 +12,19 @@ export default class DefinitionShow extends WorkflowCommand {
     };
     run(): Promise<void>;
 }
+/**
+ * Resolve the one definition `show` names, refusing every ambiguity: an
+ * untagged name spanning several tag partitions within a dataset
+ * ({@link assertSingleTagPartition}) and a name held by several datasets
+ * ({@link soleHitOrFail}) both error, never pick. `undefined` means nothing
+ * is deployed under the name.
+ */
+export declare function resolveShownDefinition({ targets, name, tag, version, }: {
+    targets: ReadTarget[];
+    name: string;
+    tag: string | undefined;
+    version: number | undefined;
+}): Promise<DeployedDefinition | undefined>;
 /** How a lookup names the version it asked for: `vN` for a pinned
  *  `--version`, `latest` when unpinned. */
 export declare function versionLabel(version: number | undefined): string;

package/dist/commands/definition/show.js

@@ -1,12 +1,13 @@
 import { styleText } from 'node:util';
 import { Args, Flags } from '@oclif/core';
-import { isTerminalStage, } from '@sanity/workflow-engine';
+import { assertReadableModel, isTerminalStage, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveReadTargets, soleHitOrFail } from "../../lib/context.js";
-import { buildDefinitionShowQuery } from "../../lib/definitions.js";
+import { buildDefinitionShowQuery, buildDefinitionTagsQuery } from "../../lib/definitions.js";
+import { fail } from "../../lib/fail.js";
 import { tagFlags } from "../../lib/flags.js";
-import { formatKeyValue, sectionHeader } from "../../lib/ui.js";
+import { formatKeyValue, resourceLabel, sectionHeader } from "../../lib/ui.js";
 export default class DefinitionShow extends WorkflowCommand {
     static description = 'Show a deployed workflow definition.';
     static args = {
@@ -19,13 +20,12 @@ export default class DefinitionShow extends WorkflowCommand {
     async run() {
         const { args, flags } = await this.parse(DefinitionShow);
         const targets = await resolveReadTargets(flags);
-        const { groq, params } = buildDefinitionShowQuery({
+        const def = await resolveShownDefinition({
+            targets,
             name: args.name,
             tag: flags.tag,
             version: flags.version,
         });
-        const hits = await fetchDefinitionHits({ targets, groq, params });
-        const def = soleHitOrFail(hits, `Definition "${args.name}"`)?.def;
         if (!def) {
             this.error(`${logSymbols.error} no definition "${args.name}" (${versionLabel(flags.version)})`, {
                 exit: 1,
@@ -38,15 +38,33 @@ export default class DefinitionShow extends WorkflowCommand {
         }
     }
 }
+export async function resolveShownDefinition({ targets, name, tag, version, }) {
+    if (tag === undefined) {
+        await assertSingleTagPartition({ targets, name });
+    }
+    const { groq, params } = buildDefinitionShowQuery({ name, tag, version });
+    const hits = await fetchDefinitionHits({ targets, groq, params });
+    return soleHitOrFail(hits, `Definition "${name}"`)?.def;
+}
 export function versionLabel(version) {
     return version === undefined ? 'latest' : `v${version}`;
 }
+async function assertSingleTagPartition({ targets, name, }) {
+    const { groq, params } = buildDefinitionTagsQuery(name);
+    await Promise.all(targets.map(async (target) => {
+        const tags = await target.client.fetch(groq, params, { tag: 'definition.show' });
+        if (tags.length > 1) {
+            fail(`Definition "${name}" exists in several tag partitions in ` +
+                `${resourceLabel(target.resource)} — pass --tag to choose one.`, tags.toSorted().join('\n'));
+        }
+    }));
+}
 export async function fetchDefinitionHits({ targets, groq, params, }) {
     const probes = await Promise.all(targets.map(async (target) => {
         const def = await target.client.fetch(groq, params, {
             tag: 'definition.show',
         });
-        return def === null ? undefined : { resource: target.resource, def };
+        return def === null ? undefined : { resource: target.resource, def: assertReadableModel(def) };
     }));
     return probes.filter((hit) => hit !== undefined);
 }

package/dist/commands/deploy.d.ts

@@ -18,7 +18,7 @@ export default class Deploy extends WorkflowCommand {
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         check: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         only: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'share-definitions-with-sanity': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'share-defs': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;

package/dist/commands/deploy.js

@@ -41,9 +41,9 @@ export default class Deploy extends WorkflowCommand {
         only: Flags.string({
             description: 'Limit deploy/check/diff to a single workflow definition by name. Every targeted deployment must contain it.',
         }),
-        'share-definitions-with-sanity': Flags.boolean({
-            description: 'Share the definition documents newly created by this deploy with Sanity — the full document, verbatim (structure, names, filters, effect configuration, seeded values), plus its deployment coordinates (project and dataset, or resource id); never content documents, instances, or your Sanity auth token. Opt-in for this invocation only; the CLI never prompts. Independent of telemetry consent.',
-            default: false,
+        'share-defs': Flags.boolean({
+            allowNo: true,
+            description: 'Share the definition documents newly created by this deploy with Sanity — the full document, verbatim (structure, names, filters, effect configuration, seeded values), plus its deployment coordinates (project and dataset, or resource id); never content documents, instances, or your Sanity auth token. Opt-out: an interactive terminal is asked once (the answer is remembered), while unattended runs (CI / non-TTY / DO_NOT_TRACK) share nothing unless --share-defs is passed. Use --no-share-defs to opt out. An explicit --share-defs also sends telemetry for this deploy regardless of CI / DO_NOT_TRACK.',
         }),
     };
     async run() {
@@ -90,7 +90,7 @@ export default class Deploy extends WorkflowCommand {
             log(line);
         }
         await shareDefinitionsAfterDeploy({
-            flag: flags['share-definitions-with-sanity'],
+            flag: flags['share-defs'],
             candidates,
             warn: (message) => this.warn(message),
         });

package/dist/commands/diagnose.d.ts

@@ -6,7 +6,7 @@ import { WorkflowCommand } from '../lib/base-command.ts';
 export declare function rawTransitionProjection(evaluation: WorkflowEvaluation): {
     name: string;
     to: string;
-    filterSatisfied: boolean;
+    whenSatisfied: boolean;
     unevaluable: boolean;
     blockedBy: {
         requirement?: import("@sanity/groq-condition-describe").AtomRequirement;

package/dist/commands/diagnose.js

@@ -19,8 +19,8 @@ function activityLine(t, assignees) {
     return `  ${activityIcon[t.status]} ${t.activity.name} ${styleText('dim', `[${t.status}]`)}${who}`;
 }
 function transitionLine(tr, explanation) {
-    const mark = tr.filterSatisfied ? styleText('green', 'ready') : styleText('red', 'false');
-    const line = `  → ${tr.transition.to}  ${styleText('dim', tr.transition.filter ?? 'true')}  ${mark}`;
+    const mark = tr.whenSatisfied ? styleText('green', 'ready') : styleText('red', 'false');
+    const line = `  → ${tr.transition.to}  ${styleText('dim', tr.transition.when)}  ${mark}`;
     return explanation !== undefined ? `${line}\n      ${styleText('dim', `↳ ${explanation}`)}` : line;
 }
 function currentStageLines(input, explanations) {
@@ -28,7 +28,7 @@ function currentStageLines(input, explanations) {
         `${sectionHeader('Stage')} ${input.instance.currentStage}`,
         sectionHeader('Activities'),
     ];
-    for (const t of input.activities) {
+    for (const t of input.activities.filter((a) => !a.scopedOut)) {
         lines.push(activityLine(t, input.assignees[t.activity.name] ?? []));
     }
     if (input.transitions.length > 0) {
@@ -42,14 +42,14 @@ function currentStageLines(input, explanations) {
 function failedEffectDetail(effect) {
     const ran = effect.durationMs !== undefined ? ` (after ${effect.durationMs}ms)` : '';
     return {
-        headline: `a failed effect is blocking activity '${effect.origin.name}'`,
+        headline: `a failed effect from action '${effect.origin.name}' is blocking its activity`,
         why: [
             styleText('red', `${logSymbols.error} failed effect: ${effect.name}`),
-            `  queued by activity '${effect.origin.name}', failed ${formatTimestamp(effect.ranAt)}${ran}`,
+            `  queued by action '${effect.origin.name}', failed ${formatTimestamp(effect.ranAt)}${ran}`,
             ...(effect.error !== undefined ? [`  error: ${effect.error.message}`] : []),
             '',
-            `Activity '${effect.origin.name}' is waiting on this effect. It failed against an`,
-            `external system, so the activity never completes and the stage can't advance.`,
+            `The activity that fired '${effect.origin.name}' is waiting on this effect. It failed`,
+            `against an external system, so the activity never resolves and the stage can't advance.`,
         ],
     };
 }
@@ -74,12 +74,22 @@ function failedActivityDetail(activity) {
 }
 function waitingHeadline(w) {
     const who = w.assignees.length > 0 ? ` on ${w.assignees.map(formatAssignee).join(', ')}` : '';
+    if (w.actions.length === 0) {
+        return `waiting${who} on automation — a trigger fires on its own when its condition holds`;
+    }
     return `waiting${who} for action: ${w.actions.join(' or ')}`;
 }
 function waitingLines(w) {
     const who = w.assignees.length > 0
         ? `assigned to ${w.assignees.map(formatAssignee).join(', ')}`
         : 'unassigned — anyone with permission can act';
+    if (w.actions.length === 0) {
+        return [
+            `${logSymbols.info} activity '${w.activity}' is active (${who}),`,
+            `waiting on automation: its cascade-fired action(s) fire on their own when their`,
+            `trigger conditions hold — nothing for a caller to fire.`,
+        ];
+    }
     return [
         `${logSymbols.info} activity '${w.activity}' is active (${who}),`,
         `waiting for action: ${w.actions.join(' or ')}. This is the normal in-flight`,
@@ -103,20 +113,20 @@ function blockedLines(b) {
 }
 function noTransitionDetail() {
     return {
-        headline: `no exit transition's filter is satisfied`,
+        headline: `no exit transition's trigger is satisfied`,
         why: [
-            `${logSymbols.info} every activity is resolved, but no exit transition's filter is true.`,
-            `Likely a routing state value a filter reads never got written.`,
+            `${logSymbols.info} every activity is resolved, but no exit transition's \`when\` is true.`,
+            `Likely a routing state value a trigger reads never got written.`,
         ],
     };
 }
 function transitionUnevaluableDetail(transitions) {
     return {
-        headline: `an exit transition's filter could not be evaluated`,
+        headline: `an exit transition's trigger could not be evaluated`,
         why: [
             `${logSymbols.info} every activity is resolved, but ${transitions.join(', ')} reads an operand`,
             `that is missing or unreadable (GROQ null), so routing is held rather than`,
-            `falling through. Make the data the filter reads readable — publish the`,
+            `falling through. Make the data the trigger reads readable — publish the`,
             `subject (or fill the field) — and the instance advances on its own; no`,
             `set-stage needed.`,
         ],
@@ -166,7 +176,7 @@ export function rawTransitionProjection(evaluation) {
     return evaluation.currentStage.transitions.map((t) => ({
         name: t.transition.name,
         to: t.transition.to,
-        filterSatisfied: t.filterSatisfied,
+        whenSatisfied: t.whenSatisfied,
         unevaluable: t.unevaluable,
         blockedBy: t.insight.blockedBy.map((atom) => ({
             groq: atom.atom.groq,

package/dist/commands/fire-action.js

@@ -1,6 +1,6 @@
 import { styleText } from 'node:util';
 import { Args, Flags } from '@oclif/core';
-import { actionDisabledDetail, deniedGuardLabels, workflow, } from '@sanity/workflow-engine';
+import { actionRendering, actionDisabledDetail, deniedGuardLabels, workflow, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../lib/base-command.js";
 import { resolveInstanceContext } from "../lib/context.js";
@@ -20,8 +20,19 @@ function paramLabel(p) {
     return `${p.name}${p.required === true ? '' : '?'}:${p.type}`;
 }
 function actionLines(a) {
-    const mark = a.allowed ? logSymbols.success : logSymbols.error;
     const title = a.title !== undefined ? styleText('dim', `  (${a.title})`) : '';
+    const rendering = actionRendering(a);
+    if (rendering === 'absent')
+        return [];
+    if (rendering === 'automation') {
+        return [
+            `  ${styleText('cyan', '⚡')} ${a.activity} → ${a.action}${title} ${styleText('dim', '[automation]')}`,
+            ...(a.disabledReason?.kind === 'cascade-fired'
+                ? [styleText('dim', `      ${actionDisabledDetail(a.disabledReason)}`)]
+                : []),
+        ];
+    }
+    const mark = a.allowed ? logSymbols.success : logSymbols.error;
     const lines = [
         `  ${mark} ${a.activity} → ${a.action}${title} ${styleText('dim', `[activity ${a.activityStatus}]`)}`,
     ];

package/dist/commands/list.d.ts

@@ -8,11 +8,14 @@ interface InstanceRow {
     completedAt?: string | null;
     abortedAt?: string | null;
     lastChangedAt: string;
+    modelVersion?: number | null;
+    minReaderModel?: number | null;
 }
 interface ListFlags {
-    'in-flight': boolean;
+    'include-completed': boolean;
     failed: boolean;
     definition?: string | undefined;
+    document?: string | undefined;
     tag?: string | undefined;
     limit: number;
 }
@@ -20,6 +23,13 @@ interface ListFlags {
  * Build the GROQ query + params for `list` from its flags. Pure so the
  * filter combinations can be asserted without a live dataset. `--tag` is an
  * optional filter: omit it and the listing spans every partition.
+ *
+ * With `--document` the lake filter is the engine's prefilter arm — a
+ * deliberate superset narrowed to the exact watch-set in JS
+ * ({@link instanceWatchesDocument}) — so the rows come back as full
+ * documents (the narrowing reads fields/stages/ancestors) and UNCAPPED: a
+ * capped superset could silently hide matches. The display limit applies
+ * after narrowing.
  */
 export declare function buildListQuery(flags: ListFlags): {
     groq: string;
@@ -38,9 +48,10 @@ export default class List extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static flags: {
-        'in-flight': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'include-completed': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         failed: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         definition: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        document: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };