@qawolf/cli 1.38.0 → 1.40.0

package/dist/cli.js

@@ -16749,6 +16749,11 @@ var makeRequestFileDownloadContract = (ids) => {
     readUrl: string2().describe('Fetch the file\'s bytes from here, for example `curl -o journeys.csv "<readUrl>"`. Write it to a file and read that file, rather than printing the contents, so a large file costs one line of output instead of all of it.')
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not change, overwrite or delete the stored file.",
+      openWorldHint: "Access is limited to QA Wolf team storage; the caller cannot supply an arbitrary external destination.",
+      readOnlyHint: "Returns an expiring read URL for an existing file in the authorized workspace storage."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -16775,6 +16780,11 @@ var makeRequestFileUploadContract = (ids) => {
     uploadUrl: string2().describe(`Send the file's bytes here with a single HTTP PUT carrying the returned contentType, for example \`curl -H 'Content-Type: application/octet-stream' --upload-file "journeys.csv" "<uploadUrl>"\`. Upload the bytes from the shell rather than through this API, so a large file never has to be written out as text.`)
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Using the returned upload URL with an existing file name replaces that stored file.",
+      openWorldHint: "The upload target is QA Wolf team storage, not an arbitrary external service or recipient.",
+      readOnlyHint: "Returns an expiring upload URL that permits writing a file to the authorized workspace storage."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: false,
@@ -16890,6 +16900,11 @@ var makeCreateRunContract = (ids) => {
     tracking: _enum(["registered", "failed", "not-requested"]).describe('Whether the conversation named by aiTaskId or chatSessionId will receive run status updates: "registered" when it will, "failed" when the run was created but the registration failed, "not-requested" when neither id was given or the AI task has no conversation to notify.')
   }, { urlFieldDescription: "Absolute URL of the run page." });
   return {
+    annotationJustifications: {
+      destructiveHint: "Test code can overwrite or delete application data.",
+      openWorldHint: "Test execution can submit forms or change the application under test and its connected services.",
+      readOnlyHint: "Creates a run and enqueues execution of selected flows."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -16956,6 +16971,11 @@ var makeListScreenshotComparisonsContract = (ids) => {
     truncated: boolean2().describe(`True when the selected flows have more than ${maxListedScreenshotAttempts} failed attempts. Only the ${maxListedScreenshotAttempts} most recent are listed, and the older attempts cannot be listed.`)
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not change baselines, results or the run.",
+      openWorldHint: "Reads recorded QA Wolf screenshots without changing the application under test.",
+      readOnlyHint: "Creates missing JPEG previews of the compared images and keeps them in team storage."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -17029,6 +17049,7 @@ var browserActionSchema = discriminatedUnion("type", [
     type: literal("type")
   })
 ]);
+
 // node_modules/@qawolf/api-contracts/dist/v1/runner/environment.js
 var reservedRunEnvironmentVariableName = "QAWOLF_TEAM_ID";
 function refusalForRunEnvironmentVariableName(name) {
@@ -17149,6 +17170,11 @@ var makeInspectOnRunnerContract = (ids) => {
     })
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not edit test code or application data, although the activity refresh can extend billed runtime.",
+      openWorldHint: "Inspects the private runner session without submitting application actions.",
+      readOnlyHint: "Retrieves browser inspection data and refreshes activity, which can cancel an inactivity shutdown."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -17313,6 +17339,11 @@ var makeInspectMobileOnRunnerContract = (ids) => {
     ])
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not change application data, edit tests, or stop the runner.",
+      openWorldHint: "Inspects the existing QA Wolf mobile runner without submitting application actions or contacting arbitrary services.",
+      readOnlyHint: "Reads mobile session status, contexts, page source, or elements without refreshing the runner's inactivity timer."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -17487,6 +17518,11 @@ var makePerformActionOnRunnerContract = (ids) => {
     failure
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Actions can submit irreversible transactions or delete existing data, so uncertain outcomes must be inspected before retrying.",
+      openWorldHint: "Clicks, typing and navigation can submit external forms or change application state.",
+      readOnlyHint: "Performs a browser or device action and can start a browser when needed."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -17538,6 +17574,7 @@ var failedStepSchema = discriminatedUnion("failureReason", [
     failureReason: _enum([
       ...screenFailureReasons,
       "action-not-supported-on-mobile",
+      "action-not-supported-on-browser",
       outOfTimeFailureReason
     ]),
     index: actionIndexSchema,
@@ -17552,6 +17589,7 @@ var sequenceFailureReasons = [
   "action-failed",
   ...screenFailureReasons,
   "action-not-supported-on-mobile",
+  "action-not-supported-on-browser",
   outOfTimeFailureReason,
   unconfirmedFailureReason,
   runnerUnreachableFailureReason
@@ -17560,11 +17598,11 @@ var sequenceFailureReasons = [
 // node_modules/@qawolf/api-contracts/dist/v1/runner/performActions.js
 var actionsDescription = `The actions to perform, in order, each exactly what \`runner.performAction\` takes: coordinates are whole pixels on the runner's virtual desktop, in the same space as \`runner.takeScreenshot\`, and the shapes follow the computer-use vocabulary. At most ${maxActionsPerRequest} per request. For when the next several steps are already known — click a field, type into it, press Enter — and one look at the screen at the end is enough. They run back to back on the runner, with no pause between them: put in one request only steps whose targets are all on the screen you last saw and are not moved by the steps before them, and when a step changes the page — a submit, a navigation, opening a menu — make it the last one and read the frame.`;
 var screenshotModeDescription = "`final`, the default, answers with one screenshot in `imageJpegBase64`: the screen after the last action, or, after a stop, as it stands. `each` puts a screenshot after every action on its entry in `results`, for when each step must be checked; every frame is a full image, so keep such sequences short. `none` sends no screenshot.";
-var stopOnFailureDescription = "`true`, the default, leaves the remaining actions unperformed once one fails. `false` carries on past an action that reached the runner and did not take effect (`action-failed`, `action-not-supported-on-mobile`), so use it only for actions that do not depend on each other: a `type` after a `click` that failed goes to whatever has focus. A runner that cannot be reached, a screen that cannot serve, or running out of time ends the sequence either way.";
+var stopOnFailureDescription = "`true`, the default, leaves the remaining actions unperformed once one fails. `false` carries on past an action that reached the runner and did not take effect (`action-failed`, `action-not-supported-on-mobile`, `action-not-supported-on-browser`), so use it only for actions that do not depend on each other: a `type` after a `click` that failed goes to whatever has focus. A runner that cannot be reached, a screen that cannot serve, or running out of time ends the sequence either way.";
 var finalImageDescription = "Present with `screenshotMode: final` when the runner still answered: the screen after the last action performed, or, after a stop, as it stands.";
 var makePerformActionsOnRunnerContract = (ids) => {
   const input = object({
-    actions: array(browserActionSchema).min(1).max(maxActionsPerRequest).describe(actionsDescription),
+    actions: array(runnerActionSchema).min(1).max(maxActionsPerRequest).describe(actionsDescription),
     id: runnerIdSchema.describe("Id of the runner to act on."),
     screenshotMode: _enum(screenshotModes).optional().describe(screenshotModeDescription),
     stopOnFailure: boolean2().optional().describe(stopOnFailureDescription),
@@ -17589,12 +17627,17 @@ var makePerformActionsOnRunnerContract = (ids) => {
     })
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Actions can submit irreversible transactions or delete existing data, so uncertain outcomes must be inspected before retrying.",
+      openWorldHint: "Clicks, typing and navigation can submit external forms or change application state.",
+      readOnlyHint: "Performs a sequence of browser or device actions on a runner."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
       readOnlyHint: false
     },
-    description: "Perform a sequence of raw browser actions on an interactive runner in one request, one after another, and answer with what happened to each. A `success` means every action took effect. A `failure` names the first action that did not (`failedIndex`, `failureReason`), the last one that did (`lastCompletedIndex`), and whether actions were left unperformed (`stoppedEarly`); `results` has one entry per action reached, in order. Read `effect` on an entry before sending its action again: `performed` means the runner did it; `not-performed` means the runner answered that it did not take effect, though a `navigate` that timed out may still be loading; `unknown` means the runner stopped answering with the action in flight (`runner-unreachable`), or its screen went quiet mid-action (`action-unconfirmed`), and it may have taken effect — a click that submitted a form, say — so take a screenshot instead of repeating it. A sequence gets about a minute to start its actions; an action it did not reach in time is `out-of-time`, nothing after it was attempted, and the rest can go in a new request. Everything `runner.performAction` says about a runner that has never run anything, a mobile runner, and the `screen-needs-a-run`, `screen-not-ready`, `runner-has-no-screen` and `action-not-supported-on-mobile` reasons holds for each action here.",
+    description: "Perform a sequence of raw actions on an interactive runner in one request, one after another, and answer with what happened to each. A `success` means every action took effect. A `failure` names the first action that did not (`failedIndex`, `failureReason`), the last one that did (`lastCompletedIndex`), and whether actions were left unperformed (`stoppedEarly`); `results` has one entry per action reached, in order. Read `effect` on an entry before sending its action again: `performed` means the runner did it; `not-performed` means the runner answered that it did not take effect, though a `navigate` that timed out may still be loading; `unknown` means the runner stopped answering with the action in flight (`runner-unreachable`), or its screen went quiet mid-action (`action-unconfirmed`), and it may have taken effect — a click that submitted a form, say — so take a screenshot instead of repeating it. A sequence gets about a minute to start its actions; an action it did not reach in time is `out-of-time`, nothing after it was attempted, and the rest can go in a new request. Everything `runner.performAction` says about a runner that has never run anything, a mobile runner, and the `screen-needs-a-run`, `screen-not-ready`, `runner-has-no-screen`, `action-not-supported-on-mobile` and `action-not-supported-on-browser` reasons holds for each action here.",
     input,
     kind: "write",
     name: "runner.performActions",
@@ -17662,6 +17705,11 @@ var makeRecordOnRunnerContract = (ids) => {
     url: url()
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Starts or stops a video recording without changing the application under test.",
+      openWorldHint: "Controls recording on a QA Wolf runner without starting external work.",
+      readOnlyHint: "Starts or stops video recording and changes automatic capture settings."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -17689,6 +17737,11 @@ var makeRunnerRecordingsContract = (ids) => {
     }))
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not delete or change any recording.",
+      openWorldHint: "Reads QA Wolf workspace storage without changing the application under test.",
+      readOnlyHint: "Lists or retrieves a runner's finalized recordings."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -17918,6 +17971,11 @@ var makeCreateTriggerContract = (ids) => {
   ]).superRefine(checkTriggerConfiguration);
   const output = object({ trigger: makeTriggerResourceSchema(ids) });
   return {
+    annotationJustifications: {
+      destructiveHint: "Enables automatic execution of test code that may overwrite or delete application data.",
+      openWorldHint: "Triggered runs can change the application under test and update connected integrations.",
+      readOnlyHint: "Creates an active schedule or deployment trigger that can start test runs."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -17941,6 +17999,11 @@ var makeFindTriggersContract = (ids) => {
     triggers: array(makeTriggerResourceSchema(ids)).describe("The team's triggers, newest first.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not modify or delete triggers or their runs.",
+      openWorldHint: "Reads private QA Wolf trigger records without changing external systems.",
+      readOnlyHint: "Lists trigger configuration in the authorized workspace without changing it."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -17959,6 +18022,11 @@ var makeGetTriggerContract = (ids) => {
   const input = object({ triggerId: ids.trigger });
   const output = object({ trigger: makeTriggerResourceSchema(ids) });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not modify or delete the trigger or its runs.",
+      openWorldHint: "Reads a private QA Wolf trigger without changing external systems.",
+      readOnlyHint: "Retrieves one authorized trigger and its configuration without changing it."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -17977,6 +18045,11 @@ var makePauseTriggerContract = (ids) => {
   const input = object({ triggerId: ids.trigger });
   const output = object({ trigger: makeTriggerResourceSchema(ids) });
   return {
+    annotationJustifications: {
+      destructiveHint: "Disables future automatic execution for the selected trigger until it is resumed.",
+      openWorldHint: "Changes private QA Wolf scheduling state without starting external work.",
+      readOnlyHint: "Pauses an existing trigger so it stops starting new work."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: false,
@@ -17993,6 +18066,11 @@ var makeResumeTriggerContract = (ids) => {
   const input = object({ triggerId: ids.trigger });
   const output = object({ trigger: makeTriggerResourceSchema(ids) });
   return {
+    annotationJustifications: {
+      destructiveHint: "Enables automatic test execution that may overwrite or delete application data.",
+      openWorldHint: "Resumed execution can change the application under test and update connected integrations.",
+      readOnlyHint: "Reactivates a paused trigger so future matching schedules or deployments can start runs."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -18011,6 +18089,11 @@ var makeDeleteTriggerContract = (ids) => {
     triggerId: ids.trigger.describe("The id of the deleted trigger.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Permanently deletes the selected trigger configuration.",
+      openWorldHint: "Removes private QA Wolf trigger configuration without starting external work.",
+      readOnlyHint: "Permanently removes a trigger while preserving runs it already created."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: false,
@@ -18047,6 +18130,11 @@ var makeUpdateTriggerContract = (ids) => {
   ]).superRefine(checkTriggerConfiguration);
   const output = object({ trigger: makeTriggerResourceSchema(ids) });
   return {
+    annotationJustifications: {
+      destructiveHint: "Overwrites trigger configuration and can enable tests that change or delete application data.",
+      openWorldHint: "The updated trigger can execute tests against external applications and update connected integrations.",
+      readOnlyHint: "Replaces an existing trigger configuration and can change future automatic runs."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -18088,6 +18176,11 @@ var makeAgentGetContract = (ids) => {
     urlFieldDescription: "Absolute URL of the live session in the QA Wolf app."
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not cancel work or edit tests and messages.",
+      openWorldHint: "Reads a QA Wolf session without posting to external services.",
+      readOnlyHint: "Retrieves session status, replies and the live link without sending work."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18119,6 +18212,11 @@ var makeAgentSendContract = (ids) => {
     urlFieldDescription: "Absolute URL of the live session in the QA Wolf app."
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Delegated execution can overwrite test code or change and delete application data.",
+      openWorldHint: "Delegated work can submit application actions and publish code to connected repositories.",
+      readOnlyHint: "Creates or continues AI work that can implement, run and publish tests."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -18157,6 +18255,11 @@ var makeFindCodeHostIntegrationsContract = (ids) => {
     settingsUrl: url().describe("Absolute URL of the workspace's integrations settings page.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not disconnect integrations or change repository access.",
+      openWorldHint: "Reads QA Wolf integration records without contacting or changing GitHub or GitLab.",
+      readOnlyHint: "Lists the workspace's stored code host integrations and settings link without modifying them."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18189,6 +18292,11 @@ var makeListCodeHostRepositoriesContract = (ids) => {
     repositories: array(makeCodeHostRepositoryResourceSchema()).describe("The repositories the workspace's code host integrations cover, alphabetical by full name.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not edit repositories, integration settings, or access permissions.",
+      openWorldHint: "Reads repositories already recorded for the workspace's integrations, without accessing arbitrary external repositories.",
+      readOnlyHint: "Lists repository metadata from the workspace's last code host sync without triggering a new sync."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18232,6 +18340,11 @@ var makeFindDeploymentsContract = (ids) => {
     nextCursor: nextCursorSchema
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not modify deployments, environments, triggers, or runs.",
+      openWorldHint: "Reads QA Wolf deployment records without contacting deployment providers or starting tests.",
+      readOnlyHint: "Lists stored workspace deployments without reporting or changing their status."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18306,6 +18419,11 @@ var makeListDeploymentTriggerEvaluationsContract = (ids) => {
     object({ state: literal("not-evaluated") }).describe("Triggers were never evaluated for this deployment. Only a deployment's first success report evaluates triggers, so a deployment that never reported success carries no verdicts.")
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not alter recorded verdicts, trigger configuration, or existing runs.",
+      openWorldHint: "Reads stored QA Wolf verdicts without starting tests or updating external services.",
+      readOnlyHint: "Retrieves the recorded trigger verdicts for one deployment without evaluating triggers again."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18377,6 +18495,11 @@ var makeReportDeploymentStatusContract = (ids) => {
   }, { urlFieldDescription: "Absolute URL of the environment's runs page." });
   const output = object({ deployment });
   return {
+    annotationJustifications: {
+      destructiveHint: "Can replace deployment details and variable overrides, and trigger tests that overwrite or delete application data.",
+      openWorldHint: "Successful deployments can start tests against external applications and update connected integrations.",
+      readOnlyHint: "Creates or updates a deployment, can create an environment, and evaluates triggers on its first success report."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -18413,6 +18536,11 @@ var makeFindEmailsContract = (ids) => {
     nextCursor: nextCursorSchema
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not send, edit, or delete email messages.",
+      openWorldHint: "Reads the workspace's QA Wolf inbox records without contacting recipients or arbitrary mailboxes.",
+      readOnlyHint: "Searches stored workspace emails and returns matching message summaries."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18434,6 +18562,11 @@ var makeGetEmailContract = (ids) => {
   });
   const output = makeEmailResourceSchema();
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not alter or delete the message or its attachments.",
+      openWorldHint: "Reads a stored workspace message without forwarding it or contacting external recipients.",
+      readOnlyHint: "Retrieves the content of an existing workspace email."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18462,6 +18595,11 @@ var makeGetEmailAttachmentContract = (ids) => {
     type: string2().optional().describe("The MIME type.")
   }, { urlFieldDescription: emailUrlFieldDescription });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not modify or delete the email or attachment.",
+      openWorldHint: "Access is limited to attachments of authorized workspace emails, not arbitrary external files.",
+      readOnlyHint: "Reads one attachment from an existing workspace email and returns its content."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18486,6 +18624,11 @@ var makeListEmailAddressesContract = (ids) => {
     nextCursor: nextCursorSchema
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not register, replace, or remove inbox addresses.",
+      openWorldHint: "Reads QA Wolf inbox configuration without contacting external mail services or recipients.",
+      readOnlyHint: "Lists the workspace's registered inbox addresses without changing them."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18513,6 +18656,11 @@ var makeRegisterEmailAddressContract = (ids) => {
   });
   const output = makeEmailAddressResourceSchema();
   return {
+    annotationJustifications: {
+      destructiveHint: "Adds an address without replacing or deleting existing inbox addresses or emails.",
+      openWorldHint: "Adds a QA Wolf workspace inbox address without sending messages to external recipients.",
+      readOnlyHint: "Registers an additional inbox address for the workspace."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18551,6 +18699,11 @@ var makeSendEmailContract = (ids) => {
     urlFieldDescription: emailUrlFieldDescription
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Sending an email is irreversible; recipients may act on it, and the tool cannot recall it.",
+      openWorldHint: "Delivers message content and attachments to caller-selected email recipients outside QA Wolf.",
+      readOnlyHint: "Sends an email from a workspace inbox and stores the sent message."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -18596,6 +18749,11 @@ var makeCreateEnvironmentContract = (ids) => {
   });
   const output = makeEnvironmentResourceSchema(ids);
   return {
+    annotationJustifications: {
+      destructiveHint: "Adds a new environment and branch rather than deleting or overwriting an existing one.",
+      openWorldHint: "Creates a branch in the connected Git provider rather than changing only QA Wolf records.",
+      readOnlyHint: "Creates a QA Wolf environment and its remote flow-code branch."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: true,
@@ -18620,6 +18778,11 @@ var makeDeleteEnvironmentVariableContract = (ids) => {
     name: string2().describe("The canonicalized name that was removed. Returned even when the environment had no such variable.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Deletes an existing variable value, while an already-absent variable is left absent.",
+      openWorldHint: "Changes private test configuration without submitting it to an external application.",
+      readOnlyHint: "Removes a named environment variable from QA Wolf storage."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: false,
@@ -18647,6 +18810,11 @@ var makeFindEnvironmentsContract = (ids) => {
     nextCursor: nextCursorSchema
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not edit environments, variables or branches.",
+      openWorldHint: "Reads private QA Wolf environment metadata without publishing changes.",
+      readOnlyHint: "Lists workspace environments and their configuration summaries."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18675,6 +18843,11 @@ var makeGetEnvironmentVariableContract = (ids) => {
     })).describe("The found variables, sorted by name.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not replace or remove variable values.",
+      openWorldHint: "Reads private stored configuration without submitting it to an external application.",
+      readOnlyHint: "Retrieves decrypted values of named environment variables and reports missing names."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18696,6 +18869,11 @@ var makeGetEnvironmentContract = (ids) => {
   });
   const output = makeEnvironmentResourceSchema(ids);
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not alter environment settings or concurrency limits.",
+      openWorldHint: "Reads QA Wolf environment state without updating the connected Git provider.",
+      readOnlyHint: "Retrieves an environment's configuration, run health and code-reconciliation state."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18717,6 +18895,11 @@ var makeListEnvironmentVariableNamesContract = (ids) => {
     variableNames: array(string2()).describe("Names of the environment's variables, sorted alphabetically. Values are never returned.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not alter variables or expose their stored values.",
+      openWorldHint: "Reads private configuration names without changing external systems.",
+      readOnlyHint: "Lists available environment variable names without retrieving their values."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18740,6 +18923,11 @@ var makeSetEnvironmentVariableContract = (ids) => {
     name: string2().describe("The stored variable name after whitespace is replaced with underscores and letters are uppercased.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Can overwrite an existing variable value, while an unchanged value is skipped.",
+      openWorldHint: "Changes stored QA Wolf configuration rather than submitting forms or publishing content.",
+      readOnlyHint: "Creates or replaces a named environment variable without returning its value."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: false,
@@ -18767,6 +18955,11 @@ var makeUpdateEnvironmentContract = (ids) => {
   });
   const output = makeEnvironmentResourceSchema(ids);
   return {
+    annotationJustifications: {
+      destructiveHint: "Can overwrite existing environment settings and affect future run capacity.",
+      openWorldHint: "Changes private environment settings without publishing code or contacting application users.",
+      readOnlyHint: "Updates an environment's name or run concurrency limit."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: false,
@@ -18794,6 +18987,11 @@ var makeCreateTagContract = (ids) => {
   });
   const output = makeTagResourceSchema();
   return {
+    annotationJustifications: {
+      destructiveHint: "Creates a tag without deleting existing tags or flow associations.",
+      openWorldHint: "Adds private QA Wolf metadata without publishing to an external application.",
+      readOnlyHint: "Creates a workspace tag for grouping and selecting flows."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18827,6 +19025,11 @@ var makeAddTagToFlowsContract = (ids) => {
     })
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Adds associations without removing existing tags.",
+      openWorldHint: "Changes private flow-tag associations without running flows or publishing code.",
+      readOnlyHint: "Adds an existing tag to selected flows and skips flows already carrying it."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18881,6 +19084,11 @@ var makeListFlowsContract = (ids) => {
     }))
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not change flow code, readiness or tags.",
+      openWorldHint: "Reads flow records without pushing code or executing application actions.",
+      readOnlyHint: "Lists flows at an environment's reconciled commit or on a selected AI task branch."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -18907,6 +19115,11 @@ var makeRemoveTagFromFlowsContract = (ids) => {
     })
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Deletes existing tag associations and skips flows that do not carry the tag.",
+      openWorldHint: "Changes private flow-tag associations without updating external services.",
+      readOnlyHint: "Removes a selected tag from specified flows."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: false,
@@ -18936,6 +19149,11 @@ var makeUpdateFlowContract = (ids) => {
     })
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Overwrites readiness and can deactivate a flow that was active.",
+      openWorldHint: "Changes private readiness state without itself executing the flow or publishing code.",
+      readOnlyHint: "Changes a flow between draft and active readiness."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: false,
@@ -18958,6 +19176,7 @@ var issuePrioritySchema = _enum([
   "urgent"
 ]);
 var issueStatusSchema = _enum([
+  "backlog",
   "pending",
   "inProgress",
   "paused",
@@ -18966,7 +19185,12 @@ var issueStatusSchema = _enum([
   "archived"
 ]);
 var publicIssueTypeSchema = _enum(["bug", "coverageRequest", "maintenance"]);
-var openIssueStatuses = ["pending", "inProgress", "paused"];
+var openIssueStatuses = [
+  "backlog",
+  "pending",
+  "inProgress",
+  "paused"
+];
 var makeIssueResourceSchema = (ids) => resource({
   coveredFlowIds: array(ids.flow).describe("The flows a coverage request covers. Always empty on bug and maintenance reports, whose flows are listed under reproductions."),
   createdAt: exports_coerce.date().describe("When the issue was created."),
@@ -18988,7 +19212,7 @@ var makeIssueResourceSchema = (ids) => resource({
 var makeFindIssuesContract = (ids) => {
   const input = object({
     ...makePaginationInputFields({ defaultLimit: 20, maxLimit: 100 }),
-    statuses: array(issueStatusSchema).min(1).default([...openIssueStatuses]).describe("Issue statuses to include. Defaults to pending, in-progress, and paused issues."),
+    statuses: array(issueStatusSchema).min(1).default([...openIssueStatuses]).describe("Issue statuses to include. Defaults to backlog, pending, in-progress, and paused issues."),
     type: publicIssueTypeSchema.describe("The issue type to include: bug report, maintenance report, or coverage request."),
     workspaceId: ids.workspace.optional().describe("The workspace whose issues to list. Required when authenticating with an organization or user API key.")
   });
@@ -18997,6 +19221,11 @@ var makeFindIssuesContract = (ids) => {
     nextCursor: nextCursorSchema
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not edit issue details, statuses or coverage associations.",
+      openWorldHint: "Reads QA Wolf issue records without publishing updates to linked trackers.",
+      readOnlyHint: "Lists workspace bug reports, maintenance reports or coverage requests."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -19017,6 +19246,11 @@ var makeGetIssueContract = (ids) => {
     issue: makeIssueResourceSchema(ids)
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not modify or remove the issue.",
+      openWorldHint: "Reads the QA Wolf issue without changing linked external systems.",
+      readOnlyHint: "Retrieves one issue and its associated details."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -19086,9 +19320,18 @@ var makeGetInvestigationContract = (ids) => {
     findings: array(makeInvestigationFindingSchema(ids)),
     runId: ids.run,
     sessionId: ids.chatSession.optional().describe("The investigation session. Absent when the run has none."),
-    status: _enum(["investigating", "finished", "not-investigated"]).describe('Whether the investigation session is still working. "not-investigated" when the run has no investigation.')
+    status: _enum(["investigating", "finished", "not-investigated"]).describe('Whether the lead or any child investigator is still working. "not-investigated" when the run has no investigation.'),
+    subSessions: array(object({
+      sessionId: ids.chatSession,
+      status: agentSessionStatusSchema
+    })).optional().describe("All child investigators, including sessions not attached to findings yet. Send instructions to each sessionId with agent.send.")
   }, { urlFieldDescription: "The run in the QA Wolf app." });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not answer, dispute or change the investigation.",
+      openWorldHint: "Reads recorded QA Wolf findings without changing the application under test.",
+      readOnlyHint: "Retrieves an investigation's findings, open questions and pending answers."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -19117,6 +19360,11 @@ var makeAddFlowsToIssueContract = (ids) => {
     issue: makeIssueResourceSchema(ids)
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Adds coverage associations without removing existing ones.",
+      openWorldHint: "Changes private coverage associations without publishing an external issue update.",
+      readOnlyHint: "Adds existing flows to a coverage request's covered-flow set."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -19160,6 +19408,11 @@ var makeCreateIssueContract = (ids) => {
     issue: makeIssueResourceSchema(ids)
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Configured notifications can send irreversible messages even though the QA Wolf issue itself is new.",
+      openWorldHint: "Issue creation can send messages or synchronize records through connected communication and issue-tracking services.",
+      readOnlyHint: "Creates a bug or coverage request and can start configured issue notifications."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -19184,6 +19437,11 @@ var makeRemoveFlowsFromIssueContract = (ids) => {
     issue: makeIssueResourceSchema(ids)
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Deletes existing coverage associations while leaving already-unassociated flows unchanged.",
+      openWorldHint: "Changes private coverage associations without publishing to an external tracker.",
+      readOnlyHint: "Removes selected flows from a coverage request's covered-flow set."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -19214,6 +19472,11 @@ var makeUpdateIssueContract = (ids) => {
     issue: makeIssueResourceSchema(ids)
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Can overwrite existing issue fields or send irreversible integration messages.",
+      openWorldHint: "Issue changes can update connected issue trackers and communication services.",
+      readOnlyHint: "Updates issue details, priority or status and can trigger integration updates."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -19290,6 +19553,11 @@ var makeFindLegacyTriggersContract = (ids) => {
     legacyTriggers: array(makeLegacyTriggerSchema(ids)).describe("The workspace's legacy triggers, by name.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not pause, resume or change any trigger.",
+      openWorldHint: "Reads private QA Wolf trigger configuration without starting external work.",
+      readOnlyHint: "Lists a workspace's legacy per-environment triggers."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -19314,6 +19582,11 @@ var makeLifecycleShape = (ids) => ({
 var makePauseLegacyTriggerContract = (ids) => {
   const { input, output } = makeLifecycleShape(ids);
   return {
+    annotationJustifications: {
+      destructiveHint: "Disables future automatic execution for the legacy trigger and its pull request copies until it is resumed.",
+      openWorldHint: "Changes private QA Wolf scheduling state without starting external work.",
+      readOnlyHint: "Pauses an existing legacy trigger so it stops starting new work."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: false,
@@ -19329,6 +19602,11 @@ var makePauseLegacyTriggerContract = (ids) => {
 var makeResumeLegacyTriggerContract = (ids) => {
   const { input, output } = makeLifecycleShape(ids);
   return {
+    annotationJustifications: {
+      destructiveHint: "Enables automatic test execution that can overwrite or delete application data.",
+      openWorldHint: "Resumed execution can change the application under test and update connected integrations.",
+      readOnlyHint: "Reactivates a legacy trigger and its pull request copies so future schedules or deployments can start runs."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -19379,6 +19657,11 @@ var makeAcceptScreenshotBaselineContract = (ids) => {
     })
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Replaces the workspace's screenshot baseline, which changes what every later run compares with.",
+      openWorldHint: "Changes private QA Wolf baseline storage without starting external work.",
+      readOnlyHint: "Makes the new screenshot of a failed comparison the baseline."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: false,
@@ -19403,6 +19686,11 @@ var makeDiagnoseRunContract = (ids) => {
     issue: makeIssueResourceSchema(ids)
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Can replace a flow's existing diagnosis association and change externally reported run information.",
+      openWorldHint: "Recorded diagnosis changes can update run-related messages in configured external integrations.",
+      readOnlyHint: "Records failed flows as reproductions of a selected bug or maintenance issue."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -19433,6 +19721,11 @@ var makeFindRunsContract = (ids) => {
     }, { urlFieldDescription: "Absolute URL of the run page." })).describe("The environment's runs, newest first. Per-flow results are available via run.get.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not stop runs, overwrite results or change diagnoses.",
+      openWorldHint: "Reads private run records without executing application actions.",
+      readOnlyHint: "Lists recent environment runs without starting or retrying them."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -19494,6 +19787,7 @@ var makeGetRunContract = (ids) => {
     }),
     object({
       attemptId: ids.runAttempt.optional(),
+      canceledReason: string2().min(1).optional().describe("Why the attempt was canceled. userCanceled means a person stopped it; do not immediately retry that activity."),
       completedAt: exports_iso.datetime().optional(),
       kind: automatedKind,
       startedAt: exports_iso.datetime().optional(),
@@ -19530,6 +19824,11 @@ var makeGetRunContract = (ids) => {
     runId: ids.run.describe("The run this response describes. Treat it as canonical: it can differ from the id you asked for. A deploy notification returns a run id before the run exists, and if a second notification for the same commit is folded into an earlier run, that id resolves to the earlier run instead.")
   }, { urlFieldDescription: "Absolute URL of the run page." });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not retry, cancel or alter the run.",
+      openWorldHint: "Reads recorded QA Wolf results without changing the application under test.",
+      readOnlyHint: "Retrieves a run's status, per-flow results and result links."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -19607,6 +19906,11 @@ var makeGetRunAttemptArtifactsContract = (ids) => {
     })
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not retry, cancel or alter the run attempt.",
+      openWorldHint: "Reads recorded QA Wolf artifacts without changing the application under test.",
+      readOnlyHint: "Retrieves a finished attempt's metadata and signed artifact URLs."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -19631,6 +19935,11 @@ var makeOptOutOfInvestigationRunContract = (ids) => {
     runId: ids.run
   }, { urlFieldDescription: "Absolute URL of the run page." });
   return {
+    annotationJustifications: {
+      destructiveHint: "Ends the investigation of the selected failures and changes externally reported run information.",
+      openWorldHint: "Recorded opt-outs can update run-related messages in configured external integrations.",
+      readOnlyHint: "Records failed flows as needing no bug or maintenance report."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -19655,6 +19964,11 @@ var makeReattemptRunContract = (ids) => {
     runId: ids.run
   }, { urlFieldDescription: "Absolute URL of the run page." });
   return {
+    annotationJustifications: {
+      destructiveHint: "Repeated execution can overwrite or delete application data and creates additional billed work.",
+      openWorldHint: "New attempts execute against the application under test and can affect connected services.",
+      readOnlyHint: "Enqueues new attempts for eligible failed or canceled flows using the latest code."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -19694,6 +20008,11 @@ var makeRestoreScreenshotBaselineContract = (ids) => {
     })
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Replaces the current screenshot baseline with the one it replaced, which changes what every later run compares with.",
+      openWorldHint: "Changes private QA Wolf baseline storage without starting external work.",
+      readOnlyHint: "Puts back the screenshot baseline that an accepted comparison replaced."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: false,
@@ -19715,6 +20034,11 @@ var makeStopRunContract = (ids) => {
     status: _enum(["accepted", "already-finished", "execution-not-found"]).describe('"accepted" means stopping was requested; poll run.get for the final result. "already-finished" means the run has already finished and its result is unchanged. "execution-not-found" means the run exists but no execution was found to stop; it may still be starting or may no longer be available. No stop request was accepted in that case.')
   }, { urlFieldDescription: "Absolute URL of the run page." });
   return {
+    annotationJustifications: {
+      destructiveHint: "Interrupts unfinished work, while finished results remain intact and repeated stop requests are supported.",
+      openWorldHint: "Run status changes can update messages or commit statuses in configured external integrations.",
+      readOnlyHint: "Requests asynchronous cancellation of a run, queued flows and automatic retries."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -19753,6 +20077,11 @@ var makeEvaluateSnippetOnRunnerContract = (ids) => {
     ])
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Code can overwrite or delete runner or application data, and a timeout does not prove execution stopped.",
+      openWorldHint: "Supplied code can submit application actions or contact and change external services.",
+      readOnlyHint: "Executes supplied code against the interactive runner's current session."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -19786,6 +20115,11 @@ var makeGetRunnerContract = (ids) => {
     })
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not stop the runner or change its execution.",
+      openWorldHint: "Reads private runner placement state without acting on external applications.",
+      readOnlyHint: "Checks whether a runner exists without starting it or refreshing its inactivity timer."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -19829,6 +20163,11 @@ var makeHighlightSelectorOnRunnerContract = (ids) => {
     })
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Only replaces or clears the inspection overlay rather than deleting application data.",
+      openWorldHint: "Draws a private inspection overlay without submitting an application form.",
+      readOnlyHint: "Changes the visual selector highlight on the runner's live page."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -19862,6 +20201,11 @@ var makeImportPackageOnRunnerContract = (ids) => {
     })
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Can replace existing dependencies or execute commands that overwrite or delete runner or application data.",
+      openWorldHint: "Installation can contact external services and execute commands that change third-party systems.",
+      readOnlyHint: "Installs caller-selected dependencies into a live runner and can execute commands with the runner's access."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -19891,9 +20235,14 @@ var makeLaunchRunnerContract = (ids) => {
     outcome: literal("success")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Starts billable resource consumption that cannot be undone by later termination.",
+      openWorldHint: "Allocates a private QA Wolf runner without itself navigating to an application or submitting forms.",
+      readOnlyHint: "Starts an interactive runner and allocates billed resources unless the requested runner is already running."
+    },
     annotations: {
       destructiveHint: true,
-      openWorldHint: false,
+      openWorldHint: true,
       readOnlyHint: false
     },
     description: "Launch an interactive runner on the caller's team under an id the caller chooses. Send `initialUrl` so its browser comes up on the page the work starts from, which saves a separate navigation and the browser's cold start. Launching the same id again returns the runner already running rather than starting a second one, and the same id with a different runnerName is refused. A runner is not permanent: it terminates on its own after a period of inactivity, and launching the same id after that starts and bills a new runner, so read `alreadyRunning` to tell which happened. A success means the runner is answering: the call waits for the pod it started to come up, so the very next call to the runner reaches it. If the pod does not come up in time the call fails instead, leaving the runner running, and launching the same id again attaches to it.",
@@ -19914,6 +20263,11 @@ var makeTerminateRunnerContract = (ids) => {
     wasRunning: boolean2().describe("False when no running runner had this id: it was already terminated, was never launched, or terminated on its own after inactivity. These are not distinguished, because the run system keeps no record of a runner once it is gone. Not an error, and a retry needs no special handling.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Terminates running work and discards the live session, while an absent runner is left absent.",
+      openWorldHint: "Stops a private QA Wolf runner without itself publishing to third-party services.",
+      readOnlyHint: "Ends a selected interactive runner and the resources hosting it."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: false,
@@ -19937,6 +20291,11 @@ var makeListRunnersContract = (ids) => {
     runners: array(makeRunnerSchema()).describe("The runners running right now, in no particular order. Each entry carries the same fields a launch reports, so any of them can be addressed like a runner you launched yourself.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not interrupt or terminate any listed runner.",
+      openWorldHint: "Reads private runner state without acting on third-party applications.",
+      readOnlyHint: "Lists running workspace runners without starting them or refreshing their inactivity timers."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -19971,6 +20330,11 @@ var makePromoteSnapshotOnRunnerContract = (ids) => {
     })
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Overwrites an existing baseline, while a missing source snapshot leaves it unchanged.",
+      openWorldHint: "Updates a stored test baseline rather than publishing to an external application.",
+      readOnlyHint: "Replaces a named image-diff baseline with a screenshot produced by the runner."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: false,
@@ -19996,6 +20360,11 @@ var makeReadRunnerJournalContract = (ids) => {
     makeRunnerFailureSchema([runnerUnreachableFailureReason])
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not erase journal entries or change run results, although the activity refresh can extend billed runtime.",
+      openWorldHint: "Reads private runner history without submitting actions to external applications.",
+      readOnlyHint: "Retrieves journal entries and refreshes activity, which can cancel an inactivity shutdown."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -20074,6 +20443,11 @@ var makeRunFlowOnRunnerContract = (ids) => {
     failure
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Test code can overwrite or delete application data, and uncertain acceptance must be checked before resubmission.",
+      openWorldHint: "Executed tests can submit forms and change the application under test or its connected services.",
+      readOnlyHint: "Submits test files for full-flow or selected-line execution on an interactive runner."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: true,
@@ -20101,6 +20475,11 @@ var makeStopRunOnRunnerContract = (ids) => {
     makeRunnerFailureSchema([runnerUnreachableFailureReason])
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Stops unfinished work where it is, while an already-idle runner is left idle.",
+      openWorldHint: "Changes private execution state without itself posting external messages.",
+      readOnlyHint: "Interrupts current execution while leaving the runner available."
+    },
     annotations: {
       destructiveHint: true,
       openWorldHint: false,
@@ -20131,6 +20510,11 @@ var makeTakeScreenshotOnRunnerContract = (ids) => {
     ])
   ]);
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not change application data or stop execution, although the activity refresh can extend billed runtime.",
+      openWorldHint: "Reads the private runner display without submitting an external application action.",
+      readOnlyHint: "Captures the runner screen and refreshes activity, which can cancel an inactivity shutdown."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -20182,6 +20566,11 @@ var makeListSkillsContract = () => {
     skills: array(skillSummary).describe("Every skill the server serves, in catalog order.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not change any skill or workspace data.",
+      openWorldHint: "Reads the QA Wolf skill catalog without calling external services.",
+      readOnlyHint: "Lists the QA Wolf skills with their names and descriptions."
+    },
     annotations: readOnlyAnnotations,
     description: "List the QA Wolf skills, each with its name and the description that says when to use it. A skill is the instructions a coding agent follows for one kind of QA Wolf work, such as onboarding an application, creating a flow, repairing a failing flow, or setting up triggers. Call this before any QA Wolf work, pick the skill whose description matches the request, and read it with skill.get.",
     input,
@@ -20200,6 +20589,11 @@ var makeGetSkillContract = () => {
     })).describe("The files the skill links to under its directory.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not change any skill or workspace data.",
+      openWorldHint: "Reads the QA Wolf skill catalog without calling external services.",
+      readOnlyHint: "Retrieves one QA Wolf skill's instructions and reference files."
+    },
     annotations: readOnlyAnnotations,
     description: "Read a QA Wolf skill: the instructions a coding agent follows for one kind of QA Wolf work. The reply carries the skill's SKILL.md and every file under its references directory, so nothing else has to be fetched for it. Read the skill before starting the work it covers and follow it. A link in the reply of the form ../<skill>/SKILL.md names another skill, which this call reads by that name.",
     input,
@@ -20228,6 +20622,11 @@ var makeListTagsContract = (ids) => {
     })).describe("The team's tags, alphabetical by name.")
   });
   return {
+    annotationJustifications: {
+      destructiveHint: "Does not create, rename or remove tags.",
+      openWorldHint: "Reads private tag metadata without changing connected services.",
+      readOnlyHint: "Lists existing workspace tags by name."
+    },
     annotations: {
       destructiveHint: false,
       openWorldHint: false,
@@ -22820,7 +23219,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.38.0",
+  version: "1.40.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -22891,7 +23290,7 @@ var package_default = {
     "@clack/prompts": "1.5.1",
     "@napi-rs/keyring": "1.3.0",
     "@oxc-node/core": "0.1.0",
-    "@qawolf/api-contracts": "0.77.0",
+    "@qawolf/api-contracts": "0.81.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",
@@ -35386,6 +35785,106 @@ function registerFlowsCommand(program, signals, deps = { withResolvedEnv }) {
   registerFlowsPullCommand(flows, signals);
 }
 
+// src/commands/help/commandTree.ts
+function listVisibleSubcommands(command) {
+  return new Help2().visibleCommands(command).filter((child) => child.name() !== "help");
+}
+function commandPath(command) {
+  return command.parent === null ? [command.name()] : [...commandPath(command.parent), command.name()];
+}
+function findSubcommand(root, path) {
+  return path.reduce((command, segment) => command?.commands.find((child) => child.name() === segment || child.aliases().includes(segment)), root);
+}
+
+// src/commands/help/referenceGuide.ts
+var guides = new WeakMap;
+function declareReferenceGuide(command, markdown) {
+  guides.set(command, markdown);
+  return command;
+}
+function shiftHeadings(markdown, levels) {
+  const lines = markdown.trim().split(`
+`);
+  const shifted = lines.reduce((state, line) => {
+    if (line.startsWith("```")) {
+      return { inFence: !state.inFence, lines: [...state.lines, line] };
+    }
+    const isHeading = !state.inFence && /^#{1,6} /.test(line);
+    const shiftedLine = isHeading ? `${"#".repeat(levels)}${line}` : line;
+    return { inFence: state.inFence, lines: [...state.lines, shiftedLine] };
+  }, { inFence: false, lines: [] });
+  return shifted.lines.join(`
+`);
+}
+function renderReferenceGuide(command, depth) {
+  const guide = guides.get(command);
+  return guide === undefined ? undefined : shiftHeadings(guide, depth - 1);
+}
+
+// src/commands/help/reference.ts
+var referenceHelpWidth = 100;
+var deepestHeadingLevel = 6;
+function formatCommandHelp(command) {
+  const originalOutput = command.configureOutput();
+  const chunks = [];
+  command.configureOutput({
+    getOutHasColors: () => false,
+    getOutHelpWidth: () => referenceHelpWidth,
+    writeOut: (text) => chunks.push(text)
+  });
+  try {
+    command.outputHelp();
+  } finally {
+    command.configureOutput(originalOutput);
+  }
+  return chunks.join("").trimEnd();
+}
+function renderSections(command, path, depth) {
+  const heading = `${"#".repeat(Math.min(depth, deepestHeadingLevel))} ${path.join(" ")}`;
+  const help = ["```text", formatCommandHelp(command), "```"].join(`
+`);
+  const guide = renderReferenceGuide(command, depth);
+  const section = [heading, ...guide === undefined ? [] : [guide], help].join(`
+
+`);
+  return [
+    section,
+    ...listVisibleSubcommands(command).flatMap((child) => renderSections(child, [...path, child.name()], depth + 1))
+  ];
+}
+function renderHelpReference(command, path) {
+  return `${renderSections(command, path, 1).join(`
+
+`)}
+`;
+}
+
+// src/commands/help/index.ts
+var referenceExamples = `
+Examples:
+  $ qawolf help ref runner
+  $ qawolf help ref runner inspect
+  $ qawolf help reference`;
+function resolveCommand(program, path) {
+  const command = findSubcommand(program, path);
+  if (command === undefined) {
+    program.error(`error: unknown command '${path.join(" ")}'`, {
+      code: "commander.unknownCommand",
+      exitCode: exitCodes.invalidArgs
+    });
+  }
+  return command;
+}
+function registerHelpCommand(program) {
+  const help = program.helpCommand(false).command("help").description("Display help for a command").usage("[command...]").argument("[command...]", "Command to show help for").action((path) => {
+    resolveCommand(program, path).outputHelp();
+  });
+  help.command("ref").alias("reference").description("Print the full help of a command and of every command under it, as Markdown. Omit the command for the whole CLI").argument("[command...]", "Command whose subtree to print").addHelpText("after", referenceExamples).action((path) => {
+    const command = resolveCommand(program, path);
+    program.configureOutput().writeOut?.(renderHelpReference(command, commandPath(command)));
+  });
+}
+
 // src/domains/init/init.ts
 import { dirname as dirname14, join as join50, relative as relative9 } from "node:path";
 
@@ -36239,6 +36738,11 @@ function describeReason(step) {
         exitCode: exitCodes.invalidArgs,
         why: "has no touchscreen equivalent on a mobile runner."
       };
+    case "action-not-supported-on-browser":
+      return {
+        exitCode: exitCodes.invalidArgs,
+        why: "is a touchscreen action, which only a mobile runner performs."
+      };
     case "screen-needs-a-run":
       return {
         exitCode: exitCodes.invalidArgs,
@@ -36476,19 +36980,13 @@ function buildRunnerAction(type, flags) {
   };
   return parseRunnerAction(candidate);
 }
-function parseWith(schema, candidate) {
-  const parsed = schema.safeParse(candidate);
+function parseRunnerAction(candidate) {
+  const parsed = runnerActionSchema.safeParse(candidate);
   if (!parsed.success) {
     return { error: prettifyError(parsed.error), ok: false };
   }
   return { action: parsed.data, ok: true };
 }
-function parseRunnerAction(candidate) {
-  return parseWith(runnerActionSchema, candidate);
-}
-function parseBrowserAction(candidate) {
-  return parseWith(browserActionSchema, candidate);
-}
 
 // src/domains/interactiveRunner/readActions.ts
 var stdinArgument = "-";
@@ -36508,7 +37006,7 @@ async function readActions(argument, deps) {
       ok: false
     };
   }
-  const built = parsed.items.map(parseBrowserAction);
+  const built = parsed.items.map(parseRunnerAction);
   const firstRefused = built.findIndex((action) => !action.ok);
   const refused = built[firstRefused];
   if (refused !== undefined && !refused.ok) {
@@ -37024,15 +37522,351 @@ function runnerDeps(ctx) {
   });
 }
 
+// src/commands/runner/guides/act.txt
+var act_default = `# Seeing and acting
+
+There is no hosted vision loop: you look with screenshot, decide with your own model, and act. act performs exactly one action per call, in the computer-use tool vocabulary a vision model already emits. The names and the field names are unchanged from that vocabulary on purpose, so you can forward a tool call rather than translate it with \`act -\`.
+
+Every action in a see-and-act loop is followed by a look at the result, so ask for it in the same call with --screenshot. Prefer it over act and then screenshot: each step is one call instead of two, with no delay to guess at between them. The screen the runner answers with is taken once it has changed from just before the action or half a second has passed, whichever comes first. An action that reached the screen and did not take effect answers with one too, so an exit 1 still leaves you a picture of why the click missed. A 4 whose message starts with "Performed" means the action happened and only the picture is missing: take a screenshot, never send the action again to get it. As with \`screenshot --out -\`, a terminal on stdout is refused.
+
+Coordinates are pixels on the same screenshot you just read. The runner serves one see-or-act request at a time, so never have two in flight; when the next few steps are already known, send them as one \`runner actions\` sequence instead. Bounds are checked before anything is sent, so an over-long --text or an out-of-range coordinate comes back immediately naming the limit.
+
+On a 4, the answer may have been lost with the action in flight: take a screenshot before repeating a click, and repeat only what the screen says did not happen.
+
+# Mobile
+
+A mobile runner has a touchscreen, not a mouse, so it has actions of its own:
+- tap touches a point (--x, --y) or the element --selector names. Check the selector first with \`inspect elements --selector\`, and pass --strategy ios-predicate or shadow when it is not XPath.
+- swipe --from x,y --to x,y moves in a straight line between two points. --duration-ms sets how long it takes, up to 10000: a slow swipe scrolls, a fast one flings.
+- fill --selector ... --text ... replaces the value of that field, and --text "" clears it. To add to what a field already holds, tap it and then type.
+- type types into whatever the last tap focused, the same as on a browser.
+
+On mobile, send tap and swipe, never click or drag. The other browser actions, double_click, scroll, move, keypress and navigate, answer action-not-supported-on-mobile rather than doing something approximate. navigate is the one to watch for, since it works on a browser runner without a run first but has no meaning on mobile at all. A browser runner answers tap, swipe and fill with action-not-supported-on-browser.
+
+# Before the first run
+
+A runner has no screen until its first run, so act exits 2 until then, except navigate, which exits 1 (action-failed): it skips the screen but still needs the runner to have run something. With no runner named at all, act launches one and says so on stderr.
+`;
+
+// src/commands/runner/guides/actions.txt
+var actions_default = `# Batching
+
+Use a sequence for the steps you already know: click the field, type into it, press Enter. One round trip instead of three, with no delay to guess at between them. On a mobile runner the steps are tap, swipe, fill and type, the same as act, and a step the runner does not take fails with the same reason act would give, action-not-supported-on-mobile or action-not-supported-on-browser.
+
+Batch only steps whose targets are all on the screen you last saw and are not moved by the steps before them, and make the step that changes the page, a submit, a navigation, opening a menu, the last one. Then read the frame and decide the next batch from it.
+
+# Screenshots
+
+--screenshot after.jpg writes the screen after the last action, as \`act --screenshot\` does, and - puts those bytes on stdout with the confirmation on stderr. Stdout then carries the image and nothing else, so - trades the per-action results for the frame: give --screenshot a file path whenever you need to read \`effect\` per action. --screenshot-mode each --screenshot step.jpg writes one frame per action instead, step-0.jpg, step-1.jpg and so on; each is a full image, so keep those sequences short.
+
+# Reading the answer
+
+The answer holds one entry per action reached, and the field to read on each is \`effect\`:
+- performed means the runner did it.
+- not-performed means the runner answered that it did not take effect.
+- unknown means the runner stopped answering with the action in flight, or its screen went quiet mid-action, so it may have taken effect. Take a screenshot before repeating anything from that step on, and never send it again blind.
+
+The sequence stops at the first action that fails. --continue-on-failure carries on past one that reached the runner and did not take effect, which is only safe for actions that do not depend on each other: a type after a failed click goes to whatever has focus. A runner that cannot be reached, a screen that cannot serve, or running out of time ends the sequence either way, and the message names every action that did not succeed.
+
+# Exit codes
+
+A sequence exits by the worst thing that happened to any one of its actions: an effect nobody can confirm (4) first, then running out of time (6), then a refusal (2), then an action that plainly did not happen (1). Whatever the code, the message names the last action that took effect, and only what follows it goes in a new request. A sequence also exits 2 before it sends anything for an argument that is not a JSON array, an array of more than ten actions, and --screenshot flags that contradict each other.
+`;
+
+// src/commands/runner/guides/events.txt
+var events_default = `# Streams
+
+Everything observable is an append-only stream on the pod, read by cursor or tail rather than subscribed to, so attaching late still gets you the history that is still there. QA Wolf writes recorder, console, run-events, run-logs and run-status; a stream nobody has written reads as empty rather than as an error, and a stream this CLI version does not know about is still readable by name. One payload per line, so shell tools compose:
+
+$ qawolf runner events console --tail 20 | jq -r '.message'
+$ qawolf runner events run-logs --run <runId> --follow > run.log
+
+--tail N takes the newest N, --since <sequence> reads everything after a cursor, and --run <id> narrows the run-scoped streams.
+
+History is not unbounded: a size cap drops the oldest entries on a long-lived runner, and a --tail N read can stop early and hand back fewer than N even when more matched. Both are warned about on stderr, dropped entries only once a read holds a cursor, a stopped-early read with a pointer at --since. Watch stderr, treat a short answer as "at least this" rather than "all there was", and read what you care about as you go rather than at the end.
+
+# The recorder
+
+\`events recorder\` is what has no equivalent in a screenshot. As you drive the browser, the runner records each interaction and publishes \`locator\` (the real Playwright locator it resolved), \`alternates\` (the others that matched the same element) and \`code\` (the generated Playwright call), alongside \`type\`, \`sourceUrl\` and \`timestamp\`:
+
+$ qawolf runner events recorder --tail 5 | jq -r '.code // .type'
+$ qawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'
+
+\`code\` is absent on events with no call of their own, such as a navigation, which is why the first line falls back to \`type\`. Use these to turn a session you drove by pixel coordinates into durable selectors, and to check that a click landed on the element you meant rather than near it. The stream is empty until the runner's first run gives it a browser context, so an early empty answer means "not yet", not "broken". Do not add --json here: it wraps each line in an envelope and these field paths stop matching.
+
+# Following
+
+--follow polls and prints as entries arrive. It is tail -f with a bound: it ends only at its --timeout (an hour by default, exit 6), because reading keeps the runner alive and billing. It does not end when a run settles, so it cannot be used to wait for a run: use \`runner run --follow\`, or poll run-status. Redirect it to a file and stop it yourself, or use repeated --since reads when you need the command to end sooner.
+
+Where --follow wins is the cursor. The pod reports how far a read scanned rather than how far it matched, and --follow carries that number, so a filtered read that matched nothing still moves forward. A caller paging by hand cannot see it, because the CLI does not print it, and the best available substitute is the highest \`sequence\` you actually saw. So a narrow --run filter over a busy stream stalls: with nothing matching, there is no new \`sequence\` to move on to, and you re-read the same window until something matches.
+
+events never launches a runner.
+`;
+
+// src/commands/runner/guides/exec.txt
+var exec_default = `# Getting a value back
+
+exec does not return what the snippet evaluated to, only whether it ran. To get a value back, print it and read the \`console\` stream with \`qawolf runner events console\`. Print it behind a marker you chose, and match on that rather than taking the newest line: the page logs to the same stream, so anything it prints after your snippet would be what --tail 1 hands back. Entries carry \`source\`, which is \`serverConsole\` for your snippet and \`browserConsole\` for the page, so filtering on both is what pins the value down:
+
+$ echo 'console.log("qw-title:", await page.title())' | qawolf runner exec -
+$ qawolf runner events console --tail 20 | jq -r 'select(.source == "serverConsole" and (.message | contains("qw-title:"))) | .message'
+
+To read a top-level variable of the running workflow, \`qawolf runner inspect variable\` is one call and the value, where exec is two calls and a marker.
+
+# Scope
+
+The snippet imports nothing of yours by default. Pass --file <path> to evaluate it in that file's scope, which also ships the directory's other files, so the snippet can use your own page objects and helpers.
+
+# Failures
+
+exec exits 2 until the runner's first run, since there is no page to evaluate against. On a 4 the message says the snippet could not be evaluated, but a lost answer looks the same from outside, so treat a 4 from a snippet that changes something as "may have run" rather than "did not run", and check its effect before running it again. With no runner named at all, exec launches one and says so on stderr.
+`;
+
+// src/commands/runner/guides/formatGuide.ts
+var guideWidth = 80;
+function wrapWords(text, firstPrefix, restPrefix) {
+  const words = text.split(/\s+/).filter((word) => word.length > 0);
+  return words.reduce((lines, word) => {
+    const last = lines.at(-1);
+    if (last === undefined)
+      return [`${firstPrefix}${word}`];
+    if (last.length + 1 + word.length <= guideWidth) {
+      return [...lines.slice(0, -1), `${last} ${word}`];
+    }
+    return [...lines, `${restPrefix}${word}`];
+  }, []);
+}
+function formatLine(line) {
+  if (line.startsWith("# "))
+    return [`${line.slice(2)}:`];
+  if (line.startsWith("$ "))
+    return [`  ${line}`];
+  if (line.startsWith("- "))
+    return wrapWords(line.slice(2), "  - ", "    ");
+  return wrapWords(line, "  ", "  ");
+}
+function formatGuide(source) {
+  const paragraphs = source.trim().split(/\n\s*\n/).map((paragraph) => paragraph.split(`
+`));
+  const rendered = paragraphs.map((lines, index) => {
+    const text = lines.flatMap(formatLine).join(`
+`);
+    const followsTitle = paragraphs[index - 1]?.[0]?.startsWith("# ") === true;
+    return index === 0 ? text : `${followsTitle ? `
+` : `
+
+`}${text}`;
+  });
+  return `
+${rendered.join("")}`;
+}
+
+// src/commands/runner/guides/highlightSelector.txt
+var highlightSelector_default = `# Reading the result
+
+\`inspect element-html\` tells you what a selector matched; highlight-selector shows you where it is, by drawing on the page itself. The highlight stays until it is replaced or cleared, which is the point: you cannot see the runner's screen, so the only way to read the result is the next screenshot.
+
+Three answers are worth telling apart. A selector that matched prints how many elements it hit and exits 0. A selector the page read fine but that matched nothing also exits 0, because the call did what was asked and the count is the answer; the message says the syntax was fine so you look at the page, not the locator. A selector the page could not read at all exits 2, because that one is yours to correct and retrying will not change it.
+
+runner-cannot-highlight-selectors exits 2 and means the runner has no browser to draw on. no-answer exits 4: a highlight runs inside the page, so a page that is gone or mid-navigation does not answer at all rather than answering slowly.
+`;
+
+// src/commands/runner/guides/importPackage.txt
+var importPackage_default = `# Installing mid-session
+
+The package goes into the runner's live run, so a snippet or a selection can import it without a whole run to reinstall dependencies. The flag is --package-version because --version belongs to the CLI itself. The install resolves against your project's own dependencies, read from package.json, so it needs a run already going: there is no live run on a runner that has not run anything. npm's own refusal comes back verbatim on an exit 2, which is a name or a version to correct rather than something to retry.
+`;
+
+// src/commands/runner/guides/inspect.txt
+var inspect_default = `# Browser
+
+inspect answers one question about the live page and prints the answer on stdout by itself, so you can redirect or pipe it. \`page-html\` is simplified for a model to read rather than being the browser's exact markup, and --selector narrows it to one subtree. \`variable\` reads a top-level variable of the running workflow and prints it as JSON, which is how you see what your own code computed rather than what the page shows. Use it before reaching for exec: reading a value through a snippet means printing it and then fishing it back out of the console stream, which is two calls and a marker.
+
+One failure covers three causes, because a runner cannot tell them apart: no live page, no element matching the selector, no variable under that name. All three exit 2 and none clears by waiting, so read the message, which carries whatever the runner said. An unreachable runner exits 4 and is worth retrying; a runner that is not running at all exits 8 and is not.
+
+# Mobile
+
+element-html and page-html are a browser's shapes, and a mobile runner answers them with runner-is-not-a-browser. It answers session, contexts, page-source and elements instead, and variable works on both.
+
+session prints one summary line, ready or why not, because that line is the whole answer. contexts, page-source and elements print their answer as JSON on stdout, on its own, so you can pipe it (| jq .current, | jq .matches, | jq .pageSource) rather than getting a count with no way to see what was found.
+
+session is the one subcommand that never answers screen-needs-a-run: readiness is the question it exists to answer, so it reports ready (with the platform, device and session id), unreachable, ambiguous (more than one session is somehow live) or no-session. The other three need a live session first. screen-needs-a-run exits 2 and means no Appium session has started on this runner yet: run a flow that opens one, then inspect again. screen-not-ready exits 4 and means the session exists but did not answer this instant, or more than one is somehow live: retry once, and relaunch the runner if it persists.
+
+elements takes one of three ways to search: whole-pixel --x/--y on the device's own screen, the same coordinates a screenshot is measured in; --text, which matches exactly unless --partial is passed; or --selector, resolved the same way a screen object's own selector is, with --strategy naming how (xpath, ios-predicate or shadow; defaults to xpath). Prefer --selector when checking a selector you are about to write: it answers what that exact string resolves to, where --text and --x/--y only approximate it. The three do not mix: flags from more than one are refused before a runner is addressed. An unparseable selector answers invalid-selector, exit 2, distinctly from a selector that parsed fine but matched nothing, which answers an empty \`matches\` list, exit 0. --context on page-source or elements reads a context other than the current one, once contexts has told you which are available.
+
+A browser runner answers runner-is-not-mobile to session, contexts, page-source and elements, exit 2, since retrying never helps: launch with --name android or --name ios instead. runner-unreachable exits 4 and is worth retrying.
+`;
+
+// src/commands/runner/guides/keepalive.txt
+var keepalive_default = `# When to call it
+
+A runner is reaped after a period of inactivity, and every command that talks to the runner counts as activity, including a journal read. keepalive exists for the gap that creates: a harness that thinks, or waits on a human, for minutes between actions would otherwise come back to a pod that is gone. It resets the clock and tells you the runner is still there. It never launches a runner.
+
+It is a read with a cost: keeping the clock reset keeps a billed pod alive. Call it while you are genuinely still working, not on a timer you forget, and call \`qawolf runner terminate\` when you are done rather than leaving a pod to time out. A loop that keeps a runner alive and never stops it bills until someone notices.
+`;
+
+// src/commands/runner/guides/launch.txt
+var launch_default = `# Ids
+
+Runner ids are yours to choose and are scoped to your team, so agent-1 is a fine id. Launching an id that is already running attaches to that runner instead of starting and billing a second one, and the answer says which happened: read \`alreadyRunning\`. Reusing one id is therefore the cheap and safe pattern. The same id with a different --name is refused rather than silently ignored.
+
+launch takes its id from --id and never reads QAWOLF_RUNNER_ID. A bare \`qawolf runner launch\` invents a random id, bills a pod under it and stores it, so a harness that exported the variable and then launched without --id ends up with a pod it is not addressing. Pass --id whenever you have an id in mind.
+
+Launching an id that differs from QAWOLF_RUNNER_ID prints a warning on stderr naming both ids: the variable still outranks the directory default, so commands that omit --runner keep going to whatever it names, not the runner you just launched. That is expected when you launch an additional runner on purpose. Address that one with --runner rather than re-exporting the variable, which would repoint every other runner-less command too.
+
+# The page
+
+Either answer carries a \`url\`, which launch prints, as does a command that launched its own runner. It is a QA Wolf page showing what the runner is doing, where a person can also take over with their own mouse and keyboard. Hand it to a person who asks what your runner is up to. The page opens for anyone on the runner's team, however the runner was launched. There is nothing to see until the runner's first run starts its screen, so the page waits until then. You read the screen with \`screenshot\`, not with the page.
+
+# Browser or mobile
+
+--name also chooses between a browser and a mobile device: --name android or --name ios starts an Appium session instead of a browser. A command built for the other kind answers a failureReason naming the mismatch rather than doing something approximate: runner-is-not-mobile from inspect session, contexts, page-source and elements on a browser runner, and runner-is-not-a-browser from inspect element-html and page-html on a mobile one. Launch the right family up front rather than discovering it from a refusal mid-session.
+`;
+
+// src/commands/runner/guides/list.txt
+var list_default = `# What the list holds
+
+The list names the runners this directory has launched that are still running, and marks the one a command with no --runner would reach. It also includes the runner named by QAWOLF_RUNNER_ID even though this directory did not launch it, so a harness handed a runner sees it alongside the ones it started itself. Use the id column with --runner to address any of them; addressing one does not make it the default.
+
+Every runner is looked up before it is listed, so a runner that idled out is absent rather than reported. The lookup neither starts a runner nor resets an inactivity clock, which is what separates list from keepalive: listing tells you what is there and changes nothing. A lookup that cannot be answered fails the command rather than returning a shorter list, because a short list reads as the whole truth.
+
+Nothing is billed by listing, but everything in the list is billing. Terminate what you are done with.
+
+The table leaves out the page address, which beside a 63-character id outgrows a terminal. --json carries it as \`url\` on every runner:
+
+$ qawolf runner list --json | jq -r '.[] | [.id, .url] | @tsv'
+`;
+
+// src/commands/runner/guides/listRecordings.txt
+var listRecordings_default = "# Reading pages\n\n$ qawolf runner list-recordings --runner ci --json\n$ qawolf runner list-recordings --runner ci --recording-id <uuid> --json\n$ qawolf runner list-recordings --runner ci --page-token '<nextPageToken>' --json\n\nEach response is one page with `recordings` and an optional `nextPageToken`. Follow that token for more; the order is storage-key order, not newest-first. Entries include status, run ids, a stable platform `url`, and an expiring `videoUrl` when video is available. An empty lookup means the recording has not been published or does not exist. Abrupt runner loss may leave video unavailable. Keep the runner id for history lookups after termination clears the local default.\n";
+
+// src/commands/runner/guides/promoteSnapshot.txt
+var promoteSnapshot_default = `# Paths
+
+Use it when a run's image diff fails and the new screenshot is the one you want. Both paths are the ones the diff reported in its imageDiffArtifact run event, and both are named rather than positional, because two paths with one unlabelled is easy to get backwards and swapping them promotes the wrong image. They are paths inside the run's own screenshot storage, not files on your machine.
+
+snapshot-not-found exits 2 and means the run wrote no screenshot at that path, which nearly always means the paths did not come from a diff this run produced. Nothing is changed, so correcting the path and repeating is safe. Promoting twice is also safe, so an unreachable runner is worth retrying.
+`;
+
+// src/commands/runner/guides/record.txt
+var record_default = `# Recording
+
+Start a flow first so the runner has a screen, then start a manual capture and keep \`result.state.active.id\` from the \`record start --json\` answer to stop that capture:
+
+$ qawolf runner record start --runner ci --json
+$ qawolf runner record stop <recording-id> --runner ci
+$ qawolf runner record status --runner ci
+$ qawolf runner record auto on --runner ci
+
+Start generates a UUID unless you pass --recording-id <uuid>. If a start response is lost, the error includes that UUID: check \`record status\` and reuse the UUID when retrying. Stop always names a specific recording, so retrying it cannot stop a later capture. Manual recordings span runs and suppress automatic capture until stopped. The auto setting affects subsequent full runs. An active automatic recording ends with its run; \`record stop\` cannot interrupt it. If a stop publishes a recording with status "failed", the CLI exits 1 and still prints the manifest so callers can inspect it.
+
+Published recordings stay readable after the runner terminates, with \`qawolf runner list-recordings\`.
+`;
+
+// src/commands/runner/guides/run.txt
+var run_default = `# What travels
+
+run ships the flow file, everything it imports, and your package.json and tsconfig.json. Nothing else travels, so you can run from the root of a large project without sending it. The runner holds no copy of your project, so what runs is exactly what is on disk at that moment, uncommitted edits included.
+
+Imports are followed the same way a run from the QA Wolf app follows them: relative paths and tsconfig.json path aliases, resolving .ts and .js. An \`export ... from\` re-export is not followed, and neither is require(), so a barrel file does not pull in what it re-exports. A package.json has to be there, since the run reads its npm dependencies from it, and the files may carry at most 30 MiB in total. A missing file, a missing package.json and files over the cap are all refused before any runner is resolved or launched, so a typo costs nothing.
+
+After the first run on a runner, later runs send only the files whose content changed, so iterating on one flow costs a small request rather than the whole graph again. --json reports which happened in \`fileSync\`: delta or full. Nothing about this needs managing: the baseline lives in .qawolf/runner-files.json, a switch to another runner ignores it, and a runner that turns out not to hold what was claimed gets the whole set resent automatically.
+
+# Waiting for the outcome
+
+The call answers with a run id as soon as the run is accepted. The outcome is not in that answer; it is in the run-status stream, whose entries carry \`runId\`, \`status\` and an \`errorMessage\` when there is one.
+
+Pass --follow and let run wait for you. It reports the run's status, in progress, then passed or failed, and ends on the settled status. Exit 1 means the run did not pass. --logs, --run-events and --recorder-events mirror more streams into the follow, and each implies --follow on its own. The recorder is runner-wide rather than run-scoped, so --recorder-events carries whatever is recorded after an anchor taken just before submission. Whatever mirrors are on, the follow still ends on the status, never on them, so a run that prints nothing still ends the follow and a run that dies mid-sentence still reports how. Combining mirror flags interleaves their lines with nothing saying which stream a line came from: fine for eyeballs; when parsing, follow one stream at a time.
+
+To submit and come back later, poll with the same rule the CLI uses: \`status\` is in-progress while the run is going, and any other value means it has settled. \`events --follow\` does not end when the run settles, so it cannot be used to wait for one.
+
+$ qawolf runner run flows/checkout.flow.ts --json
+$ qawolf runner events run-status --run <runId> --tail 1 | jq -r '.status'
+
+# When the runner could not be reached
+
+If run reports that the runner could not be reached, that does not mean the run did not start. The runner may have accepted it and been too slow to answer, and resubmitting bills and journals a second run.
+
+There is no clean recovery. The journal lives on the same pod, so while the runner stays unreachable a run-status read fails the same way. Wait for the runner to answer again, then read run-status without --run and look at the newest \`runId\`. Nothing ties that id back to your submission, and a runner takes work from anyone addressing it, so treat the newest id as your run only if you know nothing else submits to this runner. An empty read is not proof the run did not start either: run returns the moment the run is accepted, and its first run-status entry may not be written yet. A resubmit always risks a second billed run, so prefer polling run-status a while longer, and only submit again once you are willing to accept that risk.
+
+# Running part of a flow
+
+--lines 12-40 runs those lines against the browser as it stands, so nothing is re-navigated and nothing is signed in again. Use it to iterate on a step without paying for the whole flow to reach it again.
+
+The two file paths are the thing to get right, because getting them backwards runs the wrong code and nothing reports it:
+- the positional is always the flow file. It is the run's entry point, and it is required for every run, selection or not.
+- --lines-file is where the lines live. It defaults to the positional, so pass it only when the range is in another file, typically a page object whose method you want to run against the instance your last run left alive.
+
+The lines-file has to be one of the files that travel, so it lives under the directory you run from. A range whose file is not collected is refused before a runner is addressed, naming the path.
+
+A --lines selection is the one call that does not need a run first. If the runner had no browser, one is started before your lines run, and the command says so on stderr. Those lines then ran against a fresh page rather than the one an earlier run left, which is worth reading before you act on what you see.
+
+# Environment variables
+
+A run takes one of two. --env-id names a QA Wolf environment by id or alias, the same reference \`qawolf flows\` takes as --env. --env-file .env gives the run the variables in a dotenv file, in the format \`qawolf flows pull\` writes. Passing both is refused: each gives the run its whole environment, so there is no order in which they would combine.
+
+A run with neither flag falls back to QAWOLF_ENVIRONMENT, the same variable \`qawolf flows\` reads, so one export covers both. The run says on stderr which environment it picked up, because those variables reach your flow's code and a run should never be given an environment silently. --env-id wins over it, and --env-file suppresses it, so a run reading a dotenv file is not handed a second environment on top.
+
+Prefer --env-id. QA Wolf reads and decrypts the environment itself, so the values never leave the server, nothing has to be pulled to disk first, and no size limit applies to them. It is the only way to run a flow whose environment holds something large, such as a session cookie.
+
+A run that sends its own variables with --env-file may carry at most 200 of them, each value at most 16 KiB. Names follow what a shell accepts, and QAWOLF_TEAM_ID is reserved because QA Wolf sets it from the key you authenticated with. All of that is refused before a runner is addressed, naming the variable at fault.
+`;
+
+// src/commands/runner/guides/screenshot.txt
+var screenshot_default = `# Reading the screen
+
+The image is a real JPEG on disk, decoded, because every coding harness can open an image file. Read it with whatever vision you have. --out - writes the JPEG bytes to stdout instead, on their own, for a caller that is a process rather than an agent: the confirmation, and the JSON line under --json, goes to stderr so nothing follows the image on stdout. A terminal on stdout is refused: redirect or pipe it.
+
+A runner has no screen until its first run, so until then screenshot exits 2. It never launches a runner. When you are about to act anyway, \`act --screenshot\` performs the action and returns the screen in one call.
+`;
+
+// src/commands/runner/guides/stopOrTerminate.txt
+var stopOrTerminate_default = `# Stopping a run or ending a runner
+
+Two different things, and the names are the only warning you get:
+- stop-run stops what the runner is executing and leaves the runner up, its browser on whatever page the run reached. The run settles as stopped rather than passed or failed. Use it to abandon a run and keep the browser you were working against.
+- terminate ends the runner and the pod with it. Everything on it is gone, and the next command under that id launches and bills a new one.
+
+Both succeed when there was nothing to do, and say which: \`wasRunning\` is false when no run was going, and when no runner was running. Neither is an error, so a retry needs no special handling. terminate never launches a runner in order to end it.
+`;
+
+// src/commands/runner/guides/workflow.md
+var workflow_default = "An interactive runner is a live pod with a browser or a mobile device in it. You launch one, look at it, act on it, run flows on it, and read what it recorded. Everything is a plain request to one host, so there is no connection to hold open. This guide covers what spans commands; each command's own help below covers the rest.\n\n## Which runner a command reaches\n\nCommands that target a runner find one in this order: `--runner`, then `QAWOLF_RUNNER_ID`, then the runner stored for the current directory, which `qawolf runner launch` sets. Setting the environment variable once is the most robust for a harness whose working directory may not be stable, with two catches:\n\n- `qawolf runner launch` is not in that order: it takes its id from `--id` and never reads `QAWOLF_RUNNER_ID`. Pass `--id` whenever you have an id in mind.\n- A runner id that is set is treated as found, whether or not anything is running under it. Exporting `QAWOLF_RUNNER_ID=agent-1` turns off the auto-launch described next: instead of starting `agent-1`, commands try to reach it and fail with exit code `8`, naming the id and saying the variable is what chose it. Launch that id once yourself and the rest follows.\n\nIf nothing names a runner, the commands that change something launch one and say so on stderr, naming it: `run`, `act` and `exec`. Read that announcement. The browser it just started is fresh: nothing has been run on it, nothing is signed in, and no page is open. Acting as though your earlier setup survived is the single most likely way to drive the wrong page.\n\nNo read command ever launches a runner. `screenshot`, `events` and `keepalive` tell you there is no runner rather than quietly billing one, and so does `terminate`.\n\n## The order that matters\n\nA freshly launched runner has no screen. The virtual desktop starts with the runner's first run and nothing else starts it, so until you have run something:\n\n- `screenshot` and `act` fail with exit code `2`, except `navigate`, which fails with exit code `1` (`action-failed`): it skips the screen but still needs the runner to have run something\n- `exec` fails with exit code `2`\n- `events recorder` reads as empty\n\nNone of that is a fault, and none of it clears on its own. Only `qawolf runner run <flow>` starts the screen. A bare navigate does not: it fails until the first run, however long you wait.\n\nSo the first thing you do to a new runner has to put a browser on it. That means a flow file and a `package.json` on disk, even if all you want is to drive the browser by hand; there is no \"just give me a screen\" call. Once one run has happened, the screenshot-and-act loop works for the rest of the runner's life. A `--lines` selection is the one call that does not need a run first.\n\n## Exit codes\n\nRetry on the exit code, not on the message text:\n\n- `4` is transient, with one exception. The screen is up but cannot serve this instant: restarting after a display-size change, or busy with another request. Retry in a second or two, and bound the retries. The exception is a command that changes something, where a `4` can instead mean the answer was lost with the work in flight. For `act` and `actions`, take a screenshot first and repeat only what the screen says did not happen. For `run`, poll `run-status` instead of submitting again, since a second submission risks a second billed run. For `exec`, check the effect the snippet was meant to have before running it again.\n- `6` means the work ran out of the time it is given.\n- `8` means there is no such runner. It was never launched, or it was terminated, or it idled out. Retrying never brings one back, so stop and launch the id or name one that is running. The message says which runner was meant and whether `--runner`, `QAWOLF_RUNNER_ID` or this directory's stored default chose it; read that line before you pick an id to launch.\n- `2` will not clear on its own. Nothing has run on this runner yet, so run a flow; or the runner has no browser at all, so launch with `--name playwright` instead; or the action belongs to the other runner family, so send `tap`, `swipe` or `fill` to a mobile runner and the browser actions to a browser runner. The message says which.\n\n`act`, `actions`, `run` and `exec` are the commands whose lost answer may still have taken effect.\n\n## End to end\n\nRun from a directory holding a flow and a `package.json`. The run is what starts the screen, so it is not optional even though the goal here is to drive by hand.\n\n```sh\nexport QAWOLF_API_KEY=...          # the only credential\nexport QAWOLF_RUNNER_ID=agent-1    # so no command below needs --runner\n\nqawolf runner launch --id agent-1 --json          # --id, not the variable; read .alreadyRunning and .url\nqawolf runner run flows/smoke.flow.ts --follow    # starts the screen; exit 1 if it failed\n\nqawolf runner act navigate --url https://example.com/login --screenshot step-1.jpg   # then read step-1.jpg yourself\nqawolf runner act click --button left --x 480 --y 260 --screenshot step-2.jpg\nqawolf runner act type --text \"someone@example.com\" --screenshot step-3.jpg\n\nqawolf runner inspect element-html --selector \"#email\"\nqawolf runner inspect variable --name cart | jq .total\n\nqawolf runner run flows/smoke.flow.ts --lines 12-40 --follow   # just those lines\nqawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'\nqawolf runner terminate\n```\n\nOn a mobile runner, launch with `--name android` or `--name ios`, and drive it with `tap`, `swipe`, `fill` and `type` instead of the browser actions.\n";
+
+// src/commands/runner/guides/index.ts
+var runnerGuides = {
+  act: formatGuide(act_default),
+  actions: formatGuide(actions_default),
+  events: formatGuide(events_default),
+  exec: formatGuide(exec_default),
+  highlightSelector: formatGuide(highlightSelector_default),
+  importPackage: formatGuide(importPackage_default),
+  inspect: formatGuide(inspect_default),
+  keepalive: formatGuide(keepalive_default),
+  launch: formatGuide(launch_default),
+  list: formatGuide(list_default),
+  listRecordings: formatGuide(listRecordings_default),
+  promoteSnapshot: formatGuide(promoteSnapshot_default),
+  record: formatGuide(record_default),
+  run: formatGuide(run_default),
+  screenshot: formatGuide(screenshot_default),
+  stopOrTerminate: formatGuide(stopOrTerminate_default)
+};
+var runnerWorkflowGuide = workflow_default;
+
 // src/commands/runner/actions.register.ts
 var actionsExamples = `
 Examples:
   $ qawolf runner actions '[{"type":"click","button":"left","x":480,"y":260},{"type":"type","text":"hello@example.com"},{"type":"keypress","keys":["Enter"]}]' --screenshot after-login.jpg
   $ echo '[{"type":"click","button":"left","x":1,"y":2},{"type":"type","text":"hi"}]' | qawolf runner actions -
   $ qawolf runner actions '[{"type":"click","button":"left","x":480,"y":260},{"type":"type","text":"hello"}]' --screenshot-mode each --screenshot step.jpg
-  $ qawolf runner actions '[{"type":"scroll","x":480,"y":260,"scroll_x":0,"scroll_y":600},{"type":"click","button":"left","x":120,"y":700}]' --continue-on-failure`;
+  $ qawolf runner actions '[{"type":"scroll","x":480,"y":260,"scroll_x":0,"scroll_y":600},{"type":"click","button":"left","x":120,"y":700}]' --continue-on-failure
+
+Mobile:
+  $ qawolf runner actions '[{"type":"tap","selector":"//*[@content-desc=\\"Email\\"]"},{"type":"type","text":"hello@example.com"},{"type":"tap","x":540,"y":1650}]' --screenshot after-login.jpg
+  $ qawolf runner actions '[{"type":"fill","selector":"name == \\"Postal code\\"","strategy":"ios-predicate","text":"94107"},{"type":"swipe","from":{"x":540,"y":1600},"to":{"x":540,"y":600}}]'`;
 function registerRunnerActionsCommand(runner, signals) {
-  declareCommandKind(runner.command("actions <sequence>"), "write").description("Perform a sequence of up to ten raw actions on a runner's screen in one request, as a JSON array of the same actions `runner act` takes. Use - to read the array from stdin. Actions run back to back, so batch only steps whose targets are on the screen you last saw, and end the sequence at the step that changes the page. Each result carries an effect: performed, not-performed, or unknown when the runner stopped answering and the action may have landed").option("--continue-on-failure", "Carry on past an action that reached the runner and did not take effect; a runner that cannot be reached or a screen that cannot serve still ends the sequence").option("--runner <id>", runnerFlagDescription).option("--screenshot <path>", "Save a JPEG of the screen after the last action to this file. With --screenshot-mode each, one file per action, with the action's index before the extension. - writes the final frame to stdout and moves the confirmation to stderr").addOption(new Option2("--screenshot-mode <mode>", "Defaults to final when --screenshot is given, none otherwise").choices([...screenshotModes])).addHelpText("after", actionsExamples).action((sequence, opts, command) => withAuthContext(signals, (ctx) => handleRunnerActions(ctx, {
+  declareCommandKind(runner.command("actions <sequence>"), "write").description("Perform a sequence of up to ten raw actions on a runner's screen in one request, as a JSON array of the same actions `runner act` takes. Use - to read the array from stdin. Actions run back to back, so batch only steps whose targets are on the screen you last saw, and end the sequence at the step that changes the page. Each result carries an effect: performed, not-performed, or unknown when the runner stopped answering and the action may have landed").option("--continue-on-failure", "Carry on past an action that reached the runner and did not take effect; a runner that cannot be reached or a screen that cannot serve still ends the sequence").option("--runner <id>", runnerFlagDescription).option("--screenshot <path>", "Save a JPEG of the screen after the last action to this file. With --screenshot-mode each, one file per action, with the action's index before the extension. - writes the final frame to stdout and moves the confirmation to stderr").addOption(new Option2("--screenshot-mode <mode>", "Defaults to final when --screenshot is given, none otherwise").choices([...screenshotModes])).addHelpText("after", actionsExamples).addHelpText("after", runnerGuides.actions).action((sequence, opts, command) => withAuthContext(signals, (ctx) => handleRunnerActions(ctx, {
     actions: sequence,
     continueOnFailure: opts.continueOnFailure === true,
     runner: opts.runner,
@@ -37203,7 +38037,7 @@ Examples:
   $ echo 'console.log(await page.title())' | qawolf runner exec -
   $ qawolf runner exec snippet.ts --file flows/checkout.flow.ts`;
 function registerRunnerExecCommand(runner, signals) {
-  declareCommandKind(runner.command("exec <file>"), "write").description("Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin").option("--file <path>", "File whose scope the snippet is evaluated in; it and the directory's other files travel with it").option("--runner <id>", runnerFlagDescription).addHelpText("after", execExamples).action((file, opts, command) => withAuthContext(signals, (ctx) => handleRunnerExec(ctx, { contextFile: opts.file, runner: opts.runner, source: file }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("exec <file>"), "write").description("Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin").option("--file <path>", "File whose scope the snippet is evaluated in; it and the directory's other files travel with it").option("--runner <id>", runnerFlagDescription).addHelpText("after", execExamples).addHelpText("after", runnerGuides.exec).action((file, opts, command) => withAuthContext(signals, (ctx) => handleRunnerExec(ctx, { contextFile: opts.file, runner: opts.runner, source: file }, runnerDeps(ctx)))(opts, command));
 }
 
 // src/domains/interactiveRunner/highlightSelector.ts
@@ -37278,7 +38112,7 @@ Examples:
   $ qawolf runner highlight-selector "#checkout" && qawolf runner screenshot
   $ qawolf runner highlight-selector`;
 function registerRunnerHighlightSelectorCommand(runner, signals) {
-  declareCommandKind(runner.command("highlight-selector [selector]"), "write").description("Highlight what a selector matches on a runner's live page, so the next screenshot shows it. Omit the selector to clear the highlight").option("--runner <id>", runnerFlagDescription).addHelpText("after", highlightExamples).action((selector, opts, command) => withAuthContext(signals, (ctx) => handleRunnerHighlightSelector(ctx, { runner: opts.runner, selector }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("highlight-selector [selector]"), "write").description("Highlight what a selector matches on a runner's live page, so the next screenshot shows it. Omit the selector to clear the highlight").option("--runner <id>", runnerFlagDescription).addHelpText("after", highlightExamples).addHelpText("after", runnerGuides.highlightSelector).action((selector, opts, command) => withAuthContext(signals, (ctx) => handleRunnerHighlightSelector(ctx, { runner: opts.runner, selector }, runnerDeps(ctx)))(opts, command));
 }
 
 // src/domains/interactiveRunner/importPackage.ts
@@ -37389,7 +38223,7 @@ Examples:
   $ qawolf runner import-package dayjs
   $ qawolf runner import-package dayjs --package-version 1.11.13`;
 function registerRunnerImportPackageCommand(runner, signals) {
-  declareCommandKind(runner.command("import-package <name>"), "write").description("Install a package into a runner's live run, so a snippet or a selection can import it").option("--package-version <version>", "Version to install", "latest").option("--runner <id>", runnerFlagDescription).addHelpText("after", importPackageExamples).action((name, opts, command) => withAuthContext(signals, (ctx) => handleRunnerImportPackage(ctx, { name, runner: opts.runner, version: opts.packageVersion }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("import-package <name>"), "write").description("Install a package into a runner's live run, so a snippet or a selection can import it").option("--package-version <version>", "Version to install", "latest").option("--runner <id>", runnerFlagDescription).addHelpText("after", importPackageExamples).addHelpText("after", runnerGuides.importPackage).action((name, opts, command) => withAuthContext(signals, (ctx) => handleRunnerImportPackage(ctx, { name, runner: opts.runner, version: opts.packageVersion }, runnerDeps(ctx)))(opts, command));
 }
 
 // src/core/interactiveRunner/inspectRequest.ts
@@ -37649,7 +38483,7 @@ Examples:
   $ qawolf runner inspect elements --text "Sign in" --partial
   $ qawolf runner inspect elements --selector "//android.widget.Button[@text='Sign in']"`;
 function registerRunnerInspectCommands(runner, signals) {
-  const inspect = runner.command("inspect").description("Read one thing off a runner's live page (browser) or Appium session (mobile)").addHelpText("after", inspectExamples);
+  const inspect = runner.command("inspect").description("Read one thing off a runner's live page (browser) or Appium session (mobile)").addHelpText("after", inspectExamples).addHelpText("after", runnerGuides.inspect);
   declareCommandKind(inspect.command("element-html"), "read").description("Print the HTML of the first element a selector matches").requiredOption("--selector <selector>", "Playwright selector to inspect").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspect(ctx, {
     flags: { name: undefined, selector: opts.selector },
     runner: opts.runner,
@@ -37943,8 +38777,8 @@ Examples:
   $ qawolf runner screenshot --out - > step-3.jpg
   $ qawolf runner screenshot --out - | my-vision-tool`;
 function registerRunnerInteractCommands(runner, signals) {
-  declareCommandKind(runner.command("screenshot"), "read").description("Save a JPEG of an interactive runner's screen to a file, or write it to stdout with --out -").option("--out <path>", "File to write the image to. - writes the JPEG bytes to stdout on their own and moves the confirmation, JSON included, to stderr", defaultScreenshotPath).option("--runner <id>", runnerFlagDescription).addHelpText("after", screenshotExamples).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerScreenshot(ctx, { out: opts.out, runner: opts.runner }, runnerDeps(ctx)))(opts, command));
-  declareCommandKind(runner.command("act <action>"), "write").description("Perform one raw action on a runner's screen. A browser runner takes click, double_click, scroll, move, drag, keypress, navigate and type; a mobile runner takes tap, swipe, fill and type. A browser runner answers mobile actions with action-not-supported-on-browser; a mobile runner answers the other browser actions with action-not-supported-on-mobile. Use - to read a whole action as JSON from stdin").option("--button <button>", "click: left, right, wheel, back or forward").option("--duration-ms <ms>", "swipe: how long it takes, up to 10000. Slow scrolls, fast flings").option("--from <x,y>", "swipe: the point it starts at").option("--keys <keys...>", "keypress: modifiers and the key, e.g. Control a").option("--path <json>", "drag: JSON array of points to drag through").option("--runner <id>", runnerFlagDescription).option("--screenshot <path>", "Also save a JPEG of the screen, taken after the action, to this file, in place of a separate screenshot. An action that did not take effect answers with one too. - writes it to stdout and moves the confirmation, JSON included, to stderr").option("--scroll-x <delta>", "scroll: horizontal wheel delta").option("--scroll-y <delta>", "scroll: vertical wheel delta").option("--selector <selector>", "tap or fill: the element to act on, as a screen object would find it. tap takes it in place of --x and --y").option("--strategy <strategy>", "how --selector is resolved: xpath (default), ios-predicate or shadow").option("--text <text>", "type: the text to type into what has focus. fill: the field's new value").option("--to <x,y>", "swipe: the point it ends at").option("--url <url>", "navigate: the http or https URL to go to").option("--x <pixels>", "click, tap and the like: x, in screenshot pixels").option("--y <pixels>", "click, tap and the like: y, in screenshot pixels").addHelpText("after", actExamples).action((action, opts, command) => withAuthContext(signals, (ctx) => handleRunnerAct(ctx, {
+  declareCommandKind(runner.command("screenshot"), "read").description("Save a JPEG of an interactive runner's screen to a file, or write it to stdout with --out -").option("--out <path>", "File to write the image to. - writes the JPEG bytes to stdout on their own and moves the confirmation, JSON included, to stderr", defaultScreenshotPath).option("--runner <id>", runnerFlagDescription).addHelpText("after", screenshotExamples).addHelpText("after", runnerGuides.screenshot).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerScreenshot(ctx, { out: opts.out, runner: opts.runner }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("act <action>"), "write").description("Perform one raw action on a runner's screen. A browser runner takes click, double_click, scroll, move, drag, keypress, navigate and type; a mobile runner takes tap, swipe, fill and type. A browser runner answers mobile actions with action-not-supported-on-browser; a mobile runner answers the other browser actions with action-not-supported-on-mobile. Use - to read a whole action as JSON from stdin").option("--button <button>", "click: left, right, wheel, back or forward").option("--duration-ms <ms>", "swipe: how long it takes, up to 10000. Slow scrolls, fast flings").option("--from <x,y>", "swipe: the point it starts at").option("--keys <keys...>", "keypress: modifiers and the key, e.g. Control a").option("--path <json>", "drag: JSON array of points to drag through").option("--runner <id>", runnerFlagDescription).option("--screenshot <path>", "Also save a JPEG of the screen, taken after the action, to this file, in place of a separate screenshot. An action that did not take effect answers with one too. - writes it to stdout and moves the confirmation, JSON included, to stderr").option("--scroll-x <delta>", "scroll: horizontal wheel delta").option("--scroll-y <delta>", "scroll: vertical wheel delta").option("--selector <selector>", "tap or fill: the element to act on, as a screen object would find it. tap takes it in place of --x and --y").option("--strategy <strategy>", "how --selector is resolved: xpath (default), ios-predicate or shadow").option("--text <text>", "type: the text to type into what has focus. fill: the field's new value").option("--to <x,y>", "swipe: the point it ends at").option("--url <url>", "navigate: the http or https URL to go to").option("--x <pixels>", "click, tap and the like: x, in screenshot pixels").option("--y <pixels>", "click, tap and the like: y, in screenshot pixels").addHelpText("after", actExamples).addHelpText("after", runnerGuides.act).action((action, opts, command) => withAuthContext(signals, (ctx) => handleRunnerAct(ctx, {
     flags: {
       button: opts.button,
       durationMs: opts.durationMs,
@@ -38157,11 +38991,11 @@ Examples:
   $ qawolf runner keepalive
   $ qawolf runner keepalive --runner ci`;
 function registerRunnerLifecycleCommands(runner, signals) {
-  declareCommandKind(runner.command("launch"), "write").description("Launch an interactive runner and make it this directory's default").option("--id <id>", "Id to launch under. Relaunching an id attaches to that runner").option("--name <family>", "Runner family to run, e.g. playwright").addHelpText("after", launchExamples).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerLaunch(ctx, { id: opts.id, name: opts.name }, runnerDeps(ctx)))(opts, command));
-  declareCommandKind(runner.command("list"), "read").description("List the runners running on your team").option("--here", "Only the runners this directory launched").addHelpText("after", listExamples2).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerList(ctx, { here: opts.here === true }, runnerDeps(ctx)))(opts, command));
-  declareCommandKind(runner.command("terminate"), "write").description("End an interactive runner, and the pod it runs on with it").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerTerminate(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
-  declareCommandKind(runner.command("stop-run"), "write").description("Stop what a runner is currently executing, leaving the runner up").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerStopRun(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
-  declareCommandKind(runner.command("keepalive"), "read").description("Reset a runner's inactivity clock, for a caller that pauses between actions").option("--runner <id>", runnerFlagDescription).addHelpText("after", keepaliveExamples).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerKeepalive(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("launch"), "write").description("Launch an interactive runner and make it this directory's default").option("--id <id>", "Id to launch under. Relaunching an id attaches to that runner").option("--name <family>", "Runner family to run, e.g. playwright").addHelpText("after", launchExamples).addHelpText("after", runnerGuides.launch).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerLaunch(ctx, { id: opts.id, name: opts.name }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("list"), "read").description("List the runners running on your team").option("--here", "Only the runners this directory launched").addHelpText("after", listExamples2).addHelpText("after", runnerGuides.list).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerList(ctx, { here: opts.here === true }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("terminate"), "write").description("End an interactive runner, and the pod it runs on with it").option("--runner <id>", runnerFlagDescription).addHelpText("after", runnerGuides.stopOrTerminate).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerTerminate(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("stop-run"), "write").description("Stop what a runner is currently executing, leaving the runner up").option("--runner <id>", runnerFlagDescription).addHelpText("after", runnerGuides.stopOrTerminate).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerStopRun(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(runner.command("keepalive"), "read").description("Reset a runner's inactivity clock, for a caller that pauses between actions").option("--runner <id>", runnerFlagDescription).addHelpText("after", keepaliveExamples).addHelpText("after", runnerGuides.keepalive).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerKeepalive(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
 }
 
 // src/domains/interactiveRunner/promoteSnapshot.ts
@@ -38218,7 +39052,7 @@ Examples:
   $ qawolf runner promote-snapshot --screenshot checkout-1-actual.png --baseline checkout-1.png
   $ qawolf runner events run-events --tail 20 | jq 'select(.type == "imageDiffArtifact")'`;
 function registerRunnerPromoteSnapshotCommand(runner, signals) {
-  declareCommandKind(runner.command("promote-snapshot"), "write").description("Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it").requiredOption("--screenshot <path>", "The screenshot to promote, as the image diff named it").requiredOption("--baseline <path>", "The baseline to replace, as the image diff named it").option("--runner <id>", runnerFlagDescription).addHelpText("after", promoteSnapshotExamples).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerPromoteSnapshot(ctx, {
+  declareCommandKind(runner.command("promote-snapshot"), "write").description("Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it").requiredOption("--screenshot <path>", "The screenshot to promote, as the image diff named it").requiredOption("--baseline <path>", "The baseline to replace, as the image diff named it").option("--runner <id>", runnerFlagDescription).addHelpText("after", promoteSnapshotExamples).addHelpText("after", runnerGuides.promoteSnapshot).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerPromoteSnapshot(ctx, {
     baselinePath: opts.baseline,
     runner: opts.runner,
     screenshotPath: opts.screenshot
@@ -38412,7 +39246,7 @@ Examples:
   $ qawolf runner events run-logs --run <runId> --follow
   $ qawolf runner events console --since 120 --json`;
 function registerRunnerEventsCommand(runner, signals) {
-  declareCommandKind(runner.command("events <stream>"), "read").description(`Print a runner's journal, one entry per line. QA Wolf writes ${knownJournalStreams.join(", ")}`).option("--follow", "Keep reading as new entries arrive. Reading counts as activity, so a follow left open keeps the runner alive and billing", false).option("--run <id>", "Restrict run-scoped streams to one run").option("--runner <id>", runnerFlagDescription).option("--since <sequence>", "Read entries after this sequence").option("--tail <count>", "Read only the newest <count> entries").option("--timeout <seconds>", "Give up following after this long. Reading keeps the runner alive, so a follow left open would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", eventsExamples).action((stream, opts, command) => withAuthContext(signals, (ctx) => handleRunnerEvents(ctx, {
+  declareCommandKind(runner.command("events <stream>"), "read").description(`Print a runner's journal, one entry per line. QA Wolf writes ${knownJournalStreams.join(", ")}`).option("--follow", "Keep reading as new entries arrive. Reading counts as activity, so a follow left open keeps the runner alive and billing", false).option("--run <id>", "Restrict run-scoped streams to one run").option("--runner <id>", runnerFlagDescription).option("--since <sequence>", "Read entries after this sequence").option("--tail <count>", "Read only the newest <count> entries").option("--timeout <seconds>", "Give up following after this long. Reading keeps the runner alive, so a follow left open would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", eventsExamples).addHelpText("after", runnerGuides.events).action((stream, opts, command) => withAuthContext(signals, (ctx) => handleRunnerEvents(ctx, {
     envelope: Boolean(command.optsWithGlobals().json),
     follow: opts.follow,
     run: opts.run,
@@ -38882,7 +39716,7 @@ Examples:
   $ qawolf runner run flows/checkout.flow.ts --lines 4-9 --lines-file pages/login.ts
   $ qawolf runner run flows/checkout.flow.ts --env-id staging`;
 function registerRunCommand(runner, signals) {
-  declareCommandKind(runner.command("run <flowFile>"), "write").description("Run a flow on an interactive runner, shipping the flow and what it imports").option("--follow", "Report the run's status until it settles: in progress, then passed or failed", false).option("--logs", "Stream every log line the run produces while following. Implies --follow", false).option("--run-events", "Stream the run's progress events as JSON lines while following. Implies --follow", false).option("--recorder-events", "Stream the browser actions the runner records as JSON lines while following, from an anchor taken just before submission: the recorder is runner-wide, not run-scoped. Implies --follow", false).option("--env-id <env>", "QA Wolf environment whose variables the run is given, by id or alias. Defaults to QAWOLF_ENVIRONMENT. QA Wolf reads and decrypts them itself, so they never leave the server and no size limit applies to them").option("--env-file <path>", "Dotenv file on this machine whose variables the run is given. Pass this or --env-id, not both").option("--lines <start-end>", "Run only these 1-indexed lines against the browser as it stands, instead of the whole flow from a fresh one").option("--lines-file <path>", "File the --lines range lives in. Defaults to <flowFile>; pass it only when the lines are in another file, such as a page object").option("--runner <id>", runnerFlagDescription).option("--timeout <seconds>", "Give up following after this long. Following keeps the runner alive, so a run that never settles would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", runExamples2).action((flowFile, opts, command) => withAuthContext(signals, (ctx) => handleRunnerRun(ctx, {
+  declareCommandKind(runner.command("run <flowFile>"), "write").description("Run a flow on an interactive runner, shipping the flow and what it imports").option("--follow", "Report the run's status until it settles: in progress, then passed or failed", false).option("--logs", "Stream every log line the run produces while following. Implies --follow", false).option("--run-events", "Stream the run's progress events as JSON lines while following. Implies --follow", false).option("--recorder-events", "Stream the browser actions the runner records as JSON lines while following, from an anchor taken just before submission: the recorder is runner-wide, not run-scoped. Implies --follow", false).option("--env-id <env>", "QA Wolf environment whose variables the run is given, by id or alias. Defaults to QAWOLF_ENVIRONMENT. QA Wolf reads and decrypts them itself, so they never leave the server and no size limit applies to them").option("--env-file <path>", "Dotenv file on this machine whose variables the run is given. Pass this or --env-id, not both").option("--lines <start-end>", "Run only these 1-indexed lines against the browser as it stands, instead of the whole flow from a fresh one").option("--lines-file <path>", "File the --lines range lives in. Defaults to <flowFile>; pass it only when the lines are in another file, such as a page object").option("--runner <id>", runnerFlagDescription).option("--timeout <seconds>", "Give up following after this long. Following keeps the runner alive, so a run that never settles would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", runExamples2).addHelpText("after", runnerGuides.run).action((flowFile, opts, command) => withAuthContext(signals, (ctx) => handleRunnerRun(ctx, {
     entryPoint: flowFile,
     envFile: opts.envFile,
     envId: opts.envId,
@@ -39071,7 +39905,7 @@ async function handleRunnerRecordings(ctx, options, deps) {
 
 // src/commands/runner/recording.register.ts
 function registerRunnerRecordingCommands(runner, signals) {
-  const record = runner.command("record").description("Control video recording on a Playwright runner");
+  const record = runner.command("record").description("Control video recording on a Playwright runner").addHelpText("after", runnerGuides.record);
   declareCommandKind(record.command("start"), "write").description("Start manual video capture across runs. Requires a ready screen and suppresses automatic capture until stopped").option("--recording-id <uuid>", "Recording UUID. Generated when omitted; reuse it when retrying this start").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecord(ctx, {
     command: { action: "start", recordingId: opts.recordingId },
     runner: opts.runner
@@ -39091,7 +39925,7 @@ function registerRunnerRecordingCommands(runner, signals) {
     command: { action: "auto", enabled: setting === "on" },
     runner: opts.runner
   }, runnerDeps(ctx)))(opts, command));
-  declareCommandKind(runner.command("list-recordings"), "read").description("Read a page of published video recordings, including after the runner terminates. Platform URLs persist; video URLs expire").option("--runner <id>", runnerFlagDescription).option("--recording-id <uuid>", "Look up one recording; an empty result means it is not published or does not exist").option("--page-token <token>", "Continue from nextPageToken returned by the previous page").action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecordings(ctx, {
+  declareCommandKind(runner.command("list-recordings"), "read").description("Read a page of published video recordings, including after the runner terminates. Platform URLs persist; video URLs expire").option("--runner <id>", runnerFlagDescription).option("--recording-id <uuid>", "Look up one recording; an empty result means it is not published or does not exist").option("--page-token <token>", "Continue from nextPageToken returned by the previous page").addHelpText("after", runnerGuides.listRecordings).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecordings(ctx, {
     runner: opts.runner,
     ...opts.recordingId === undefined ? {} : { recordingId: opts.recordingId },
     ...opts.pageToken === undefined ? {} : { pageToken: opts.pageToken }
@@ -39100,7 +39934,7 @@ function registerRunnerRecordingCommands(runner, signals) {
 
 // src/commands/runner/index.ts
 function registerRunnerCommand(program, signals) {
-  const runner = program.command("runner").description("Drive an interactive runner on the QA Wolf platform");
+  const runner = declareReferenceGuide(program.command("runner"), runnerWorkflowGuide).description("Drive an interactive runner on the QA Wolf platform");
   registerRunnerLifecycleCommands(runner, signals);
   registerRunCommand(runner, signals);
   registerRunnerEventsCommand(runner, signals);
@@ -39129,6 +39963,7 @@ function createProgram({
   registerInstallCommand(program, signals);
   registerRunnerCommand(program, signals);
   registerPublicApiCommands(program, signals);
+  registerHelpCommand(program);
   return program;
 }
 
@@ -39142,4 +39977,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=4535AB8728B9D01A64756E2164756E21
+//# debugId=A9F5B8A99DA7D0CB64756E2164756E21