ecoportal-api-graphql 1.3.17 → 2.2.1

data/lib/ecoportal/api/graphql/fragment/pages/common_page_union.rb

@@ -61,6 +61,7 @@ module Ecoportal
             fragment stageAttrs on Stage {
               id @skip(if: $only_content)
               name
+              tags
               ...sectionsFragment
               active
               started
@@ -85,6 +86,7 @@ module Ecoportal
               name
               uid
               locations { ...locationNode }
+              baseTags  @include(if: $content)
               otherTags @include(if: $content)
               timeZone
               updatedAt { dateTime        }
@@ -92,6 +94,16 @@ module Ecoportal
               creator   { name email      }
               state
               archived
+              # Cross-version template identity. `template` is non-null only on template pages
+              # (`BasePageInterface.template: Template`), so this stays nil for records.
+              # `templateContainerUid` is the SERIES key: many versions may carry the same uid,
+              # but only one may be published (`active: true`) per organization at a time —
+              # publishing another with the same uid unpublishes the incumbent. See
+              # the repo's internal docs.
+              template @skip(if: $only_content) {
+                templateContainerUid
+                active
+              }
             }
 
             fragment sectionsFragment on Stage {
@@ -119,6 +131,16 @@ module Ecoportal
               __typename
               id                @skip(if: $only_content)
               label
+              # Field-configuration `description` (the hidden per-field note). Read-only from
+              # here — the ONLY writer is the `editFieldConfiguration` workflow command
+              # (`WorkflowEditFieldConfigurationInput.description`); `DataFieldInput` and its
+              # per-type members carry no description, so `updatePage` cannot set it.
+              #
+              # Integrations use it as a pseudo external-id on fields (we do so on templates;
+              # customers do so on page instances — confirmed working on instances with a
+              # non-superuser service account, 2026-07-31). Fetched by default so those
+              # integrations can read it back.
+              description       @skip(if: $only_content)
               genomeSignature   @skip(if: $only_content)
               deindex           @include(if: $content)
               linkedFieldConfig @skip(if: $only_content) {
@@ -232,6 +254,7 @@ module Ecoportal
             fragment fileField on File {
               required @skip(if: $only_content)
               items    @include(if: $content) {
+                id
                 fileContainer { ...fileContainerAttrs }
               }
             }

data/lib/ecoportal/api/graphql/fragment/permissions.rb

@@ -0,0 +1,96 @@
+module Ecoportal
+  module API
+    class GraphQL
+      class Fragment
+        # Selects every canXXX permission on the Permissions type, spreading :AuthorizationResult
+        # ({ value message }) for each. Requires the :AuthorizationResult fragment to be assembled
+        # alongside (Fragment.assemble(:Permissions, :AuthorizationResult)).
+        fragment :Permissions, <<~GRAPHQL
+          fragment Permissions on Permissions {
+            actionCanCreateStandalone { ...AuthorizationResult }
+            actionCanIndex { ...AuthorizationResult }
+            alertNotificationCanAccessBroadcastNotifications { ...AuthorizationResult }
+            alertNotificationCanCreate { ...AuthorizationResult }
+            alertNotificationCanIndex { ...AuthorizationResult }
+            canAccessAdminTools { ...AuthorizationResult }
+            canAccessPeopleManager { ...AuthorizationResult }
+            canDeleteActionCategories { ...AuthorizationResult }
+            canIndex { ...AuthorizationResult }
+            canListAttachablePersonMembers { ...AuthorizationResult }
+            canManageActionCategories { ...AuthorizationResult }
+            canManageStandaloneActionsPermissions { ...AuthorizationResult }
+            canResetActionsCounter { ...AuthorizationResult }
+            canUpload { ...AuthorizationResult }
+            contractorEntityCanAccessContractorManager { ...AuthorizationResult }
+            contractorEntityCanAttach { ...AuthorizationResult }
+            contractorEntityCanCreate { ...AuthorizationResult }
+            contractorEntityCanDestroy { ...AuthorizationResult }
+            contractorEntityCanEdit { ...AuthorizationResult }
+            contractorEntityCanEditLinkedUsers { ...AuthorizationResult }
+            contractorEntityCanIndex { ...AuthorizationResult }
+            contractorEntityCanManageParentContractors { ...AuthorizationResult }
+            contractorEntityCanManageSubcontractors { ...AuthorizationResult }
+            crossReferenceReportsCanIndex { ...AuthorizationResult }
+            dashboardCanManage { ...AuthorizationResult }
+            dataSetsCanIndex { ...AuthorizationResult }
+            dataSpaceCanShow { ...AuthorizationResult }
+            dataViewsCanIndex { ...AuthorizationResult }
+            emailReportCanConfigureSmartReport { ...AuthorizationResult }
+            filesCanIndex { ...AuthorizationResult }
+            filesCanUpload { ...AuthorizationResult }
+            generatedPageFilterCanCreate { ...AuthorizationResult }
+            generatedPageFilterCanUseSmartQuery { ...AuthorizationResult }
+            hasFileAbilityToDownload { ...AuthorizationResult }
+            locationClassificationsCanCreate { ...AuthorizationResult }
+            locationClassificationsCanUpdate { ...AuthorizationResult }
+            locationStructuresCanAccess { ...AuthorizationResult }
+            locationStructuresCanAdministrate { ...AuthorizationResult }
+            locationStructuresCanAiGenerateStructure { ...AuthorizationResult }
+            locationStructuresCanCreate { ...AuthorizationResult }
+            locationStructuresCanManage { ...AuthorizationResult }
+            locationStructuresCanManageSftpIntegration { ...AuthorizationResult }
+            locationStructuresCanPublish { ...AuthorizationResult }
+            locationStructuresCanRead { ...AuthorizationResult }
+            locationStructuresCanScheduleUpdate { ...AuthorizationResult }
+            locationStructuresCanUpdate { ...AuthorizationResult }
+            organizationCanViewSettings { ...AuthorizationResult }
+            pageAiSummaryCanAccess { ...AuthorizationResult }
+            pageCanListDrafts { ...AuthorizationResult }
+            pageCanRestore { ...AuthorizationResult }
+            pageCanUseDrafts { ...AuthorizationResult }
+            personSchemaCanAccessManager { ...AuthorizationResult }
+            publicTemplatesCanCopyLink { ...AuthorizationResult }
+            publicTemplatesCanIndex { ...AuthorizationResult }
+            publicTemplatesCanListEntries { ...AuthorizationResult }
+            publicTemplatesCanManage { ...AuthorizationResult }
+            registerCanAccessRegisterTools { ...AuthorizationResult }
+            registerCanCreate { ...AuthorizationResult }
+            registerCanLimitTemplates { ...AuthorizationResult }
+            scimIntegrationCanAddCodeHooks { ...AuthorizationResult }
+            scimIntegrationCanCreate { ...AuthorizationResult }
+            scimIntegrationCanDestroy { ...AuthorizationResult }
+            scimIntegrationCanGenerateApiKey { ...AuthorizationResult }
+            scimIntegrationCanIndex { ...AuthorizationResult }
+            scimIntegrationCanShow { ...AuthorizationResult }
+            scimIntegrationCanShowLogs { ...AuthorizationResult }
+            scimIntegrationCanUpdate { ...AuthorizationResult }
+            spatialCanUpdateLocationNodeGeojson { ...AuthorizationResult }
+            structuresCanIndex { ...AuthorizationResult }
+            templateCanRestore { ...AuthorizationResult }
+            userAccessLogsCanShow { ...AuthorizationResult }
+            userCanAccessAdminArea { ...AuthorizationResult }
+            userCanAccessPageCreationTools { ...AuthorizationResult }
+            visitorLogCanAdminCheckIn { ...AuthorizationResult }
+            visitorLogCanEdit { ...AuthorizationResult }
+            visitorLogCanManage { ...AuthorizationResult }
+            visitorLogCanShow { ...AuthorizationResult }
+            visitorManagementCanAccessVisitorManager { ...AuthorizationResult }
+            visitorManagementCanIndex { ...AuthorizationResult }
+            webhooksCanManageSubscriptions { ...AuthorizationResult }
+            webhooksCanViewSubscriptions { ...AuthorizationResult }
+          }
+        GRAPHQL
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/fragment/person_member_changelog.rb

@@ -0,0 +1,33 @@
+module Ecoportal
+  module API
+    class GraphQL
+      class Fragment
+        fragment :PersonMemberChangelog, <<~GRAPHQL
+          fragment PersonMemberChangelog on PersonMemberChangelog {
+            id
+            operation
+            accountOperation
+            personMemberId
+            apiKeyPrefix
+            changedByApi
+            humanReadableDifferences
+            createdAt {
+              dateTime
+              timeZone
+            }
+            personMember {
+              id
+              name
+              email
+            }
+            user {
+              id
+              email
+              name
+            }
+          }
+        GRAPHQL
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/fragment/template_change_log.rb

@@ -0,0 +1,102 @@
+module Ecoportal
+  module API
+    class GraphQL
+      class Fragment
+        # Node selection for a TEMPLATE change-log entry — `template { commands { nodes } }`.
+        #
+        # The type condition is the INTERFACE `PagesWorkflowCommandInterface`
+        # (`app/graphql/types/pages/interfaces/workflow_command_interface.rb`, graphql_name set
+        # explicitly there). Spreading a fragment on an interface at an interface-typed location
+        # is legal; selecting a CONCRETE type's field (e.g. `changes`, `changeMessages`) is not,
+        # unless wrapped in an inline fragment. Everything below is therefore an interface field,
+        # plus `__typename` so callers can branch on the concrete command class.
+        #
+        # Deliberately NOT selected, and why:
+        # - `stage: StageType` and `task: TaskInterface` — object subtrees; `stageId`/`stageName`
+        #   and `taskId`/`taskType` already answer "which stage / which task" as scalars, and
+        #   both resolvers do an extra RecordLoader/EmbeddedObjectLoader round trip. Select them
+        #   explicitly with a custom connection block if you need the full objects.
+        # - the concrete-type extras (`changes { field from to }`, `changeMessages`) — see
+        #   `Fragment :PagesWorkflowCommandFields` in `fragment/pages_workflow.rb`, which already
+        #   models them for the workflow-builder side of the same interface.
+        #
+        # See `Base::Template::ChangeLogEntry` for the two access caveats (nil-when-unpermitted,
+        # TEMPLATE_BUILDER-only) and the forces watermark blind spot.
+        fragment :TemplateChangeLogEntry, <<~GRAPHQL
+          fragment TemplateChangeLogEntry on PagesWorkflowCommandInterface {
+            __typename
+            id
+            commandAction
+            patchVer
+            createdAt {
+              dateTime
+              timeZone
+            }
+            updatedAt {
+              dateTime
+              timeZone
+            }
+            ownerId
+            owner {
+              id
+              name
+              email
+            }
+            stageId
+            stageName
+            taskId
+            taskType
+            targetedResourceId
+            targetedResourceName
+            targetedResourceType
+          }
+        GRAPHQL
+
+        # DETAIL selection — the same entry PLUS what actually changed.
+        #
+        # Opt in to this only when you need it: it costs three inline fragments and their
+        # sub-selections on every node. `Query::TemplateChangeLog.detail_block` and
+        # `api.template.change_log(detail: true)` both use it; the light
+        # `:TemplateChangeLogEntry` above stays the default so "who changed this, and when"
+        # does not pay for per-type detail.
+        #
+        # ★ The three concrete types report changes DIFFERENTLY, verified against the backend
+        # (2026-08-20) — this is why one flat shape cannot describe them:
+        # - `PagesWorkflowCommandChange.changes: [ChangeType!]!` — `ChangeType` is
+        #   `{ field: String!, from: String, to: String }` (`app/graphql/types/change_type.rb`),
+        #   i.e. before/after as STRINGS. This is the common case.
+        # - `PagesWorkflowCommandChangeMessage.changeMessages` — pre-rendered human strings, no
+        #   field/from/to at all.
+        # - `PagesWorkflowCommandEsChange.changes: [StoredEsFilterChangeType!]!` where `from`/`to`
+        #   are `StoredEsFilterType` OBJECTS, not strings
+        #   (`app/graphql/types/stored_es_filter_change_type.rb`). Only `field` is selected here,
+        #   deliberately: naming which filter changed is useful, and `StoredEsFilterType`'s own
+        #   shape has not been verified, so selecting into it would be a guess. An ES-change entry
+        #   therefore tells you WHICH filter moved, not its before/after.
+        #   (Reached via `WorkflowCallbacks::EditTrigger` — see the interface's `resolve_type`.)
+        #
+        # So branch on `__typename` (or ask `entry.detail_kind`) before reading `changes`.
+        fragment :TemplateChangeLogEntryDetail, <<~GRAPHQL
+          fragment TemplateChangeLogEntryDetail on PagesWorkflowCommandInterface {
+            ...TemplateChangeLogEntry
+            ... on PagesWorkflowCommandChange {
+              changes {
+                field
+                from
+                to
+              }
+            }
+            ... on PagesWorkflowCommandChangeMessage {
+              changeMessages
+            }
+            ... on PagesWorkflowCommandEsChange {
+              changes {
+                field
+              }
+            }
+          }
+        GRAPHQL
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/fragment.rb

@@ -35,6 +35,14 @@ require_relative 'fragment/page'
 require_relative 'fragment/pages'
 require_relative 'fragment/force'
 require_relative 'fragment/pages_workflow'
+require_relative 'fragment/authorization_result'
+require_relative 'fragment/permissions'
+require_relative 'fragment/activity'
+require_relative 'fragment/activity_log'
+require_relative 'fragment/auth_log'
+require_relative 'fragment/person_member_changelog'
+require_relative 'fragment/minimal_dashboard'
 require_relative 'fragment/field_configuration'
 require_relative 'fragment/page_task'
 require_relative 'fragment/template'
+require_relative 'fragment/template_change_log'

data/lib/ecoportal/api/graphql/input/action/update.rb

@@ -4,8 +4,20 @@ module Ecoportal
       module Input
         module Action
           class Update < Ecoportal::API::GraphQL::Base::Action
+            extend Logic::Input::FullArrayFields
+
             passthrough :clientMutationId
             passthrough :updateMode
+
+            # Base::Action is `root!`, so its own `as_update` never emits its array fields — an
+            # unaugmented Action::Update produced nothing for changed id-lists. The macro gives it
+            # emission, reading the full current array directly from doc vs original_doc.
+            #
+            # Schema (live introspection 20260605, UpdateActionInput): these are plain `[ID!]`,
+            # NOT IdDiffInput — the server expects the COMPLETE array, not additions/removals
+            # deltas. Hence `full_array_fields`, not `id_diff_fields` (contrast ContractorEntity,
+            # whose associatedPeopleIds/leadContractorIds ARE IdDiffInput).
+            full_array_fields :assignedPersonMemberIds, :locationIds, :fileContainerIds
           end
         end
       end

data/lib/ecoportal/api/graphql/input/contractor_entity/manager_settings.rb

@@ -0,0 +1,20 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        module ContractorEntity
+          # Input for the `updateContractorManagerSettings` mutation (2026-07 schema;
+          # renamed from the removed `updateCmAutoApprovalsSettings` / CmAutoApprovalsSettingsInput,
+          # which this gem never modelled).
+          #
+          # `cmAutoApprovalsSettings` is a required AutoApprovalsInput
+          # ({ enabled:, approvalConditions: }); pass it as a Hash.
+          class ManagerSettings < Logic::Input
+            passthrough :cmAutoApprovalsSettings
+            passboolean :allowContractorAdminsToAddAdmins
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/contractor_entity/update.rb

@@ -4,35 +4,14 @@ module Ecoportal
       module Input
         module ContractorEntity
           class Update < Input::ContractorEntity::Create
-            passthrough :clientMutationId
-            class_resolver :id_diff_input, "Ecoportal::API::GraphQL::Input::IdDiff"
-            embeds_one :associatedPeopleIds, klass: :id_diff_input
-            embeds_one :leadContractorIds, klass: :id_diff_input
-
-            ID_DIFF_FIELDS = %i[associatedPeopleIds leadContractorIds].freeze
-
-            class << self
-              # Overrides Logic::Input.from_model to reshape array fields into
-              # IdDiffInput format: { additions: [...], removals: [...] }
-              # Array fields are stripped from the flat diff, so we compare
-              # doc vs original_doc directly rather than relying on the diff hash.
-              def from_model(model, **kargs)
-                diff = Logic::Input.from_model(model, **kargs)
+            extend Logic::Input::IdDiffFields
 
-                ID_DIFF_FIELDS.each do |field|
-                  key      = field.to_s
-                  current  = Array(model.doc[key])
-                  original = Array(model.original_doc[key])
-                  next if current == original
-
-                  diff       ||= {}
-                  diff[:id]  ||= model.id
-                  diff[field]  = { additions: current - original, removals: original - current }
-                end
+            passthrough :clientMutationId
 
-                diff
-              end
-            end
+            # `associatedPeopleIds` / `leadContractorIds` are exposed on UpdateContractorEntityInput
+            # as IdDiffInput { additions:, removals: }. The macro installs a `from_model` that
+            # computes each delta directly from the read model's doc vs original_doc arrays.
+            id_diff_fields :associatedPeopleIds, :leadContractorIds
           end
         end
       end

data/lib/ecoportal/api/graphql/input/contractor_entity.rb

@@ -12,3 +12,4 @@ end
 require_relative 'contractor_entity/create'
 require_relative 'contractor_entity/destroy'
 require_relative 'contractor_entity/update'
+require_relative 'contractor_entity/manager_settings'

data/lib/ecoportal/api/graphql/input/date_range.rb

@@ -0,0 +1,16 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        # DateRange input for filtering time-bounded queries (e.g. the
+        # `dateFilter` arg of `activityLogs`).
+        #   from: ISO8601DateTime
+        #   to:   ISO8601DateTime
+        # Pass as: { from: '2026-07-01T00:00:00Z', to: '2026-07-14T00:00:00Z' }
+        class DateRange < Logic::BaseModel
+          passthrough :from, :to
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/location_structure/apply_commands.rb

@@ -33,8 +33,8 @@ module Ecoportal
                 Input::LocationStructure::InsertCommand.new
               when :update
                 Input::LocationStructure::UpdateCommand.new
-              when :reoder
-                Input::LocationStructure::ReoderCommand.new
+              when :reorder
+                Input::LocationStructure::ReorderCommand.new
               else
                 raise "Unknown command type: '#{type}'"
               end

data/lib/ecoportal/api/graphql/input/location_structure/draft/add_commands.rb

@@ -34,8 +34,8 @@ module Ecoportal
                   Input::LocationStructure::InsertCommand.new
                 when :update
                   Input::LocationStructure::UpdateCommand.new
-                when :reoder
-                  Input::LocationStructure::ReoderCommand.new
+                when :reorder
+                  Input::LocationStructure::ReorderCommand.new
                 else
                   raise "Unknown command type: '#{type}'"
                 end

data/lib/ecoportal/api/graphql/input/location_structure/insert_command.rb

@@ -3,7 +3,15 @@ module Ecoportal
     class GraphQL
       module Input
         module LocationStructure
+          # Backend evidence (app/graphql/types/inputs/locations/insert_input.rb:7-12, verified
+          # against C:\docker\ecoPortal_master): `name` is `required: true` -- without it, every
+          # insert is rejected by the backend. `keywords` ([String], optional) was also missing.
+          # Both are declared here, on InsertCommand only, NOT on the shared MoveCommand parent --
+          # a plain move has no `name`/`keywords` in the backend input, so putting them on the
+          # parent would give ReorderCommand's sibling MoveCommand a field the backend does not
+          # accept (the mirror image of this bug).
           class InsertCommand < Input::LocationStructure::MoveCommand
+            passthrough :name, :keywords
             passthrough :classificationIds
           end
         end

data/lib/ecoportal/api/graphql/input/location_structure/update_command.rb

@@ -8,14 +8,18 @@ module Ecoportal
             passthrough :name, :newName
             passthrough :classificationIds, :newClassificationIds
 
+            # Effective name: the new value if one was set, otherwise the
+            # current value stored under +name+.
             def name
-              super if newName.nil?
+              return doc["name"] if newName.nil?
 
               newName
             end
 
+            # Effective classification ids: the new value if one was set,
+            # otherwise the current value stored under +classificationIds+.
             def classificationIds
-              super if newClassificationIds.empty?
+              return doc["classificationIds"] if newClassificationIds.nil? || newClassificationIds.empty?
 
               newClassificationIds
             end

data/lib/ecoportal/api/graphql/input/page/review_task.rb

@@ -3,9 +3,22 @@ module Ecoportal
     class GraphQL
       module Input
         class Page
+          # Shared input for the five review-task mutations (approve/reject/restart/undo,
+          # plus batch_update, which does not go through this shape at all).
+          #
+          # Backend evidence (app/graphql/mutations/tasks/review_pages/, verified against
+          # C:\docker\ecoPortal_master -- the gem's stored introspection snapshot, dated
+          # 2026-07-30, is stale on this point):
+          #   approve.rb / reject.rb : id, notes
+          #   restart.rb             : id, notes, approve (Boolean, default false)
+          #   undo_review.rb         : id only
+          # None of the four accept `stageId` or `comment` -- both were unknown arguments the
+          # backend would reject, so no caller passing them could ever have succeeded.
+          # `notes` replaces the old (wrong) `comment`; `approve` is added for restart and is
+          # simply omitted (passthrough) for the other three, which never populate it.
           class ReviewTask < Logic::Input
             passkey :id
-            passthrough :stageId, :comment
+            passthrough :notes, :approve
           end
         end
       end

data/lib/ecoportal/api/graphql/input/preset_view/update.rb

@@ -7,7 +7,22 @@ module Ecoportal
             passkey     :id
             passthrough :name, :sorter
             passboolean :preview
-            passarray   :fieldConfigs
+            # NOT a list: `UpdatePresetViewInput.fieldConfigs` is a (required)
+            # `FieldConfigurationOneToManyInput` — `{ additions:, deletions:, updates: }`.
+            # Only `CreatePresetViewInput` takes the plain `[FieldConfigurationInput!]!`.
+            passthrough :fieldConfigs
+
+            class << self
+              # The read model (Base::PresetView) exposes the collection as the
+              # `fieldConfigurations` LIST; this input takes it as the `fieldConfigs`
+              # one-to-many OBJECT. Base::PresetView owns the rename + reshape, so this
+              # explicit-converter seam (`as_input(target_class:)`, or a direct
+              # `.from_model`) stays in step with the implicit `model.as_input` one.
+              # The reshape is idempotent, so applying it on both is harmless.
+              def from_model(model, **kargs)
+                Base::PresetView.build_update_input(model, super)
+              end
+            end
           end
         end
       end

data/lib/ecoportal/api/graphql/input/workflow_command/add_checklist_field_item.rb

@@ -0,0 +1,19 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class WorkflowCommand
+          # 20260713: add an item to a checklist field.
+          module AddChecklistFieldItem
+            SCHEMA_VERSION = '20260713'.freeze
+            VALID_KEYS = %i[dataFieldId placeholderId label weight].freeze
+
+            def self.build(**kwargs)
+              kwargs.slice(*VALID_KEYS).compact
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/workflow_command/add_field.rb

@@ -5,15 +5,16 @@ module Ecoportal
         class WorkflowCommand
           module AddField
             SCHEMA_VERSION = '20260605'.freeze
-            # VERIFIED against the live schema dump (WorkflowAddFieldInput, 20260605): the create
-            # command accepts ONLY these keys. There is NO `description` and NO `required` field on
-            # WorkflowAddFieldInput. `description` is instead a top-level key of
-            # WorkflowEditFieldConfigurationInput, so a field's description is persisted via a
-            # follow-up editFieldConfiguration command (see Builder::TemplateBuilder /
-            # Diff::CommandSynthesizer). `required` has NO input key anywhere in the schema (not on
-            # AddField, not on editFieldConfiguration top-level or any byType sub-input) and so
-            # cannot be persisted through the workflow command bus at all — callers must treat it as
-            # a read-only/unsupported attribute. Do NOT add these keys here (the server rejects them).
+            # VERIFIED against the backend source (WorkflowAddFieldInput, checked 20260828): the
+            # create command accepts ONLY these keys. There is NO `description` and NO `required`
+            # field on WorkflowAddFieldInput itself. Both are instead top-level keys of
+            # WorkflowEditFieldConfigurationInput (see edit_field_configuration.rb), so a field's
+            # description and required-ness are persisted via a follow-up editFieldConfiguration
+            # command (see Builder::TemplateBuilder / Diff::CommandSynthesizer). `required` IS
+            # persistable through the workflow command bus — via editFieldConfiguration's
+            # top-level `required` argument — it is simply not part of AddField. Do NOT add
+            # `description` or `required` to this builder's own keys (the server rejects them on
+            # AddField); route them through EditFieldConfiguration instead.
             VALID_KEYS = %i[placeholderId fieldType label stageId sectionId column].freeze
 
             def self.build(**kwargs)

data/lib/ecoportal/api/graphql/input/workflow_command/add_select_field_option.rb

@@ -4,12 +4,18 @@ module Ecoportal
       module Input
         class WorkflowCommand
           module AddSelectFieldOption
-            SCHEMA_VERSION = '20260605'.freeze
-            VALID_KEYS = %i[dataFieldId placeholderId label weight].freeze
+            SCHEMA_VERSION = '20260828'.freeze
+            # 20260828: added `value`, which the backend's AddSelectFieldOptionInput declares as
+            # `required: true` (schema authority: backend source, not the stale 2026-07-30
+            # introspection dump). This builder previously dropped it via kwargs.slice, so every
+            # call built by this class was rejected by the server for a missing required
+            # argument. `value` is always sent as a String, even for numeric select fields (an
+            # integral value is stored as an Integer by the server).
+            VALID_KEYS = %i[dataFieldId placeholderId label value weight].freeze
 
-            def self.build(data_field_id:, label:, **kwargs)
-              { dataFieldId: data_field_id, label: label }.
-                merge(kwargs.slice(*VALID_KEYS - %i[dataFieldId label]).compact)
+            def self.build(data_field_id:, label:, value:, **kwargs)
+              { dataFieldId: data_field_id, label: label, value: value }.
+                merge(kwargs.slice(*VALID_KEYS - %i[dataFieldId label value]).compact)
             end
           end
         end

data/lib/ecoportal/api/graphql/input/workflow_command/add_smart_fill_config.rb

@@ -0,0 +1,23 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class WorkflowCommand
+          # 20260713: smart-fill (AI) configuration extracted from the field-config inputs
+          # into its own add/edit/remove command family. `fieldConfigurations` accepts an array
+          # of pre-built WorkflowSmartFillFieldConfigurationInput hashes.
+          module AddSmartFillConfig
+            SCHEMA_VERSION = '20260713'.freeze
+            VALID_KEYS = %i[
+              dataFieldId triggerType instructions editEnabled textFormat limitLength fieldConfigurations
+            ].freeze
+
+            def self.build(**kwargs)
+              kwargs.slice(*VALID_KEYS).compact
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/workflow_command/add_stage.rb

@@ -4,8 +4,9 @@ module Ecoportal
       module Input
         class WorkflowCommand
           module AddStage
-            SCHEMA_VERSION = '20260605'.freeze
-            VALID_KEYS = %i[placeholderId name ordering].freeze
+            SCHEMA_VERSION = '20260713'.freeze
+            # 20260713: gained `tags` (create a stage already tagged, rather than adding stage tags after).
+            VALID_KEYS = %i[placeholderId name ordering tags].freeze
 
             def self.build(**kwargs)
               kwargs.slice(*VALID_KEYS).compact