ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/code/spec_coverage.md

@@ -0,0 +1,73 @@
+# Spec Coverage Map
+
+*Last updated: 2026-06-07*
+
+---
+
+## Areas WITH specs (117 examples total)
+
+| Spec file | What it covers |
+|---|---|
+| `common/graphql/model/as_input_spec.rb` | `AsInput#as_input`, `Logic::Input.from_model`, `ContractorEntity::Update.from_model` |
+| `common/graphql/model/diff_service_spec.rb` | `DiffService#diff` — no-change, single prop, nested, root! exclusion |
+| `base/page/data_field_spec.rb` | `DataField.from_doc` dispatch, dirty tracking, `as_input` for PlainText/RichText/Select/People/Checklist, `Collection` get_by_type/get_by_name/dirty_inputs |
+| `concerns/fragment_definitions_spec.rb` | `FragmentDefinitions.assemble`, `register_namespace` cross-namespace discovery, `Fragment::Pages` integration |
+| `input/page/update_spec.rb` | `Input::Page::Update.from_model` — no-change nil, patchVer injection, publish flag, clientMutationId |
+| `input/search_conf_spec.rb` | `SearchConf` builder — all filter types, sort, query, `#with` parametrization, `as_json` |
+| `logic/assemble_fragments_spec.rb` | `BaseQuery#assemble_fragments` — single, recursive (PageFields→LocationNode), cycle safety, deduplication |
+| `model/page_union_spec.rb` | `Model::PageUnion.new` — `__typename` dispatch to Basic/Phased/fallback, opts forwarded |
+| `api_spec.rb` | Version constant smoke test |
+
+---
+
+## Areas WITHOUT specs (by design or deferred)
+
+### Query / Mutation / Payload / Builder classes
+No unit specs. These classes primarily wire DSL blocks to HTTP + response wrapping —
+meaningful tests require a live or stubbed GraphQL server. Integration testing via
+`tests/` scripts (manual) is the current approach.
+
+Includes: `Query::Page`, `Query::Pages`, `Query::Templates`, `Query::RegisterPreviewPages`,
+`Query::PageDelta`, all `Mutation::Page::*`, all `Payload::Page::*`, `Builder::Page`.
+
+**Gap severity: Low** — the classes are thin wrappers; bugs show up on integration.
+If stubs become practical, priority order: `Query::Page`, `Query::Pages`.
+
+### Compat layer
+No unit specs for `Compat::Pages`, `Compat::Registers`, `Compat::StageCollection`,
+`Compat::SearchResults`. These require either a live GraphQL connection or deep mocking.
+
+**Gap severity: Medium** — integration testing with the end-script repo (pending access)
+will cover this.
+
+### Model classes (stubs and pass-through)
+`Base::Page::Basic`, `Base::Page::Phased`, `Model::Page::Basic`, `Model::Page::Phased`,
+`Base::PreviewPage`, `Base::DeltaResult`, `Base::Page::DataField::TagField/Geo/Gauge/Date/Number`
+— these are mostly DSL declarations with no business logic. Not worth unit-testing.
+
+### Fragment definitions (GRAPHQL strings)
+`Fragment::PageFields`, `BasicPageFields`, `PhasedPageFields` — assembly is tested via
+`assemble_fragments_spec.rb`. Individual fragment content is validated in integration.
+
+### Input stubs
+`Input::DeltaInput`, `Input::Page::Archive`, `Input::Page::Unarchive`,
+`Input::Page::BuildFromTemplate`, `Input::Page::CreateFromTemplate` — simple passthrough
+classes. Worth adding if any logic is added.
+
+### Concerns
+`Concerns::DataFieldAccess`, `Concerns::PageCompat`, `Concerns::PhasedPageCompat` —
+tested indirectly via `data_field_spec.rb` and `page_union_spec.rb`.
+
+---
+
+## Recommended next specs (priority order)
+
+1. **`Input::Page::Update.from_model` with `dataFields`** — now that field changes are
+   included, add a test that dirty fields appear in `dataFields.updates`.
+   File: extend `spec/ecoportal/api/graphql/input/page/update_spec.rb`
+
+2. **`StageCollection`** — `stages[name]`, `stages.get_by_name`, `stages.ordered`.
+   File: `spec/ecoportal/api/graphql/compat/stage_collection_spec.rb`
+
+3. **`SearchConf` filter translation in Registers** — v2 `date_filter` lbound→gte.
+   File: `spec/ecoportal/api/graphql/compat/registers_spec.rb` (filter translation only)

data/.ai-assistance/code/workflow-command-guide.md

@@ -0,0 +1,438 @@
+# WorkflowCommand Porting Guide
+
+*For developers and Claude: porting old operations to the `executeWorkflowCommands` command bus.*
+
+---
+
+## Why This Exists
+
+Most template and page structural mutations go through `executeWorkflowCommands`.
+This is a single GraphQL mutation that accepts an ordered array of
+`WorkflowCommandInput` objects. There are no individual mutations for "add a stage",
+"rename a field", "add a select option", etc. — they all route through this one endpoint.
+
+Old scripts that manipulated template structure via the APIv2 REST layer or direct
+back-end access need to be ported to this command bus.
+
+---
+
+## The Command Bus Pattern
+
+One mutation. N commands per call. Commands execute in array order server-side.
+
+```ruby
+# Build individual commands
+cmd1 = Input::WorkflowCommand.build(:editPage,  name: 'Incident Report', icon: 'warning')
+cmd2 = Input::WorkflowCommand.build(:editStage, stageId: 's1_id', name: 'Initial Report')
+cmd3 = Input::WorkflowCommand.build(:editStage, stageId: 's2_id', name: 'Investigation')
+
+# Batch all three into one mutation call — more efficient than three separate calls
+payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
+  id:        template_id,
+  patch_ver: template.patchVer,   # fetch before mutating
+  commands:  [cmd1, cmd2, cmd3]
+)
+
+raise "Commands failed: #{payload.body.inspect}" unless payload.success?
+puts "New patchVer: #{payload.patchVer}"
+```
+
+### patchVer requirement
+
+`ExecuteWorkflowCommandsInput` requires `patchVer: Int!` (non-null). Always fetch the
+current page or template before sending commands:
+
+```ruby
+page = graphql.currentOrganization.page(id: page_id) do
+  id; patchVer
+end
+# ... build commands ...
+payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
+  id: page_id, patch_ver: page.patchVer, commands: cmds
+)
+```
+
+### Error handling
+
+```ruby
+payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
+  id: page_id, patch_ver: page.patchVer, commands: cmds
+)
+
+if payload.success?
+  puts "Done. New patchVer: #{payload.patchVer}"
+else
+  # payload.body → raw errors array from the server
+  warn "Workflow command failed: #{payload.body.inspect}"
+end
+```
+
+---
+
+## Complete Command Mapping Table
+
+Grouped by category. Every key listed here corresponds to one field in `WorkflowCommandInput`.
+All map to a Ruby sub-input module under `Input::WorkflowCommand::`.
+
+### Page-level
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Edit page metadata / settings | `editPage` | _(none required)_ | `name`, `icon`, `themeId`, `timeZone`, `counterEnabled`, `counterPrefix`, `counterPostfix`, `counter`, `showCreator`, `disableComments`, `enableDashboardImport`, `enableActionsOnFields`, `mobileEnabled`, `useSectionsOnMobile`, `showStrategyForRestrictedStages`, `showAssigneeNamesForRestrictedStages`, `showTaskDueDateForRestrictedStages`, `hideActivityStream`, `disableDirectPermissions`, `active`, `addLocationIds`, `removeLocationIds`, `addBaseTags`, `removeBaseTags`, `addOtherTags`, `removeOtherTags`, `addFolders`, `removeFolders`, `creatorEnabled`, `creatorEditable`, `creatorFlags` |
+| Edit page creator permissions | `editPageCreatorPermissions` | _(see schema)_ | various permission flags |
+
+### Stage structural
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Add a stage | `addStage` | `name`, `ordering` | `placeholderId` |
+| Remove a stage | `removeStage` | `stageId` | |
+| Rename / configure a stage | `editStage` | `stageId` | `name`, `description`, `lockAfterCompletion`, `disableDirectPermissions` |
+| Move a stage (reorder) | `moveStage` | `stageId`, `ordering` | |
+
+### Stage permissions
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Edit creator permissions (stage) | `editCreatorPermissions` | _(see schema)_ | |
+| Toggle restrict comment tagging | `editRestrictCommentTagging` | _(see schema)_ | |
+| Add user group to comment tagging | `addCommentTaggingUserGroup` | `userGroupId` | |
+| Remove user group from comment tagging | `removeCommentTaggingUserGroup` | `userGroupId` | |
+| Toggle restrict task assignment | `editRestrictTaskAssignment` | _(see schema)_ | |
+| Add user group to task assignment | `addTaskAssignmentUserGroup` | `userGroupId` | |
+| Remove user group from task assignment | `removeTaskAssignmentUserGroup` | `userGroupId` | |
+| Add a tag to a stage | `addStageTag` | `stageId`, `tag` | |
+| Remove a tag from a stage | `removeStageTag` | `stageId`, `tag` | |
+
+### Section
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Add a section (BasicPage / PhasedPage) | `addSection` | `layout` | `placeholderId` |
+| Remove a section (BasicPage) | `removeSection` | `sectionId` | |
+| Add a section to a stage | `addStageSection` | `stageId`, `layout` | `placeholderId` |
+| Remove a section from a stage | `removeStageSection` | `stageId`, `sectionId` | |
+| Edit section heading | `editSectionHeader` | `sectionId` | `header`, `leftHeader`, `rightHeader` |
+| Collapse section by default | `collapseSection` | `sectionId` | |
+| Expand section by default | `expandSection` | `sectionId` | |
+| Reorder sections | `reorderSection` | `sectionId`, `ordering` | |
+
+### Task
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Add a task to a stage | `addTask` | `stageId`, `taskType` | `placeholderId` |
+| Remove a task from a stage | `removeTask` | `stageId`, `taskId` | |
+| Set task due date config | `editTaskDue` | `stageId`, `taskId` | `dueInValue`, `dueInUnit`, `dueExcludeWeekends` |
+| Remove task due date config | `removeTaskDue` | `stageId`, `taskId` | |
+| Remove task priority level | `removeTaskPriorityLevel` | `stageId`, `taskId` | |
+| Edit required sign-offs | `editRequiredSignOffs` | `stageId`, `taskId` | `required`, `minimum` |
+| Edit reminder | `editReminder` | `stageId`, `taskId` | `enabled`, `value`, `unit` |
+
+### Strategy (default assignment)
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Add default assignment strategy | `addDefaultStrategy` | `stageId`, `taskId`, `strategy` | `placeholderId` |
+| Edit default strategy | `editDefaultStrategy` | `stageId`, `taskId`, `strategyId` | `strategy` |
+| Remove default strategy | `removeDefaultStrategy` | `stageId`, `taskId`, `strategyId` | |
+| Add user to direct default strategy | `addDefaultDirectStrategyUser` | `stageId`, `taskId`, `strategyId`, `userId` | |
+| Remove user from direct default strategy | `removeDefaultDirectStrategyUser` | `stageId`, `taskId`, `strategyId`, `userId` | |
+
+### Strategy (task assignment)
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Add task assignment strategy | `addStrategy` | `stageId`, `taskId`, `strategy` | `placeholderId` |
+| Edit task strategy | `editStrategy` | `stageId`, `taskId`, `strategyId` | `strategy` |
+| Remove task strategy | `removeStrategy` | `stageId`, `taskId`, `strategyId` | |
+| Add user to direct strategy | `addDirectStrategyUser` | `stageId`, `taskId`, `strategyId`, `userId` | |
+| Remove user from direct strategy | `removeDirectStrategyUser` | `stageId`, `taskId`, `strategyId`, `userId` | |
+
+### Strategy (operation)
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Add operation strategy | `addOperationStrategy` | `stageId`, `callbackId`, `operationId`, `strategy` | `taskId`, `placeholderId` |
+| Edit operation strategy | `editOperationStrategy` | `stageId`, `callbackId`, `operationId`, `strategyId` | `taskId`, `strategy` |
+| Remove operation strategy | `removeOperationStrategy` | `stageId`, `callbackId`, `operationId`, `strategyId` | `taskId` |
+| Add user to direct op strategy | `addOperationDirectStrategyUser` | `stageId`, `callbackId`, `operationId`, `strategyId`, `userId` | `taskId` |
+| Remove user from direct op strategy | `removeOperationDirectStrategyUser` | `stageId`, `callbackId`, `operationId`, `strategyId`, `userId` | `taskId` |
+
+### Callback + Operation
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Add a workflow callback | `addWorkflowCallback` | `stageId`, `triggerCondition` | `placeholderId`, `taskId`, `triggers`, `operations` |
+| Remove a callback | `removeCallback` | `stageId`, `callbackId` | `taskId` |
+| Edit callback trigger | `editTrigger` | `stageId`, `callbackId`, `triggers` | `taskId` |
+| Add an operation to a callback | `addOperation` | `stageId`, `callbackId`, `operation` | `taskId`, `placeholderId` |
+| Edit an operation | `editOperation` | `stageId`, `callbackId`, `operationId`, `operation` | `taskId` |
+| Remove an operation | `removeOperation` | `stageId`, `callbackId`, `operationId` | `taskId` |
+
+### Recipient (10 variants)
+
+| Goal | Command key | Required fields |
+|------|-------------|-----------------|
+| Add a specific user as recipient | `addRecipientUser` | `stageId`, `callbackId`, `operationId`, `userId` |
+| Remove a specific user | `removeRecipientUser` | `stageId`, `callbackId`, `operationId`, `userId` |
+| Add a people field as recipient source | `addRecipientPeopleField` | `stageId`, `callbackId`, `operationId`, `peopleFieldId` |
+| Remove a people field | `removeRecipientPeopleField` | `stageId`, `callbackId`, `operationId`, `peopleFieldId` |
+| Add a task config as recipient source | `addRecipientTaskConfig` | `stageId`, `callbackId`, `operationId`, `taskConfigId` |
+| Remove a task config | `removeRecipientTaskConfig` | `stageId`, `callbackId`, `operationId`, `taskConfigId` |
+| Add an action type as recipient source | `addRecipientActionType` | `stageId`, `callbackId`, `operationId`, `actionTypeId` |
+| Remove an action type | `removeRecipientActionType` | `stageId`, `callbackId`, `operationId`, `actionTypeId` |
+| Add a filter-based recipient | `addRecipientFilter` | `stageId`, `callbackId`, `operationId`, `filter` |
+| Remove a filter-based recipient | `removeRecipientFilter` | `stageId`, `callbackId`, `operationId`, `filter` |
+
+All 10 recipient commands also accept optional `taskId`.
+
+### Scheduled callbacks
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Add a scheduled callback | `addScheduledCallback` | `stageId`, `taskId` | `placeholderId`, `dueInValue`, `dueInUnit`, `dueExcludeWeekends`, `recurs`, `recursInValue`, `recursInUnit`, `recursExcludeWeekends`, `actions` |
+| Edit a scheduled callback | `editScheduledCallback` | `stageId`, `taskId`, `scheduledCallbackId` | `dueInValue`, `dueInUnit`, `recurs`, etc. |
+| Remove a scheduled callback | `removeScheduledCallback` | `stageId`, `taskId`, `scheduledCallbackId` | |
+| Add action to scheduled callback | `addScheduledCallbackAction` | `stageId`, `taskId`, `scheduledCallbackId`, `action` | |
+| Add action tag | `addActionTag` | `stageId`, `taskId`, `scheduledCallbackId`, `tag` | |
+| Remove action tag | `removeActionTag` | `stageId`, `taskId`, `scheduledCallbackId`, `tag` | |
+
+### Field structural
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Add a field to a stage section | `addField` | `fieldType`, `stageId`, `sectionId` | `placeholderId`, `label`, `column` |
+| Move a field to another section/position | `moveField` | `dataFieldId`, `sectionId` | `column`, `ordering` |
+| Remove a field | `removeField` | `dataFieldId` | |
+
+### Field configuration (12 type variants)
+
+All field configuration changes go through a single command key with a nested `byType` dispatcher:
+
+```ruby
+Input::WorkflowCommand.build(
+  :editFieldConfiguration,
+  data_field_id: 'FIELD_ID',
+  label:         'New Label',        # optional base-level
+  tooltip:       'Help text',        # optional base-level
+  description:   'Longer desc',     # optional base-level
+  hide_view:     false,              # optional base-level (snake_case → camelCase)
+  byType: {
+    people: {                        # one of the 12 type keys below
+      singular:       true,
+      personSchemaId: 'SCHEMA_ID'
+    }
+  }
+)
+```
+
+Base-level fields (all optional): `label`, `tooltip`, `description`, `hideView`,
+`hiddenOnMobile`, `enableActions`, `globalBinding`.
+
+The `byType` hash accepts exactly one of these keys:
+
+| `byType` key | Schema input | Configures |
+|---|---|---|
+| `plainText` | `WorkflowEditFieldConfigurationPlainTextInput` | `value`, `maxLength`, `embeddingEnabled`, `smartFillConfiguration` |
+| `richText` | `WorkflowEditFieldConfigurationRichTextInput` | `content`, `markdown`, `embeddingEnabled`, `smartFillConfiguration` |
+| `date` | `WorkflowEditFieldConfigurationDateInput` | `showTime`, `pastOnly`, `todayButton`, `smartFillConfiguration` |
+| `gauge` | `WorkflowEditFieldConfigurationGaugeInput` | `max` |
+| `select` | `WorkflowEditFieldConfigurationSelectInput` | `dataType`, `multiple`, `flat`, `other`, `otherDesc`, `smartFillConfiguration` |
+| `people` | `WorkflowEditFieldConfigurationPeopleInput` | `personSchemaId`, `singular`, `requiresNumber`, `attachMode`, `isMeButton`, `autoSelectMode`, `addViewableFields`, `removeViewableFields` |
+| `crossReference` | `WorkflowEditFieldConfigurationCrossReferenceInput` | `registerId`, `singleSelectMode`, `displayFields`, `hideCreate`, `hideAttach`, `hideDashboards` |
+| `imageGallery` | `WorkflowEditFieldConfigurationImageGalleryInput` | `layout`, `stretch`, `noPopup`, `hideOptions` |
+| `locationField` | `WorkflowEditFieldConfigurationLocationFieldInput` | `buttonText`, `minimumRequired`, `singleSelect`, `autoselectDefaultLocation`, `restrictByClassification`, `addAllowedClassifications`, `removeAllowedClassifications`, `addAllowedStructures`, `removeAllowedStructures` |
+| `contractorEntities` | `WorkflowEditFieldConfigurationContractorEntitiesInput` | `singular`, `requiresNumber`, `isMeButton`, `showApprovalStatus`, `grantPermissionsEnabled`, `adminAccess`, `regularAccess` |
+| `signature` | `WorkflowEditFieldConfigurationSignatureInput` | `color` |
+| `table` | `WorkflowEditFieldConfigurationTableInput` | `tableType`, `jurisdictionFieldRef`, various date/award fields |
+
+### Select options
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Add a select option | `addSelectFieldOption` | `dataFieldId`, `label` | `placeholderId`, `weight` |
+| Edit a select option | `editSelectFieldOption` | `dataFieldId`, `optionId` | `label`, `weight` |
+| Remove a select option | `removeSelectFieldOption` | `dataFieldId`, `optionId` | |
+
+### Gauge stops
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Add a gauge stop | `addGaugeFieldStop` | `dataFieldId`, `threshold`, `color` | `placeholderId` |
+| Edit a gauge stop | `editGaugeFieldStop` | `dataFieldId`, `stopId` | `threshold`, `color` |
+| Remove a gauge stop | `removeGaugeFieldStop` | `dataFieldId`, `stopId` | |
+
+### Linked fields
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Add a linked field config | `addLinkedFieldConfig` | `dataFieldId`, `sourceFieldKey`, `crossReferenceId` | `attachedMode` |
+| Edit a linked field config | `editLinkedFieldConfig` | `dataFieldId`, `linkedFieldConfigId` | `sourceFieldKey` |
+| Remove a linked field config | `removeLinkedFieldConfig` | `dataFieldId`, `linkedFieldConfigId` | |
+
+### Forces and bindings (advanced)
+
+| Goal | Command key | Required fields | Optional fields |
+|------|-------------|-----------------|-----------------|
+| Add a force | `addForce` | `name`, `script` | `placeholderId` |
+| Remove a force | `removeForce` | `forceId` | |
+| Edit a force | `editForce` | `forceId` | `name`, `script` |
+| Reorder forces | `reorderForces` | `forceIds` | |
+| Add a binding | `addBinding` | `forceId`, `fieldId`, `name` | `placeholderId` |
+| Edit a binding | `editBinding` | `forceId`, `bindingId` | `fieldId`, `name` |
+| Remove a binding | `removeBinding` | `forceId`, `bindingId` | |
+| Add linked helper | `addLinkedHelper` | _(see schema)_ | |
+| Edit linked helper | `editLinkedHelper` | _(see schema)_ | |
+| Remove linked helper | `removeLinkedHelper` | _(see schema)_ | |
+
+---
+
+## Usage Examples
+
+### 1. Rename a stage
+
+```ruby
+page = graphql.currentOrganization.page(id: page_id) { id; patchVer }
+
+payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
+  id:        page_id,
+  patch_ver: page.patchVer,
+  commands:  [
+    Input::WorkflowCommand.build(:editStage, stageId: stage_id, name: 'Investigation Phase')
+  ]
+)
+raise payload.body.inspect unless payload.success?
+```
+
+### 2. Add a workflow callback (send notification on stage submit)
+
+```ruby
+page = graphql.currentOrganization.page(id: page_id) { id; patchVer }
+
+payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
+  id:        page_id,
+  patch_ver: page.patchVer,
+  commands:  [
+    Input::WorkflowCommand.build(
+      :addWorkflowCallback,
+      stageId:          stage_id,
+      triggerCondition: 'on_stage_complete'
+    )
+  ]
+)
+raise payload.body.inspect unless payload.success?
+```
+
+### 3. Edit page icon and counter format
+
+```ruby
+page = graphql.currentOrganization.page(id: page_id) { id; patchVer }
+
+payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
+  id:        page_id,
+  patch_ver: page.patchVer,
+  commands:  [
+    Input::WorkflowCommand.build(
+      :editPage,
+      icon:           'clipboard',
+      counterEnabled: true,
+      counterPrefix:  'INC-',
+      counterPostfix: ''
+    )
+  ]
+)
+raise payload.body.inspect unless payload.success?
+```
+
+### 4. Edit a field label and tooltip
+
+```ruby
+page = graphql.currentOrganization.page(id: page_id) { id; patchVer }
+
+payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
+  id:        page_id,
+  patch_ver: page.patchVer,
+  commands:  [
+    Input::WorkflowCommand.build(
+      :editFieldConfiguration,
+      data_field_id: field_id,
+      label:         'Incident Description',
+      tooltip:       'Describe what happened, where, and who was involved'
+    )
+  ]
+)
+raise payload.body.inspect unless payload.success?
+```
+
+### 5. Add a select field option
+
+```ruby
+page = graphql.currentOrganization.page(id: page_id) { id; patchVer }
+
+payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
+  id:        page_id,
+  patch_ver: page.patchVer,
+  commands:  [
+    Input::WorkflowCommand.build(
+      :addSelectFieldOption,
+      dataFieldId: field_id,
+      label:       'Under Review',
+      weight:      50
+    )
+  ]
+)
+raise payload.body.inspect unless payload.success?
+```
+
+### 6. Configure a people field (singular, person schema)
+
+```ruby
+page = graphql.currentOrganization.page(id: page_id) { id; patchVer }
+
+payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
+  id:        page_id,
+  patch_ver: page.patchVer,
+  commands:  [
+    Input::WorkflowCommand.build(
+      :editFieldConfiguration,
+      data_field_id: field_id,
+      byType: {
+        people: {
+          singular:       true,
+          personSchemaId: person_schema_id,
+          attachMode:     'ATTACH_ONLY'
+        }
+      }
+    )
+  ]
+)
+raise payload.body.inspect unless payload.success?
+```
+
+### Batching multiple commands (efficiency)
+
+Commands are ordered — the server executes them in sequence. Batch unrelated or
+sequential changes into a single mutation call to reduce round-trips and avoid
+intermediate patchVer staleness:
+
+```ruby
+page = graphql.currentOrganization.page(id: page_id) { id; patchVer }
+
+cmds = [
+  Input::WorkflowCommand.build(:editPage,  name: 'Safety Incident Report', icon: 'warning'),
+  Input::WorkflowCommand.build(:editStage, stageId: s1, name: 'Initial Report'),
+  Input::WorkflowCommand.build(:editStage, stageId: s2, name: 'Investigation'),
+  Input::WorkflowCommand.build(:editStage, stageId: s3, name: 'Close-out'),
+  Input::WorkflowCommand.build(:addSelectFieldOption, dataFieldId: severity_field, label: 'Critical', weight: 1),
+  Input::WorkflowCommand.build(:addSelectFieldOption, dataFieldId: severity_field, label: 'High',     weight: 2),
+]
+
+payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
+  id:        page_id,
+  patch_ver: page.patchVer,
+  commands:  cmds
+)
+raise "Commands failed: #{payload.body.inspect}" unless payload.success?
+puts "Applied #{cmds.size} commands. New patchVer: #{payload.patchVer}"
+```