docs: action disabled/errorMessage/undoable + predicate scope + object-form screen wizard (#2007)

Fills hand-written doc + authoring-skill gaps for capabilities that shipped but
were undocumented:

- actions.mdx: add `errorMessage`/`undoable` to the field table and feedback
  list; add an "Evaluation context" subsection (predicates are bare CEL against
  the record; `record.<field>` resolves identically on every surface; narrower
  scope than record-alert's os.*); warn against `${…}`/`{…}`-wrapped predicates.
- flow.mdx: document the `screen` node's object-form mode (`objectName`/`mode`/
  `recordId`/`defaults`/`idVariable`) and the atomic parent+child save / id
  rebind that powers multi-step object-form wizards.
- skills/objectstack-ui: document `disabled` (CEL, greys vs `visible` hides),
  `errorMessage`, `undoable`, and the bare-CEL `record.*` predicate convention,
  with a worked Reassign example.

Docs/skill only; no shipped-package changes.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: os-zhuang

.changeset/docs-action-predicates-objectform-wizard.md

@@ -0,0 +1,9 @@
+---
+---
+
+docs: document action `disabled`/`errorMessage`/`undoable`, the action
+predicate evaluation context (bare CEL against `record`, consistent across
+surfaces), and the `screen` node's `object-form` wizard mode
+(`objectName`/`mode`/`defaults`/`idVariable` + atomic child persistence).
+Also fills the same gaps in the `objectstack-ui` authoring skill. Docs/skill
+only — no shipped-package changes.

content/docs/guides/metadata/flow.mdx

@@ -206,6 +206,36 @@ rather than evaluating an arbitrary JavaScript string:
 }
 ```
 
+**Screen (object form):**
+
+A `screen` node normally renders a flat `fields` list. Set `config.objectName`
+to instead render an object's **entire** create/edit form — including any
+master-detail child grids (`inlineEdit`) — as one wizard step. The client
+renders the object form and, on save, **persists the record itself** (parent +
+inline children atomically); the flow then resumes with the new record's id
+bound to `config.idVariable` so a later step can reference it.
+
+```typescript
+{
+  id: 'new_opportunity',
+  type: 'screen',
+  label: 'Opportunity Details',
+  config: {
+    objectName: 'opportunity',         // render this object's full form
+    mode: 'create',                    // 'create' (default) | 'edit'
+    // recordId: '{account_id}',        // required for mode: 'edit'
+    defaults: {                        // pre-filled values (interpolated)
+      account: '{account_id}',
+      stage: 'prospecting',
+    },
+    idVariable: 'opportunity_id',      // bind the saved record's id for later steps
+  },
+}
+```
+
+This is how a single flow walks the user through several full object forms in
+sequence (e.g. lead → account → opportunity), each step saving its own record.
+
 ## Structured control flow (ADR-0031)
 
 `loop`, `parallel`, and `try_catch` are **structured control-flow constructs** —

content/docs/protocol/objectui/actions.mdx

@@ -180,6 +180,8 @@ interface Action {
   // UX
   confirmText?: string;         // Confirmation message before execution
   successMessage?: string;      // Toast shown after success
+  errorMessage?: string;        // Toast shown on failure (overrides the raw error)
+  undoable?: boolean;           // Offer an Undo affordance after a single-record update succeeds
   refreshAfter?: boolean;       // Reload the view after execution (default false)
   resultDialog?: ResultDialog;  // One-shot reveal of API response values
   shortcut?: string;            // Keyboard shortcut, e.g. "Ctrl+S"
@@ -247,6 +249,23 @@ target: /api/orders/ship
 disabled: "record.status != 'paid'"
 ```
 
+<Callout type="warn">
+Predicates are **bare CEL** — `record.status == 'paid'`, not `${record.status == 'paid'}` and not `{record.status} == 'paid'` (in CEL, `{…}` is a map literal). A `${…}`-wrapped or brace-wrapped predicate is not evaluated as a boolean.
+</Callout>
+
+#### Evaluation context
+
+Action predicates evaluate against the **record the action is attached to**. Both `record.<field>` and the bare field name resolve to the current record's value:
+
+```yaml
+disabled: "record.status == 'converted'"   # preferred — works on every surface
+disabled: "status == 'converted'"          # bare field — also resolves to the record
+```
+
+Prefer the `record.<field>` form: it reads unambiguously and resolves identically on **every** surface an action renders (`record_header`, `record_more`, `list_item`, related lists). The bare-field form is supported for brevity but is easy to confuse with a local variable.
+
+This is a narrower scope than [record-alert](/docs/protocol/objectui/record-alert) conditions (which also expose `os.user` / `os.org` / `os.env`) — action predicates see the record only.
+
 ## Confirmation & Feedback
 
 Actions express confirmation and feedback through dedicated string fields — there is no nested confirm-dialog object with `requireTyping`/`confirmLabel`.
@@ -265,10 +284,25 @@ refreshAfter: true
 ```
 
 - `confirmText` — message shown in a confirm dialog before the action runs.
-- `successMessage` — toast shown after a successful run.
+- `successMessage` — toast shown after a successful run. When omitted the UI shows a generic "Action completed" toast, so set this for any action whose outcome isn't self-evident.
+- `errorMessage` — toast shown when the action fails; overrides the raw server error with author-controlled copy.
+- `undoable` — for a single-record update action, offer an **Undo** affordance in the success toast (and via `Ctrl+Z`). The runtime captures the record's prior values before the write and restores them on undo. Only meaningful for reversible single-record mutations.
 - `refreshAfter` — reload the current view after success.
 - `mode` — a semantic hint (`create` / `edit` / `delete` / `custom`) the UI uses to pick confirm copy and default variants.
 
+```yaml
+# A reversible owner reassignment: custom success/error copy + Undo
+name: reassign_lead
+label: Reassign Lead
+type: api
+target: lead
+params:
+  - { field: assigned_to, required: true }
+undoable: true
+successMessage: Lead reassigned.
+errorMessage: Couldn't reassign this lead — try again.
+```
+
 ### Result Dialog (one-shot reveals)
 
 For API actions that return a value the user must copy **now** (a freshly minted secret, TOTP URI, or backup codes), `resultDialog` renders the response in an acknowledge-only dialog instead of a toast:

skills/objectstack-ui/SKILL.md

@@ -1088,11 +1088,35 @@ Register them under `defineStack({ actions: [...] })`.
 | `list_toolbar`   | Bulk action on selected rows (`input.selectedIds`) |
 | `global`         | Global action launcher (utility bar) |
 
-### Visibility & Confirmation
+### Visibility, Disable & Feedback
 
-Use `visible` (CEL predicate, prefer the `P\`...\`` tagged template) to
-gate the action against the current record. Set `confirmText` for any
-destructive or irreversible operation.
+- `visible` — CEL predicate (prefer the `P\`...\`` tagged template); when false the action is **hidden**.
+- `disabled` — `boolean` **or** a CEL predicate; when true the action **shows but greys out**. Use this (not `visible`) when the action should stay discoverable but locked in the current state.
+- `confirmText` — set for any destructive or irreversible operation.
+- `successMessage` / `errorMessage` — author-controlled toast copy on success / failure. Always set `successMessage` for non-obvious outcomes; without it the UI shows a generic "Action completed" toast.
+- `undoable: true` — on a single-record update, offers an **Undo** in the success toast (and `Ctrl+Z`); the runtime snapshots prior values and restores them.
+
+Predicates are **bare CEL** — `record.status == "converted"`, evaluated against
+the current record. `record.<field>` resolves identically on every surface
+(`record_header`, `list_item`, …); prefer it over the bare-field form. Never
+wrap a predicate in `${…}` or `{…}` braces (see `objectstack-formula`).
+
+```typescript
+export const ReassignLeadAction: Action = {
+  name: 'reassign_lead',
+  label: 'Reassign Lead',
+  objectName: 'lead',
+  type: 'api',
+  target: 'lead',
+  locations: ['record_header', 'list_item'],
+  // Greys out (stays visible) once the lead is converted:
+  disabled: P`record.status == "converted"`,
+  params: [{ field: 'assigned_to', required: true }],
+  undoable: true,                 // success toast offers Undo; Ctrl+Z works too
+  successMessage: 'Lead reassigned.',
+  errorMessage: "Couldn't reassign this lead — try again.",
+};
+```
 
 ### Examples