ecoportal-api-graphql 2.2.0 → 3.0.0

data/lib/ecoportal/api/graphql/file_upload/client.rb

@@ -26,21 +26,38 @@ module Ecoportal
         # `X-ECOPORTAL-API-KEY` is needed here: every ecoPortal call is GraphQL, on the session
         # token this client already holds.
         #
-        # Single file:
+        # ★ Extended 2026-09 with `#upload_image`/`#upload_all_images` — steps 1-2 above (the
+        # presign + S3 POST) are IDENTICAL for an Image Gallery image; only step 3 differs
+        # (`uploadImage` -> a `TempImage`, not `uploadFile` -> a `FileContainer`). Confirmed
+        # against the live ecoPortal server source (read-only, /tmp/work/ecoPortal) that an
+        # Image Gallery image is genuinely NOT a `FileContainer` — see
+        # `Mutation::Image::Upload`'s and `Base::Page::DataField::ImageGallery`'s own headers
+        # for the full evidence trail. `#presign_and_store!` is the shared internal path both
+        # `#upload_one` and `#upload_one_image` call; `#run_batch` is the shared batch-with-
+        # progress-callback loop both `#upload_all` and `#upload_all_images` call.
+        #
+        # Single file, FileContainer (File-type fields):
         #   id = api.file_upload.upload('/path/report.pdf')
         #   page.components.get_by_name('Report').file_container_ids = [id]
         #
-        # Many files, concurrently, with per-file error isolation (nothing raises out):
+        # Single file, TempImage (Image Gallery fields):
+        #   source_id = api.file_upload.upload_image('/path/photo.jpg')
+        #   page.components.get_by_name('Site Photos').add_source_images([{source_id: source_id, file_name: 'photo.jpg'}])
+        #
+        # Many files, concurrently, with per-file error isolation (nothing raises out) — same
+        # shape for both flows:
         #   results = api.file_upload.upload_all(paths, threads: 4) do |r|
         #     puts r.success? ? "#{r.file} -> #{r.container_id}" : "#{r.file} FAILED: #{r.error}"
         #   end
         #   results.select(&:error?)
         #
-        # Instrumentation / middleware — hooks fire per stage, per file:
+        # Instrumentation / middleware — hooks fire per stage, per file, for EITHER flow (the
+        # stage names are shared: `:register` fires once whether the registration mutation was
+        # `uploadFile` or `uploadImage`):
         #   client = api.file_upload
         #   client.on(:signature) { |creds|         logger.info "presigned #{creds.endpoint}" }
         #   client.on(:storage)   { |key, response| logger.info "S3 #{response.code} #{key}" }
-        #   client.on(:register)  { |payload|       logger.info "container #{payload.item&.id}" }
+        #   client.on(:register)  { |payload|       logger.info "registered #{payload.item&.id}" }
         class Client
           include Ecoportal::API::GraphQL::Concerns::Threadable
 
@@ -51,9 +68,10 @@ module Ecoportal
 
           STAGES = %i[signature storage register].freeze
           # Fallback only — the real value is a condition inside the returned policy.
-          DEFAULT_ENCRYPTION = 'AES256'.freeze
-          DEFAULT_MIME       = 'application/octet-stream'.freeze
-          MAX_THREADS        = 8
+          DEFAULT_ENCRYPTION  = 'AES256'.freeze
+          DEFAULT_MIME        = 'application/octet-stream'.freeze
+          DEFAULT_IMAGE_TYPE  = 'image_gallery'.freeze
+          MAX_THREADS         = 8
 
           # One entry per input file. Mirrors `ecoportal-api-v2`'s
           # `S3::Files::BatchUpload::FileResult` so batch code reads the same in both stacks.
@@ -77,13 +95,36 @@ module Ecoportal
             end
           end
 
+          # Sibling to {Result} for the image-upload pipeline — same shape, different item
+          # (a `TempImage`, not a `FileContainer`).
+          ImageResult = Struct.new(:file) do
+            attr_accessor :key, :payload, :error
+
+            def error?
+              !error.nil?
+            end
+
+            def success?
+              !error? && !temp_image_id.nil?
+            end
+
+            def temp_image
+              payload&.item
+            end
+
+            def temp_image_id
+              temp_image&.id
+            end
+          end
+
           def initialize(graphql_client)
             @graphql = graphql_client
             @hooks   = {}
           end
 
           # Register a stage hook. Called for every file, in that file's own thread — keep it
-          # thread-safe (or wrap it in your own mutex).
+          # thread-safe (or wrap it in your own mutex). Fires identically for {#upload} and
+          # {#upload_image} — the STAGE names are shared between both flows.
           # @param stage [:signature, :storage, :register]
           def on(stage, &block)
             stage = stage.to_sym
@@ -102,33 +143,32 @@ module Ecoportal
             result.container_id
           end
 
+          # @return [String] the new `TempImage` id (the `sourceId` an Image Gallery
+          #   `ImageInput` write needs — see `Base::Page::DataField::ImageGallery#
+          #   add_source_images`).
+          # @raise [Error] on any failure — use {#upload_all_images} for non-raising per-file
+          #   isolation.
+          def upload_image(file_path, **kargs)
+            result = upload_one_image(file_path, **kargs)
+            raise result.error if result.error?
+
+            result.temp_image_id
+          end
+
           # Uploads many files with bounded concurrency. Never raises for a single file: each
           # {Result} carries its own error, and the block is called as each finishes.
           #
           # @param threads [Integer] max concurrent uploads (`1` = inline, deterministic).
           # @return [Array<Result>] one per input file; order is not guaranteed when threaded.
           def upload_all(file_paths, threads: 4, **kargs, &block)
-            files   = Array(file_paths).flatten.compact
-            max     = threads.to_i.clamp(1, MAX_THREADS)
-            results = []
-            spawned = []
-
-            # Presign ONCE for the batch (the policy is time-boxed but reusable) and warm it
-            # here so N threads don't race for the first one.
-            credentials
-
-            with_preserved_thread_globals do
-              files.each do |file|
-                new_thread(spawned, max: max) do
-                  result = upload_one(file, **kargs)
-                  mutex(:results).synchronize { results << result }
-                  block&.call(result)
-                end
-              end
-            end
+            run_batch(file_paths, threads: threads, on_result: block) { |file| upload_one(file, **kargs) }
+          end
 
-            spawned.each(&:join)
-            results
+          # Sibling to {#upload_all} for the image-upload pipeline — identical concurrency,
+          # isolation and progress-callback semantics.
+          # @return [Array<ImageResult>]
+          def upload_all_images(file_paths, threads: 4, **kargs, &block)
+            run_batch(file_paths, threads: threads, on_result: block) { |file| upload_one_image(file, **kargs) }
           end
 
           # Force the next upload to presign again (e.g. after a policy expiry).
@@ -141,13 +181,10 @@ module Ecoportal
 
           def upload_one(file_path, location_ids: nil, tags: nil, container_id: nil)
             Result.new(file_path).tap do |result|
-              raise MissingLocalFile, "no such file: #{file_path}" unless ::File.file?(file_path)
-
-              creds      = credentials
-              result.key = storage_key(creds, file_path)
-              store!(creds, result.key, file_path)
+              _creds, key = presign_and_store!(file_path)
+              result.key     = key
               result.payload = register(
-                file_path, result.key,
+                file_path, key,
                 location_ids: location_ids, tags: tags, container_id: container_id
               )
             rescue StandardError => e
@@ -155,6 +192,61 @@ module Ecoportal
             end
           end
 
+          def upload_one_image(file_path, type: DEFAULT_IMAGE_TYPE, id: nil, import: true)
+            ImageResult.new(file_path).tap do |result|
+              _creds, key = presign_and_store!(file_path)
+              result.key     = key
+              result.payload = register_image(file_path, key, type: type, id: id, import: import)
+            rescue StandardError => e
+              result.error = e
+            end
+          end
+
+          # Shared by BOTH flows: presign (memoised per batch), build a collision-proof S3
+          # key, and the multipart POST itself. Only the THIRD step (the registration
+          # mutation — `uploadFile` vs `uploadImage`) differs between {#upload_one} and
+          # {#upload_one_image}.
+          # @return [Array(Query::FileUploadSignature::SignatureResponse, String)] the
+          #   credentials used and the S3 key the file was stored under.
+          def presign_and_store!(file_path)
+            raise MissingLocalFile, "no such file: #{file_path}" unless ::File.file?(file_path)
+
+            creds = credentials
+            key   = storage_key(creds, file_path)
+            store!(creds, key, file_path)
+            [creds, key]
+          end
+
+          # Shared by {#upload_all}/{#upload_all_images}: bounded-concurrency loop, presign-
+          # once-per-batch, per-file error isolation, and a progress callback fired as each
+          # result lands (not deferred to the end). `upload_one` (the block) is the only thing
+          # that differs between the two callers.
+          # @yieldparam file_path [String]
+          # @yieldreturn [Result, ImageResult]
+          def run_batch(file_paths, threads:, on_result: nil)
+            files   = Array(file_paths).flatten.compact
+            max     = threads.to_i.clamp(1, MAX_THREADS)
+            results = []
+            spawned = []
+
+            # Presign ONCE for the batch (the policy is time-boxed but reusable) and warm it
+            # here so N threads don't race for the first one.
+            credentials
+
+            with_preserved_thread_globals do
+              files.each do |file|
+                new_thread(spawned, max: max) do
+                  result = yield(file)
+                  mutex(:results).synchronize { results << result }
+                  on_result&.call(result)
+                end
+              end
+            end
+
+            spawned.each(&:join)
+            results
+          end
+
           # Memoised behind a mutex so a batch presigns once, not once per thread.
           def credentials
             mutex(:credentials).synchronize do
@@ -167,7 +259,8 @@ module Ecoportal
           # `uploads/<userId>/<epoch-ms>-<token>-/<basename>` — the shape the web client uses.
           # That stamp+token segment is what stops same-named files colliding: the previous
           # implementation concatenated `upload_prefix + filename`, so two uploads of
-          # `report.pdf` overwrote each other in the bucket.
+          # `report.pdf` overwrote each other in the bucket. Shared by BOTH flows — an image
+          # upload needs the identical collision-proofing.
           def storage_key(creds, file_path)
             stamp = (Time.now.to_f * 1000).to_i
             "#{creds.upload_prefix}#{stamp}-#{SecureRandom.alphanumeric(20)}-/#{::File.basename(file_path)}"
@@ -224,6 +317,18 @@ module Ecoportal
             payload
           end
 
+          def register_image(file_path, key, type:, id:, import:)
+            payload = Mutation::Image::Upload.new(@graphql.client).query(
+              key: key, type: type, id: id, import: import
+            )
+            fire(:register, payload)
+
+            raise RegistrationFailed, "uploadImage failed for #{::File.basename(file_path)}: #{payload.error_doc}" if payload.error?
+            raise RegistrationFailed, "uploadImage returned no item for #{::File.basename(file_path)}" unless payload.item&.id
+
+            payload
+          end
+
           # The bucket policy dictates the encryption header, so echo it instead of assuming:
           # the policy is base64 JSON whose `conditions` carry `x-amz-server-side-encryption`.
           def encryption(creds)

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

@@ -99,7 +99,7 @@ module Ecoportal
               # `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
-              # `.ai-assistance/code/ecoPortal_architecture/02_data_model.md`.
+              # the repo's internal docs.
               template @skip(if: $only_content) {
                 templateContainerUid
                 active
@@ -137,7 +137,7 @@ module Ecoportal
               # 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;
-              # M&S do so on page instances — confirmed working on instances with a
+              # 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)
@@ -243,11 +243,16 @@ module Ecoportal
 
             fragment imageGalleryField on ImageGallery {
               images @include(if: $content) {
+                id
+                weight
                 downloadUrl
                 caption
                 fileName
                 fileSize
-                uploadId @skip(if: $only_content)
+                uploadId                 @skip(if: $only_content)
+                sensitiveContent         @skip(if: $only_content)
+                inaccurateDescription    @skip(if: $only_content)
+                inaccurateExtractedText  @skip(if: $only_content)
               }
             }
 

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

@@ -58,13 +58,11 @@ module Ecoportal
             pageCanListDrafts { ...AuthorizationResult }
             pageCanRestore { ...AuthorizationResult }
             pageCanUseDrafts { ...AuthorizationResult }
-            pageSmartAssistantCanChat { ...AuthorizationResult }
             personSchemaCanAccessManager { ...AuthorizationResult }
             publicTemplatesCanCopyLink { ...AuthorizationResult }
             publicTemplatesCanIndex { ...AuthorizationResult }
             publicTemplatesCanListEntries { ...AuthorizationResult }
             publicTemplatesCanManage { ...AuthorizationResult }
-            registerAssistantCanChat { ...AuthorizationResult }
             registerCanAccessRegisterTools { ...AuthorizationResult }
             registerCanCreate { ...AuthorizationResult }
             registerCanLimitTemplates { ...AuthorizationResult }

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

@@ -1,3 +1,5 @@
+require 'securerandom'
+
 module Ecoportal
   module API
     class GraphQL
@@ -15,7 +17,19 @@ module Ecoportal
               # patchVer is always included when present (required for concurrency control).
               #
               # Options:
-              #   stage_id:           ID      — target a specific stage (required for stage submit/close-out)
+              #   stage_id:           ID      — target a specific stage. Optional even for a
+              #                                 PHASED page: when omitted, it is DERIVED from
+              #                                 the owning stage of the data fields being
+              #                                 updated in this same call (see #derive_stage_id)
+              #                                 — a PHASED `updatePage` has been observed to 500
+              #                                 without a `stageId` on an Image Gallery / File
+              #                                 field write (live-diagnosed, page
+              #                                 a customer's phased page), and sending it
+              #                                 whenever derivable is always safe even where it
+              #                                 turns out not to be strictly required. Pass this
+              #                                 explicitly to override the derivation, or to
+              #                                 target a stage submit/close-out when no field on
+              #                                 that stage is dirty yet.
               #   submit:             Boolean — submit the stage (triggers task transitions server-side)
               #   publish:            Boolean — publish a draft page
               #   show_hidden_data:   Boolean — include hidden data in the mutation response
@@ -37,17 +51,31 @@ module Ecoportal
               #   location_ids:       [ID]    — set page locations (PageInput.locations); the
               #                                 model's locations embed is read_only, so this is
               #                                 the way to write them
-              #   client_mutation_id: String
+              #   client_mutation_id: String  — correlation id for tracing this call in logs /
+              #                                 the server's own activity trail. Defaults to a
+              #                                 fresh `SecureRandom.uuid` PER CALL — every
+              #                                 mutation this input builds is now traceable by
+              #                                 default, not just the ones a caller remembered
+              #                                 to tag. Pass an explicit id to correlate several
+              #                                 calls under one value, or `''`/`nil` to omit the
+              #                                 key entirely. NOTE: this is for CORRELATION only
+              #                                 — the server does NOT dedupe mutations on it, so
+              #                                 it buys no idempotency; a retried call with the
+              #                                 same clientMutationId still re-applies the write.
+              #                                 Any idempotency has to be client-side (e.g. this
+              #                                 gem's own dirty-tracking not re-sending a field
+              #                                 that already round-tripped).
               def from_model(model, stage_id: nil, submit: nil, publish: nil, show_hidden_data: nil,
                              task: nil, complete_page_task: false, sign_off: nil, review_notes: nil,
-                             location_ids: nil, client_mutation_id: '', **_kargs)
+                             location_ids: nil, client_mutation_id: SecureRandom.uuid, **_kargs)
                 task = resolve_task(task, complete_page_task, sign_off, review_notes)
-                require_stage!(stage_id, submit, task)
                 page_input = (model.as_update || {}).slice(*PAGE_FIELD_KEYS)
                 # Page locations are read_only on the model (excluded from the as_update diff),
                 # so set them explicitly here → PageInput.locations = [LocationInput{ id }].
                 page_input = page_input.merge(locations: Array(location_ids).map { |lid| { id: lid } }) unless location_ids.nil?
                 data_fields = build_data_fields(model)
+                stage_id  ||= derive_stage_id(model, data_fields)
+                require_stage!(stage_id, submit, task)
 
                 no_changes = page_input.empty? && data_fields.empty?
                 no_op      = publish.nil? && submit.nil? && stage_id.nil? && task.nil?
@@ -66,13 +94,88 @@ module Ecoportal
 
               private
 
+              # Derives the default `stageId` for a PHASED page update from the STAGE(S) that
+              # own the data fields being changed in THIS call (updates/additions/deletions).
+              #
+              # Platform fact, live-diagnosed against a customer's phased page (the
+              # org's own service account): `updatePage` on a PHASED page 500s when `stageId`
+              # is missing on an Image Gallery / File field write. The live-verified
+              # a customer collection's integration guide (§5) documents a related but
+              # narrower nuance — omitting `stageId` is judged against the ROOT page's
+              # `PagePolicy#update?` rather than being an unconditional failure, so it is
+              # "optional but preferable" for an account whose edit right arrives through
+              # page-level administration rather than a stage. Sending it whenever it CAN be
+              # derived is correct either way: never wrong for an account that did not need
+              # it, and fixes the account/field combination that does. A `BasicPage` has no
+              # `#stages` at all — returns `nil` (stageId OMITTED from the input entirely,
+              # never sent as an explicit `null`; `build_input`'s nil-guard already drops a
+              # nil operation key).
+              #
+              # Multi-stage calls: if the fields being updated in this ONE call span MORE
+              # THAN ONE stage, this raises rather than guessing which stage's id to send (a
+              # single `updatePage` input can only carry one `stageId`). The caller must split
+              # such a change into one `from_model`/mutation call PER STAGE, in stage order,
+              # threading the model's (fresh, server-returned) `patchVer` from each response
+              # into the next call — the same pattern the org-side reference implementation
+              # (a downstream script repo's `-file-attach` case, `persist_file_updates`/
+              # `persist_gallery`) already uses at the call-site level, re-fetching the page
+              # between groups. Pass `stage_id:` explicitly to bypass this derivation for any
+              # other need (e.g. targeting a stage submit with no dirty field on it yet).
+              def derive_stage_id(model, data_fields)
+                return nil unless model.respond_to?(:stages)
+
+                field_ids = changed_field_ids(data_fields)
+                return nil if field_ids.empty?
+
+                owning_stage_ids = Array(model.stages).filter_map do |stage|
+                  stage.id if Array(stage.stage_field_ids).intersect?(field_ids)
+                end.uniq
+
+                case owning_stage_ids.size
+                when 0 then nil
+                when 1 then owning_stage_ids.first
+                else
+                  raise ArgumentError,
+                        "This update's data fields span #{owning_stage_ids.size} different " \
+                        "stages (#{owning_stage_ids.join(', ')}) — a single updatePage call " \
+                        'can only target one stageId. Split into one from_model/mutation call ' \
+                        "per stage, in stage order, re-fetching the page (fresh patchVer) " \
+                        'between calls, or pass stage_id: explicitly to target just one.'
+                end
+              end
+
+              # Every field id touched by this call's dataFields command (updates, additions,
+              # deletions) — the raw DataFieldInput hashes are `{ typeKey: { id:, ... } }`, so
+              # `id` is read generically off the first (only) value, regardless of field type.
+              def changed_field_ids(data_fields)
+                ids = Array(data_fields[:updates]).filter_map { |cmd| field_id_from_command(cmd) }
+                ids.concat(Array(data_fields[:additions]).filter_map { |cmd| field_id_from_command(cmd) })
+                ids.concat(Array(data_fields[:deletions]))
+                ids.compact.uniq
+              end
+
+              def field_id_from_command(command)
+                return nil unless command.is_a?(Hash)
+
+                inner = command.values.first
+                inner.is_a?(Hash) ? inner[:id] : nil
+              end
+
               # Platform invariant: a stage submit / sign-off MUST target a specific stage.
               # Page tasks (and the people-field permissions scoped to them) apply to ONE
               # stage; without a stageId the server cannot route the submit to the stage the
               # work was done on. Fail loudly here rather than silently omit stageId (the
               # nil-guard in build_input would otherwise drop it — the exact bug that let an
-              # act-gov TOOCS submit go out stage-less). A plain field update or publish
-              # needs no stage and is unaffected.
+              # some customer submissions go out stage-less).
+              #
+              # CORRECTED comment (this used to say "a plain field update ... needs no stage
+              # and is unaffected" — wrong for a PHASED page: `updatePage` 500s there without
+              # a `stageId` on ANY write, plain field update included; see `#derive_stage_id`,
+              # which is called BEFORE this guard and already fills it in from the fields
+              # being changed whenever it can). This guard now only fires for the case
+              # `#derive_stage_id` genuinely cannot resolve — no dirty field to derive from
+              # (a stage-submit-only call) or a `BasicPage` (no stages at all, where a submit
+              # makes no sense anyway) — same platform invariant, just reached less often now.
               def require_stage!(stage_id, submit, task)
                 return unless stage_id.nil?
                 return unless submit || task

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

@@ -96,7 +96,7 @@ module Ecoportal
           # A register FIELD key carries a `<type>.<hash>` shape (e.g. 'date.zab1bddc3');
           # system/top-level keys (created_at, external_id, state) have no such prefix.
           # Field filters need the nested `membranes.<type>` path — see
-          # .ai-assistance/code/filter_contract_matrix.md.
+          # the repo's internal docs
           # ---------------------------------------------------------------------------
           module MembranePath
             module_function

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

@@ -6,7 +6,7 @@ module Ecoportal
           # `WorkflowEditTemplateContainerUidInput { templateContainerUid: String! }`.
           #
           # Sets the template's CROSS-VERSION identity key. Semantics (verified against the
-          # backend on 2026-07-31 — see `.ai-assistance/code/ecoPortal_architecture/02_data_model.md`):
+          # backend on 2026-07-31 — see the repo's internal docs):
           #
           # - Format `/\A[a-zA-Z0-9\-_.]{3,20}\z/` — org-scoped, human-authored.
           # - Many versions of a template may share one uid, but only ONE may be published

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

@@ -17,7 +17,7 @@ module Ecoportal
           # included in a copy (`include`) and whether the choice is locked against per-copy
           # override (`enforce`). `enforce` is the least certain of these.
           # Confirm against platform behaviour before relying on any of it; see
-          # `.ai-assistance/code/ecoPortal_architecture/10_forces_workflow_builder.md`.
+          # the repo's internal docs.
           module ManageCopyPageConfiguration
             SCHEMA_VERSION = '20260819'.freeze
             VALID_KEYS = %i[overridePageCreatorPermissions autoIncludeNewContent inclusionSettingsChanges].freeze

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

@@ -0,0 +1,33 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class WorkflowCommand
+          # `WorkflowMoveSectionToStageInput` (20260929) -- moves an existing section from one
+          # stage to another, optionally placed relative to an anchor section. Unlike
+          # `reorderSection` (same stage), the source and target stages are both required.
+          module MoveSectionToStage
+            SCHEMA_VERSION = '20260929'.freeze
+            VALID_KEYS = %i[sourceStageId targetStageId sectionId anchorId anchorPosition].freeze
+            ANCHOR_POSITIONS = AddViewableField::ANCHOR_POSITIONS
+
+            def self.build(source_stage_id:, target_stage_id:, section_id:, **kwargs)
+              position = kwargs[:anchorPosition]
+              unless position.nil? || ANCHOR_POSITIONS.include?(position.to_s)
+                raise ArgumentError,
+                      "Invalid anchorPosition #{position.inspect}: " \
+                      "expected one of #{ANCHOR_POSITIONS.join(', ')}"
+              end
+
+              {
+                sourceStageId: source_stage_id,
+                targetStageId: target_stage_id,
+                sectionId:     section_id
+              }.merge(kwargs.slice(:anchorId, :anchorPosition).compact)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -43,6 +43,7 @@ module Ecoportal
             collapseSection:                   'Ecoportal::API::GraphQL::Input::WorkflowCommand::CollapseSection',
             expandSection:                     'Ecoportal::API::GraphQL::Input::WorkflowCommand::ExpandSection',
             reorderSection:                    'Ecoportal::API::GraphQL::Input::WorkflowCommand::ReorderSection',
+            moveSectionToStage:                'Ecoportal::API::GraphQL::Input::WorkflowCommand::MoveSectionToStage',
             # Task
             addTask:                           'Ecoportal::API::GraphQL::Input::WorkflowCommand::AddTask',
             removeTask:                        'Ecoportal::API::GraphQL::Input::WorkflowCommand::RemoveTask',
@@ -275,6 +276,7 @@ require_relative 'workflow_command/edit_linked_helper'
 require_relative 'workflow_command/remove_linked_helper'
 require_relative 'workflow_command/add_viewable_field'
 require_relative 'workflow_command/move_viewable_field'
+require_relative 'workflow_command/move_section_to_stage'
 require_relative 'workflow_command/remove_viewable_field'
 require_relative 'workflow_command/field_config/action_list'
 require_relative 'workflow_command/field_config/contractor_entities'

data/lib/ecoportal/api/graphql/logic/base_query.rb

@@ -155,7 +155,7 @@ module Ecoportal
           # location `graphql-client` deliberately sets via
           # `set_backtrace(["#{filename}:#{line}"])`. With that gone there was no other
           # way to see which query blew up. (Tracked upstream; see
-          # `.ai-assistance/code/refactoring/opportunities.md`.)
+          # the repo's internal docs.)
           #
           # But the location was never actually destroyed. Ruby populates `.cause`
           # automatically when you raise inside a rescue, so the original error — with the

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

@@ -108,6 +108,9 @@ module Ecoportal
                      klass: "Ecoportal::API::GraphQL::Model::AuthorizationResult", nullable: true
           embeds_one :pageCanUseDrafts,
                      klass: "Ecoportal::API::GraphQL::Model::AuthorizationResult", nullable: true
+          # DEPRECATED (20260929): removed from the live schema by the smart-assistant
+          # consolidation; no longer selected by Fragment::Permissions, so always nil. Kept so
+          # callers get nil instead of NoMethodError.
           embeds_one :pageSmartAssistantCanChat,
                      klass: "Ecoportal::API::GraphQL::Model::AuthorizationResult", nullable: true
           embeds_one :personSchemaCanAccessManager,
@@ -120,6 +123,9 @@ module Ecoportal
                      klass: "Ecoportal::API::GraphQL::Model::AuthorizationResult", nullable: true
           embeds_one :publicTemplatesCanManage,
                      klass: "Ecoportal::API::GraphQL::Model::AuthorizationResult", nullable: true
+          # DEPRECATED (20260929): removed from the live schema by the smart-assistant
+          # consolidation; no longer selected by Fragment::Permissions, so always nil. Kept so
+          # callers get nil instead of NoMethodError.
           embeds_one :registerAssistantCanChat,
                      klass: "Ecoportal::API::GraphQL::Model::AuthorizationResult", nullable: true
           embeds_one :registerCanAccessRegisterTools,

data/lib/ecoportal/api/graphql/model/temp_image.rb

@@ -0,0 +1,10 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Model
+        class TempImage < Base::TempImage
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/model/template/binding.rb

@@ -0,0 +1,60 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Model
+        module Template
+          # A force binding — `addBinding`/`editBinding`'s `referenceId` is the field (or field
+          # placeholder) the binding points at. `reference_id=` accepts either a raw id/String
+          # OR a `Field` (or any object answering `#ref`) so a caller can write
+          # `binding.reference_id = some_field` and let the SAME just-created-or-real-id
+          # resolution `Field#ref` already does apply here automatically — no separate
+          # "resolve the field id" step for the caller to remember.
+          class Binding
+            include Node
+
+            PLACEHOLDER_PREFIX = 'bnd'.freeze
+
+            BINDING_TYPE = 'field'.freeze
+
+            attr_reader :template, :force, :type
+            attr_accessor :name
+
+            def initialize(template:, force:, id: nil, name: nil, reference_id: nil, type: BINDING_TYPE)
+              @template     = template
+              @force        = force
+              @id           = id
+              @name         = name
+              @type         = type
+              self.reference_id = reference_id
+              @snapshot = snapshot_attrs.freeze
+            end
+
+            attr_writer :reference_id
+
+            # Resolved at read time: the referenced node's own `#ref` when it is one (a `Field`
+            # or anything else in this tree), otherwise the raw value as given.
+            def reference_id
+              @reference_id.respond_to?(:ref) ? @reference_id.ref : @reference_id
+            end
+
+            def dirty?
+              !removed? && !new? && snapshot_attrs != @snapshot
+            end
+
+            def changed_attributes
+              return {} if new? || removed?
+
+              snapshot_attrs.each_with_object({}) { |(k, v), h| h[k] = v if v != @snapshot[k] }
+            end
+
+            private
+
+            def snapshot_attrs
+              { name: name, reference_id: reference_id }
+            end
+          end
+        end
+      end
+    end
+  end
+end