@sanity/workflow-cli 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @sanity/workflow-cli
 
+## 0.28.0
+
+### Minor Changes
+
+- 5050b06: **BREAKING:** Authoring a deployment now types through `WorkflowDeploymentInput` / `WorkflowConfigInput`, which require `expectedMinReaderModel` as the current reader-floor literal. Passing a parsed `WorkflowDeployment` / `WorkflowConfig` (where the floor is optional/unverified) into `defineWorkflowConfig` or `defineWorkflows` is a type error — share the authored deployment object instead of `config.deployments[n]`. The same pin shows up on the blueprint resource: `EditorialWorkflowsResource.deployment` and `parseWorkflowDeployment`'s return type are now `AcknowledgedDeployment` (floor asserted to the current literal), so a hand-constructed provider resource must carry that literal too.
+
+  At runtime, config parse no longer rejects a stale or missing floor on an untargeted deployment. Only deployment-scoped commands assert, and only the selected deployment: definition deploy, `--check` / `--dry-run`, blueprint provision, `start`, `definition delete`, and `definition diff` (the last is a deployment-scoped read). Instance-id commands (`fire-action`, `abort`, `set-stage`, `reset-activity`) deliberately do not assert — they resolve by instance id, not by a declared deployment's acknowledgement — so an unacknowledged floor does not stop those instance commits.
+
+  Upgrade TypeScript configs and blueprint manifests that fed a parsed deployment into those helpers: keep a shared authored object (`satisfies WorkflowDeploymentInput`) for both `defineWorkflowConfig` and `defineWorkflows`, and give any hand-built `EditorialWorkflowsResource` the current floor literal on `deployment`. Existing configs that already acknowledge the current floor keep working at runtime; a stale selected deployment still fails with `ReaderModelAcknowledgementError` (headline + short steps; the CLI renders it through the clean styled-error path).
+
+  **Docs impact:** Update the CLI / blueprint authoring examples and the prerelease reader-floor guidance so they name `WorkflowConfigInput` / `WorkflowDeploymentInput` / `AcknowledgedDeployment`, forbid passing `config.deployments[n]` into `defineWorkflows`, state that instance-id writes are outside the acknowledgement gate, and stop implying whole-config parse-time rejection for commands that never select a deployment.
+
+- cc50d58: **BREAKING:** Canonical oclif command ids move from the `editorial-workflows` topic to `workflows`. A future host mount therefore surfaces `sanity workflows deploy` (and the same shape for every other command) instead of `sanity editorial-workflows …`. Standalone short forms (`sanity-workflows deploy`, `definition list`, …) are unchanged — the bin still rewrites them onto the topic before resolution.
+
+  Anyone invoking the previous topic-scoped ids (`sanity-workflows editorial-workflows deploy`, or a host/plugin that hard-coded those ids) must switch to `workflows …`. Continuing to call `editorial-workflows …` fails with command-not-found.
+
+  **Docs impact:** When the host mount ships, update Editorial Workflows CLI getting-started and invocation docs so the documented host path is `sanity workflows …`, and refresh any topic-scoped examples that still say `editorial-workflows`. Until then the standalone short forms remain the documented surface.
+
+### Patch Changes
+
+- 4403e66: Short command forms (`deploy`, `definition list`, …) are no longer registered as oclif root aliases. The standalone `sanity-workflows` binary still accepts those forms by rewriting argv onto the `workflows` topic before command resolution, so day-to-day usage is unchanged. Removing the aliases makes the package safe to mount inside the official `sanity` CLI without colliding with host commands such as `sanity deploy`.
+
+  **No upgrade action required** for standalone `sanity-workflows` / `npx @sanity/workflow-cli` users. Anyone who embedded this package as an oclif plugin and relied on the root aliases must invoke the topic-scoped ids (`workflows deploy`, …) or perform equivalent argv rewriting in the host.
+
+  **Docs impact:** Update Editorial Workflows CLI getting-started and invocation docs when the host mount ships so the primary path is `sanity workflows …`; until then the standalone short forms remain the documented surface in this package README.
+
+- Updated dependencies [1e4a5da]
+- Updated dependencies [5050b06]
+- Updated dependencies [a044ba5]
+  - @sanity/workflow-engine@0.28.0
+
+## 0.27.0
+
+### Patch Changes
+
+- Updated dependencies [780cf93]
+  - @sanity/workflow-engine@0.27.0
+
 ## 0.26.0
 
 ### Patch Changes

package/README.md

@@ -21,17 +21,16 @@ pnpm --filter @sanity/workflow-cli dev show wf-instance.abc123
 ```
 
 The package is an [oclif](https://oclif.io) plugin: every command's canonical
-id nests under the `editorial-workflows` topic
-(`sanity-workflows editorial-workflows deploy`), so mounting the package into
+id nests under the `workflows` topic
+(`sanity-workflows workflows deploy`), so mounting the package into
 the `sanity` CLI's plugin list surfaces the same commands as
-`sanity editorial-workflows …` without its canonical ids colliding with the
-host's own commands (the sanity CLI already has a `deploy`). The bare forms
-used throughout this README (`deploy`, `definition list`, …) are aliases of
-the nested ids and are the standalone binary's stable surface. oclif registers
-plugin aliases in a host unconditionally (an id collision resolves by plugin
-priority, host first), so a host mount would also surface these bare aliases
-at its root — trimming or hiding them for the mounted context is part of the
-host-side mount work, not something a host can configure away.
+`sanity workflows …` without colliding with the host's own root
+commands (the sanity CLI already has a `deploy`). The short forms used
+throughout this README (`deploy`, `definition list`, …) are the standalone
+binary's stable surface — its production and development entrypoints
+(`bin/run.js` and `bin/dev.js`) rewrite them onto the topic before oclif
+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
@@ -224,11 +223,11 @@ only warns, never failing a completed deploy.
 ## Known gaps
 
 - **Not mounted in the `sanity` CLI yet.** The package side is mount-ready —
-  commands nest under the `editorial-workflows` oclif topic (see
-  [Run](#run)) — but the `sanity` CLI does not list this package in its
-  plugin array, so the commands ship only through the standalone
-  `sanity-workflows` binary today. The host-side mount (and what happens to
-  the bare aliases inside a host) is a separate piece of work.
+  commands nest under the `workflows` oclif topic with no root
+  aliases (see [Run](#run)) — but the `sanity` CLI does not list this package
+  in its plugin array, so the commands ship only through the standalone
+  `sanity-workflows` binary today. The host-side mount is a separate piece of
+  work.
 - **No true bypass.** `set-stage` is the engine's `setStage` admin
   override: it skips the definition's declared transitions and filters, but
   the target stage's enter lifecycle and the post-move cascade still run. A

package/bin/run.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
 import {execute} from '@oclif/core'
 
-await execute({dir: import.meta.url})
+import {rewriteStandaloneArgv} from '../dist/standalone-argv.js'
+
+await execute({args: rewriteStandaloneArgv(process.argv.slice(2)), dir: import.meta.url})

package/dist/command-ids.d.ts

@@ -0,0 +1,2 @@
+export declare const WORKFLOWS_TOPIC = "workflows";
+export declare const WORKFLOWS_DEPLOY_COMMAND_ID = "workflows:deploy";

package/dist/command-ids.js

@@ -0,0 +1,2 @@
+export const WORKFLOWS_TOPIC = 'workflows';
+export const WORKFLOWS_DEPLOY_COMMAND_ID = `${WORKFLOWS_TOPIC}:deploy`;

package/dist/commands/{editorial-workflows → workflows}/abort.d.ts

@@ -2,7 +2,6 @@ import { type WorkflowInstance } from '@sanity/workflow-engine';
 import { WorkflowCommand } from '../../lib/base-command.ts';
 import { type WriteReport } from '../../lib/ops-report.ts';
 export default class Abort extends WorkflowCommand {
-    static aliases: string[];
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/{editorial-workflows → workflows}/abort.js

@@ -7,11 +7,10 @@ import { instanceFlags } from "../../lib/flags.js";
 import { buildOperationArgs } from "../../lib/operation-args.js";
 import { runWriteVerb } from "../../lib/ops-report.js";
 export default class Abort extends WorkflowCommand {
-    static aliases = ['abort'];
     static description = 'Abort an in-flight workflow instance — a hard stop: pending effects are cancelled, stage guards removed, and the instance is marked terminal where it stands.';
     static examples = [
-        '<%= config.bin %> abort wf-instance.abc123',
-        "<%= config.bin %> abort wf-instance.abc123 --reason 'superseded by relaunch'",
+        '<%= config.bin %> workflows abort wf-instance.abc123',
+        "<%= config.bin %> workflows abort wf-instance.abc123 --reason 'superseded by relaunch'",
     ];
     static args = {
         instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),

package/dist/commands/{editorial-workflows → workflows}/definition/delete.d.ts

@@ -2,7 +2,6 @@ import { type DeleteDefinitionArgs, type DeleteDefinitionResult } from '@sanity/
 import { WorkflowCommand } from '../../../lib/base-command.ts';
 import { type EngineScope } from '../../../lib/operation-args.ts';
 export default class DefinitionDelete extends WorkflowCommand {
-    static aliases: string[];
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/{editorial-workflows → workflows}/definition/delete.js

@@ -7,14 +7,13 @@ import { deploymentFlags } from "../../../lib/flags.js";
 import { baseEngineArgs } from "../../../lib/operation-args.js";
 import { runWriteVerb } from "../../../lib/ops-report.js";
 export default class DefinitionDelete extends WorkflowCommand {
-    static aliases = ['definition:delete'];
     static description = 'Delete a deployed workflow definition (every version, or one via --version). ' +
         'Refuses while non-terminal instances exist unless --cascade aborts them first — ' +
         'instances are aborted in place, never deleted.';
     static examples = [
-        '<%= config.bin %> definition delete my-workflow',
-        '<%= config.bin %> definition delete my-workflow --version 2',
-        "<%= config.bin %> definition delete my-workflow --cascade --reason 'workflow retired'",
+        '<%= config.bin %> workflows definition delete my-workflow',
+        '<%= config.bin %> workflows definition delete my-workflow --version 2',
+        "<%= config.bin %> workflows definition delete my-workflow --cascade --reason 'workflow retired'",
     ];
     static args = {
         name: Args.string({ required: true, description: 'Workflow definition name.' }),

package/dist/commands/{editorial-workflows → workflows}/definition/diff.d.ts

@@ -1,7 +1,6 @@
 import { type WorkflowDefinition } from '@sanity/workflow-engine';
 import { WorkflowCommand } from '../../../lib/base-command.ts';
 export default class DefinitionDiff extends WorkflowCommand {
-    static aliases: string[];
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/{editorial-workflows → workflows}/definition/diff.js

@@ -8,11 +8,10 @@ import { diffReport } from "../../../lib/diff.js";
 import { deploymentFlags } from "../../../lib/flags.js";
 import { deploymentToTarget } from "../../../lib/select-deployment.js";
 export default class DefinitionDiff extends WorkflowCommand {
-    static aliases = ['definition:diff'];
     static description = 'Diff an in-code definition against the deployed version (latest by default).';
     static examples = [
-        '<%= config.bin %> definition diff productLaunch',
-        '<%= config.bin %> definition diff productLaunch --version 2',
+        '<%= config.bin %> workflows definition diff productLaunch',
+        '<%= config.bin %> workflows definition diff productLaunch --version 2',
     ];
     static args = {
         name: Args.string({ required: true, description: 'Workflow definition name.' }),

package/dist/commands/{editorial-workflows → workflows}/definition/list.d.ts

@@ -22,7 +22,6 @@ export declare function buildDefinitionListQuery(flags: DefinitionListFlags): {
     params: Record<string, unknown>;
 };
 export default class DefinitionList extends WorkflowCommand {
-    static aliases: string[];
     static description: string;
     static examples: string[];
     static flags: {

package/dist/commands/{editorial-workflows → workflows}/definition/list.js

@@ -40,12 +40,11 @@ export function buildDefinitionListQuery(flags) {
     return { groq, params };
 }
 export default class DefinitionList extends WorkflowCommand {
-    static aliases = ['definition:list'];
     static description = 'List deployed workflow definitions.';
     static examples = [
-        '<%= config.bin %> definition list',
-        '<%= config.bin %> definition list --tag prod',
-        '<%= config.bin %> definition list --json',
+        '<%= config.bin %> workflows definition list',
+        '<%= config.bin %> workflows definition list --tag prod',
+        '<%= config.bin %> workflows definition list --json',
     ];
     static flags = {
         ...tagFlags,

package/dist/commands/{editorial-workflows → workflows}/definition/show.d.ts

@@ -2,7 +2,6 @@ import { type DeployedDefinition, type WorkflowDefinition, type WorkflowResource
 import { WorkflowCommand } from '../../../lib/base-command.ts';
 import { type ReadTarget } from '../../../lib/context.ts';
 export default class DefinitionShow extends WorkflowCommand {
-    static aliases: string[];
     static description: string;
     static args: {
         name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;

package/dist/commands/{editorial-workflows → workflows}/definition/show.js

@@ -9,7 +9,6 @@ import { fail } from "../../../lib/fail.js";
 import { jsonFlags, tagFlags } from "../../../lib/flags.js";
 import { formatKeyValue, resourceLabel, sectionHeader } from "../../../lib/ui.js";
 export default class DefinitionShow extends WorkflowCommand {
-    static aliases = ['definition:show'];
     static description = 'Show a deployed workflow definition.';
     static args = {
         name: Args.string({ required: true, description: 'Workflow definition name.' }),

package/dist/commands/{editorial-workflows → workflows}/deploy.d.ts

@@ -12,7 +12,6 @@ interface DeployFailure {
     message: string;
 }
 export default class Deploy extends WorkflowCommand {
-    static aliases: string[];
     static description: string;
     static examples: string[];
     static flags: {
@@ -47,8 +46,10 @@ export declare function resolveBatches(config: WorkflowConfig, { only, selection
  * Select and validate every deployment's definitions up front. Validation runs
  * before any network write ({@link validateOrFail} exits on a bad definition),
  * so a whole-config deploy can never leave a partial reconcile behind a broken
- * batch. In a multi-deployment run the failure names its deployment — it exits
- * before any banner could attribute it.
+ * batch. Also asserts each selected deployment's reader-floor acknowledgement —
+ * including `--check`, which never reaches {@link deploymentToTarget}. In a
+ * multi-deployment run the failure names its deployment — it exits before any
+ * banner could attribute it.
  */
 export declare function buildBatches(deployments: WorkflowDeployment[], only: string | undefined): DeployBatch[];
 /**

package/dist/commands/{editorial-workflows → workflows}/deploy.js

@@ -1,6 +1,6 @@
 import { styleText } from 'node:util';
 import { Flags } from '@oclif/core';
-import { computeDiffEntries, errorMessage, workflow, } from '@sanity/workflow-engine';
+import { assertReaderModelAcknowledgement, computeDiffEntries, errorMessage, workflow, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import ora from 'ora';
 import { WorkflowCommand } from "../../lib/base-command.js";
@@ -15,15 +15,14 @@ import { shareDefinitionsAfterDeploy } from "../../lib/share-definitions.js";
 import { cliTelemetry } from "../../lib/telemetry.js";
 import { groupBanner, resourceLabel } from "../../lib/ui.js";
 export default class Deploy extends WorkflowCommand {
-    static aliases = ['deploy'];
     static description = 'Validate, diff, and deploy workflow definitions to the resource bound by the selected deployment.';
     static examples = [
-        '<%= config.bin %> deploy --deployment review-prod',
-        '<%= config.bin %> deploy --tag prod',
-        '<%= config.bin %> deploy --all-tags',
-        '<%= config.bin %> deploy --check',
-        '<%= config.bin %> deploy --dry-run',
-        '<%= config.bin %> deploy --only productLaunch',
+        '<%= config.bin %> workflows deploy --deployment review-prod',
+        '<%= config.bin %> workflows deploy --tag prod',
+        '<%= config.bin %> workflows deploy --all-tags',
+        '<%= config.bin %> workflows deploy --check',
+        '<%= config.bin %> workflows deploy --dry-run',
+        '<%= config.bin %> workflows deploy --only productLaunch',
     ];
     static flags = {
         ...deploymentFlags,
@@ -161,6 +160,7 @@ export async function resolveBatches(config, { only, selection }) {
 }
 export function buildBatches(deployments, only) {
     return deployments.map((deployment) => {
+        assertReaderModelAcknowledgement(deployment.expectedMinReaderModel, `Deployment ${deployment.name}`);
         const context = deployments.length > 1 ? `${deploymentLabel(deployment)} — ` : '';
         const defs = selectDefinitions(deployment.definitions, { only, context });
         validateOrFail(defs, context);
@@ -193,7 +193,13 @@ export function deploySummary({ total, failures, }) {
     return [
         '',
         styleText('bold', `${total - failures.length} of ${total} deployments succeeded — ${failures.length} failed:`),
-        ...failures.map((f) => styleText('red', `  ${logSymbols.error} ${deploymentLabel(f.deployment)} — ${f.message}`)),
+        ...failures.flatMap((f) => {
+            const [first = '', ...rest] = f.message.split('\n');
+            return [
+                styleText('red', `  ${logSymbols.error} ${deploymentLabel(f.deployment)} — ${first}`),
+                ...rest.map((line) => styleText('red', `    ${line}`)),
+            ];
+        }),
     ];
 }
 export function deploymentBanner({ deployment, index, total, }) {

package/dist/commands/{editorial-workflows → workflows}/diagnose.d.ts

@@ -32,7 +32,6 @@ export declare function renderDiagnosis({ diagnosis, input, remediations, explan
     explanations?: ReadonlyMap<string, string> | undefined;
 }): string[];
 export default class Diagnose extends WorkflowCommand {
-    static aliases: string[];
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/{editorial-workflows → workflows}/diagnose.js

@@ -212,12 +212,11 @@ export function renderDiagnosis({ diagnosis, input, remediations, explanations,
     return lines;
 }
 export default class Diagnose extends WorkflowCommand {
-    static aliases = ['diagnose'];
     static description = "Explain why a workflow instance is or isn't progressing, and what would unstick it.";
     static examples = [
-        '<%= config.bin %> diagnose wf-instance.abc123',
-        '<%= config.bin %> diagnose wf-instance.abc123 --tag prod',
-        '<%= config.bin %> diagnose wf-instance.abc123 --json',
+        '<%= config.bin %> workflows diagnose wf-instance.abc123',
+        '<%= config.bin %> workflows diagnose wf-instance.abc123 --tag prod',
+        '<%= config.bin %> workflows diagnose wf-instance.abc123 --json',
     ];
     static args = {
         instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),

package/dist/commands/{editorial-workflows → workflows}/fire-action.d.ts

@@ -30,7 +30,6 @@ export declare function fireActionReport({ result, activity, action, }: {
     action: string;
 }): WriteReport;
 export default class FireAction extends WorkflowCommand {
-    static aliases: string[];
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/{editorial-workflows → workflows}/fire-action.js

@@ -82,12 +82,11 @@ export function fireActionReport({ result, activity, action, }) {
     };
 }
 export default class FireAction extends WorkflowCommand {
-    static aliases = ['fire-action'];
     static description = 'Fire an action on an instance to unstick a waiting activity — the write acts as the configured token. Omit --action to list what can be fired.';
     static examples = [
-        '<%= config.bin %> fire-action wf-instance.abc123',
-        '<%= config.bin %> fire-action wf-instance.abc123 --activity approve --action approve',
-        '<%= config.bin %> fire-action wf-instance.abc123 --activity publish --action publish --param note=shipping',
+        '<%= config.bin %> workflows fire-action wf-instance.abc123',
+        '<%= config.bin %> workflows fire-action wf-instance.abc123 --activity approve --action approve',
+        '<%= config.bin %> workflows fire-action wf-instance.abc123 --activity publish --action publish --param note=shipping',
     ];
     static args = {
         instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),

package/dist/commands/{editorial-workflows → workflows}/list.d.ts

@@ -47,7 +47,6 @@ export declare function instanceRow(r: InstanceRow): {
     lastChangedAt: string;
 };
 export default class List extends WorkflowCommand {
-    static aliases: string[];
     static description: string;
     static examples: string[];
     static flags: {

package/dist/commands/{editorial-workflows → workflows}/list.js

@@ -77,15 +77,14 @@ export function instanceRow(r) {
     };
 }
 export default class List extends WorkflowCommand {
-    static aliases = ['list'];
     static description = 'List workflow instances in the configured dataset (in-flight by default).';
     static examples = [
-        '<%= config.bin %> list',
-        '<%= config.bin %> list --include-completed',
-        '<%= config.bin %> list --definition productLaunch',
-        '<%= config.bin %> list --document dataset:proj:ds:article-1',
-        '<%= config.bin %> list --tag prod',
-        '<%= config.bin %> list --json',
+        '<%= config.bin %> workflows list',
+        '<%= config.bin %> workflows list --include-completed',
+        '<%= config.bin %> workflows list --definition productLaunch',
+        '<%= config.bin %> workflows list --document dataset:proj:ds:article-1',
+        '<%= config.bin %> workflows list --tag prod',
+        '<%= config.bin %> workflows list --json',
     ];
     static flags = {
         ...tagFlags,

package/dist/commands/{editorial-workflows → workflows}/nuke.d.ts

@@ -1,7 +1,6 @@
 import { type WorkflowConfig, type WorkflowDeployment, type WorkflowInstance, type WorkflowResource } from '@sanity/workflow-engine';
 import { WorkflowCommand } from '../../lib/base-command.ts';
 export default class Nuke extends WorkflowCommand {
-    static aliases: string[];
     static summary: string;
     static description: string;
     static examples: string[];

package/dist/commands/{editorial-workflows → workflows}/nuke.js

@@ -16,7 +16,6 @@ function planApiHost() {
     return resolveApiHost() ?? 'https://api.sanity.io (production default)';
 }
 export default class Nuke extends WorkflowCommand {
-    static aliases = ['nuke'];
     static summary = 'Delete engine-owned documents — a whole deployment tag, or a single instance.';
     static description = 'The reset for a dataset holding engine documents the versioned upgrade framework cannot yet ' +
         "migrate: deletes the tag's instances, definitions, and guards (across every alias-bound " +
@@ -24,9 +23,9 @@ export default class Nuke extends WorkflowCommand {
         'documents are never touched. Prints a dry-run plan, then confirms (--force skips the prompt; ' +
         'the plan still prints).';
     static examples = [
-        '<%= config.bin %> nuke --deployment plugin-dev',
-        '<%= config.bin %> nuke --tag plugin-dev --force',
-        '<%= config.bin %> nuke --instance plugin-dev.wf-instance.abc123',
+        '<%= config.bin %> workflows nuke --deployment plugin-dev',
+        '<%= config.bin %> workflows nuke --tag plugin-dev --force',
+        '<%= config.bin %> workflows nuke --instance plugin-dev.wf-instance.abc123',
     ];
     static flags = {
         deployment: Flags.string({

package/dist/commands/{editorial-workflows → workflows}/reset-activity.d.ts

@@ -2,7 +2,6 @@ import { type ResetActivityTarget, type WorkflowInstance } from '@sanity/workflo
 import { WorkflowCommand } from '../../lib/base-command.ts';
 import { type WriteOutcome, type WriteReport } from '../../lib/ops-report.ts';
 export default class ResetActivity extends WorkflowCommand {
-    static aliases: string[];
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/{editorial-workflows → workflows}/reset-activity.js

@@ -7,11 +7,10 @@ import { instanceFlags } from "../../lib/flags.js";
 import { buildOperationArgs } from "../../lib/operation-args.js";
 import { cascadeTail, runWriteVerb, } from "../../lib/ops-report.js";
 export default class ResetActivity extends WorkflowCommand {
-    static aliases = ['reset-activity'];
     static description = 'Reset a failed activity on an in-flight instance — back to active to re-run it, or --skip to bypass it (mark it skipped) so a gated exit transition can fire.';
     static examples = [
-        '<%= config.bin %> reset-activity wf-instance.abc123 legal-review',
-        '<%= config.bin %> reset-activity wf-instance.abc123 legal-review --skip',
+        '<%= config.bin %> workflows reset-activity wf-instance.abc123 legal-review',
+        '<%= config.bin %> workflows reset-activity wf-instance.abc123 legal-review --skip',
     ];
     static args = {
         instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),

package/dist/commands/{editorial-workflows → workflows}/set-stage.d.ts

@@ -3,7 +3,6 @@ import { WorkflowCommand } from '../../lib/base-command.ts';
 import { type EngineScope } from '../../lib/operation-args.ts';
 import { type WriteOutcome, type WriteReport } from '../../lib/ops-report.ts';
 export default class SetStage extends WorkflowCommand {
-    static aliases: string[];
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/{editorial-workflows → workflows}/set-stage.js

@@ -9,12 +9,11 @@ import { buildOperationArgs } from "../../lib/operation-args.js";
 import { cascadeTail, opsAppliedLines, runWriteVerb, } from "../../lib/ops-report.js";
 import { canPromptOnStderr, selectOnStderr } from "../../lib/prompt.js";
 export default class SetStage extends WorkflowCommand {
-    static aliases = ['set-stage'];
     static description = "Force an instance into a stage, regardless of its declared transitions and filters — the engine's setStage admin override. The target stage's enter lifecycle still runs (auto-activities start, stage guards reconcile), and the post-move cascade can immediately auto-transition the instance onward.";
     static examples = [
-        '<%= config.bin %> set-stage wf-instance.abc123 --to ready',
-        '<%= config.bin %> set-stage wf-instance.abc123',
-        "<%= config.bin %> set-stage wf-instance.abc123 --to ready --reason 'unblock for demo'",
+        '<%= config.bin %> workflows set-stage wf-instance.abc123 --to ready',
+        '<%= config.bin %> workflows set-stage wf-instance.abc123',
+        "<%= config.bin %> workflows set-stage wf-instance.abc123 --to ready --reason 'unblock for demo'",
     ];
     static args = {
         instanceId: Args.string({

package/dist/commands/{editorial-workflows → workflows}/show.d.ts

@@ -1,7 +1,6 @@
 import { type WorkflowInstance } from '@sanity/workflow-engine';
 import { WorkflowCommand } from '../../lib/base-command.ts';
 export default class Show extends WorkflowCommand {
-    static aliases: string[];
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/{editorial-workflows → workflows}/show.js

@@ -7,12 +7,11 @@ import { findInstance, resolveReadTargets } from "../../lib/context.js";
 import { jsonFlags, tagFlags } from "../../lib/flags.js";
 import { formatKeyValue, formatTimestamp, sectionHeader, activityIcon } from "../../lib/ui.js";
 export default class Show extends WorkflowCommand {
-    static aliases = ['show'];
     static description = 'Show the state, activities, and effects of a workflow instance.';
     static examples = [
-        '<%= config.bin %> show wf-instance.abc123',
-        '<%= config.bin %> show wf-instance.abc123 --include history',
-        '<%= config.bin %> show wf-instance.abc123 --json',
+        '<%= config.bin %> workflows show wf-instance.abc123',
+        '<%= config.bin %> workflows show wf-instance.abc123 --include history',
+        '<%= config.bin %> workflows show wf-instance.abc123 --json',
     ];
     static args = {
         instanceId: Args.string({

package/dist/commands/{editorial-workflows → workflows}/start.d.ts

@@ -2,7 +2,6 @@ import { StartNotSettledError, type InitialFieldValue, type StartInstanceArgs, t
 import { WorkflowCommand } from '../../lib/base-command.ts';
 import { type EngineScope } from '../../lib/operation-args.ts';
 export default class Start extends WorkflowCommand {
-    static aliases: string[];
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/{editorial-workflows → workflows}/start.js

@@ -10,14 +10,13 @@ import { baseEngineArgs } from "../../lib/operation-args.js";
 import { runWriteVerb } from "../../lib/ops-report.js";
 import { parseParams } from "../../lib/params.js";
 export default class Start extends WorkflowCommand {
-    static aliases = ['start'];
     static description = 'Start a workflow instance from a deployed definition. Supply values for the ' +
         "workflow's input-sourced fields with --field (e.g. the subject document ref).";
     static examples = [
-        '<%= config.bin %> start productLaunch',
-        '<%= config.bin %> start article-review --field subject=\'{"id":"dataset:proj:ds:article-1","type":"article"}\'',
-        '<%= config.bin %> start productLaunch --version 2 --tag prod',
-        '<%= config.bin %> start productLaunch --instance-id prod.wf-instance.a1b2c3d4e5f6',
+        '<%= config.bin %> workflows start productLaunch',
+        '<%= config.bin %> workflows start article-review --field subject=\'{"id":"dataset:proj:ds:article-1","type":"article"}\'',
+        '<%= config.bin %> workflows start productLaunch --version 2 --tag prod',
+        '<%= config.bin %> workflows start productLaunch --instance-id prod.wf-instance.a1b2c3d4e5f6',
     ];
     static args = {
         name: Args.string({ required: true, description: 'Workflow definition name.' }),

package/dist/commands/{editorial-workflows → workflows}/tail.d.ts

@@ -1,6 +1,5 @@
 import { WorkflowCommand } from '../../lib/base-command.ts';
 export default class Tail extends WorkflowCommand {
-    static aliases: string[];
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/{editorial-workflows → workflows}/tail.js

@@ -9,9 +9,8 @@ import { tagFlags } from "../../lib/flags.js";
 import { formatTimestamp } from "../../lib/ui.js";
 const TAIL_TAG = 'tail';
 export default class Tail extends WorkflowCommand {
-    static aliases = ['tail'];
     static description = 'Stream new history entries on a workflow instance as they land in the dataset.';
-    static examples = ['<%= config.bin %> tail wf-instance.abc123'];
+    static examples = ['<%= config.bin %> workflows tail wf-instance.abc123'];
     static args = {
         instanceId: Args.string({
             required: true,

package/dist/help.d.ts

@@ -1,8 +1,13 @@
-import { Help } from '@oclif/core';
-export declare const isBareSurface: (idOrName: string) => boolean;
+import { Help, type Command } from '@oclif/core';
+/** Strip the mount topic so standalone root help can list short forms. */
+export declare const standaloneSurfaceId: (id: string) => string | undefined;
+/** Keep the standalone short surface, including oclif's help command. */
 export declare const keepCommandAtRoot: (id: string) => boolean;
-/** Standalone-binary help that lists the nested `definition` commands flat in
- *  `--help` rather than under a topic. A mounted host governs its own root help. */
+/** Strip the mount topic from an example rendered by standalone help. */
+export declare const standaloneExample: (example: Command.Example) => Command.Example;
+/** Standalone-binary help that lists topic-scoped commands under their short
+ *  forms (`deploy`, `definition list`) rather than the mount ids. */
 export default class WorkflowHelp extends Help {
+    showCommandHelp(command: Command.Loadable): Promise<void>;
     protected showRootHelp(): Promise<void>;
 }