docs(spec): FlowSchema terminal messages are every-terminal-run, not screen-flow-only (#9512) (#9548)

Since #9414, AutomationResult.successMessage/errorMessage are carried on
EVERY terminal flow run — execute()'s exit, both retryExecution() exits, and
the resume exit — not only screen-flow runs. Rewrite the JSDoc and
describe() text above FlowSchema.successMessage/errorMessage to say so
explicitly and to kill the screen-flow-only reading, which was the premise
of a route considered and rejected at #9414's triage (narrowing the contract
to screen-flow-only). Regenerate the two mirrored reference pages.

Text-only: authorable-surface.base.json is unchanged (re-verified via
check:generated, not inherited from the filer's claim).


Claude-Session: https://claude.ai/code/session_01Fs18A2DdXLVN2h8PaaFBcP

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-steve

.changeset/flow-terminal-messages-every-run-doc.md

@@ -0,0 +1,16 @@
+---
+"@objectstack/spec": patch
+---
+
+docs(spec): `FlowSchema.successMessage`/`errorMessage` describe themselves as carried on every terminal flow run, not screen-flow-only (#9512)
+
+Since #9414, the pair is set on `AutomationResult` for every terminal run —
+`execute()`'s exit, both `retryExecution()` exits, and the resume exit — not
+only on `screen`-flow runs. The JSDoc and `describe()` text above
+`successMessage`/`errorMessage` in `packages/spec/src/automation/flow.zod.ts`
+previously said "Terminal messages for `screen`-flow runs", which stayed the
+premise of a route considered and rejected at #9414's triage (narrowing the
+contract to screen-flow-only). Text-only: no schema shape, validation, or
+`authorable-surface.base.json` change. The two mirrored reference pages
+(`content/docs/references/automation/flow.mdx`,
+`content/docs/references/api/automation-api.mdx`) are regenerated to match.

content/docs/references/api/automation-api.mdx

@@ -88,8 +88,8 @@ const result = AutomationApiErrorCode.parse(data);
 | **name** | `string` | ✅ | Machine name |
 | **label** | `string` | ✅ | Flow label |
 | **description** | `string` | optional |  |
-| **successMessage** | `string` | optional | Toast shown when a screen flow completes (defaults to a generic "Done"). |
-| **errorMessage** | `string` | optional | Toast shown when a screen flow fails (defaults to the raw error). |
+| **successMessage** | `string` | optional | Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of a generic "Done". |
+| **errorMessage** | `string` | optional | Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of the raw error. |
 | **version** | `integer` | optional (default: `1`) | Version number |
 | **status** | `Enum<'draft' \| 'active' \| 'obsolete' \| 'invalid'>` | optional (default: `"draft"`) | Deployment status |
 | **template** | `never` | optional | [REMOVED] `flow.template` was removed in @objectstack/spec 17.0.0 (#3896 audit close-out) — no designer or engine path ever read it, so flagging a flow as a template/subflow did nothing. Delete the key. Shared logic is invoked via a subflow NODE referencing the flow by name. Run `os migrate meta --from 16` to rewrite existing sources automatically. |

content/docs/references/automation/flow.mdx

@@ -42,8 +42,8 @@ const result = FlowSchema.parse(data);
 | **name** | `string` | ✅ | Machine name |
 | **label** | `string` | ✅ | Flow label |
 | **description** | `string` | optional |  |
-| **successMessage** | `string` | optional | Toast shown when a screen flow completes (defaults to a generic "Done"). |
-| **errorMessage** | `string` | optional | Toast shown when a screen flow fails (defaults to the raw error). |
+| **successMessage** | `string` | optional | Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of a generic "Done". |
+| **errorMessage** | `string` | optional | Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of the raw error. |
 | **version** | `integer` | optional (default: `1`) | Version number |
 | **status** | `Enum<'draft' \| 'active' \| 'obsolete' \| 'invalid'>` | optional (default: `"draft"`) | Deployment status |
 | **template** | `never` | optional | [REMOVED] `flow.template` was removed in @objectstack/spec 17.0.0 (#3896 audit close-out) — no designer or engine path ever read it, so flagging a flow as a template/subflow did nothing. Delete the key. Shared logic is invoked via a subflow NODE referencing the flow by name. Run `os migrate meta --from 16` to rewrite existing sources automatically. |

packages/spec/src/automation/flow.zod.ts

@@ -616,14 +616,23 @@ export const FlowSchema = lazySchema(() => strictObject(
   description: z.string().optional(),
 
   /**
-   * Terminal messages for `screen`-flow runs. When the run reaches a terminal
-   * state, the UI flow-runner shows `successMessage` instead of a generic
-   * "Done" toast, and `errorMessage` instead of the raw error. Both are
-   * surfaced on the terminal {@link AutomationResult} (`successMessage` /
-   * `errorMessage`). Plain strings; `{var}` is NOT interpolated here.
+   * Terminal messages for the flow. Since #9414, carried on EVERY terminal
+   * run — `execute()`'s exit, both `retryExecution()` exits, and the resume
+   * exit — not only on `screen`-flow runs. The pair is set on the terminal
+   * {@link AutomationResult} (`successMessage` on success, `errorMessage` on
+   * failure) returned by any trigger route (e.g.
+   * `POST /api/v1/automation/:name/trigger`), whether or not a UI is
+   * listening; a `screen`-flow run additionally has the UI flow-runner show
+   * `successMessage` as a toast instead of a generic "Done", and
+   * `errorMessage` instead of the raw error. Reading this pair as
+   * screen-flow-only was the alternative considered and rejected at #9414's
+   * triage — narrowing the text would delete a declared, documented,
+   * console-consumed capability to make a bug disappear — so treat the
+   * screen-flow toast as one consumer, not the whole contract. Plain
+   * strings; `{var}` is NOT interpolated here.
    */
-  successMessage: z.string().optional().describe('Toast shown when a screen flow completes (defaults to a generic "Done").'),
-  errorMessage: z.string().optional().describe('Toast shown when a screen flow fails (defaults to the raw error).'),
+  successMessage: z.string().optional().describe('Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of a generic "Done".'),
+  errorMessage: z.string().optional().describe('Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of the raw error.'),
 
   /** Metadata & Versioning */
   version: z.number().int().default(1).describe('Version number'),