ecoportal-api-graphql 2.0.0 → 2.2.0

data/lib/ecoportal/api/graphql/query/templates.rb

@@ -1,53 +1,53 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Query
-        class Templates < Logic::QueryConnection
-          field_name :templates
-
-          class_resolver :item_class, 'Ecoportal::API::GraphQL::Model::PageUnion'
-          class_resolver :connection_class, 'Ecoportal::API::GraphQL::Connection::Page'
-
-          private
-
-          def basic_block(&block)
-            connection_block = block || default_connection_block
-            proc {
-              query(
-                searchConf: :Search,
-                after:      :string,
-                before:     :string,
-                first:      :int,
-                last:       :int
-              ) {
-                currentOrganization {
-                  templates(
-                    searchConf: :searchConf,
-                    after:      :after,
-                    before:     :before,
-                    first:      :first,
-                    last:       :last,
-                    &connection_block
-                  )
-                }
-              }
-            }
-          end
-
-          def default_connection_block
-            proc {
-              totalCount
-              pageInfo {
-                endCursor
-                hasNextPage
-              }
-              nodes {
-                spread :PageFields
-              }
-            }
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        class Templates < Logic::QueryConnection
+          field_name :templates
+
+          class_resolver :item_class, 'Ecoportal::API::GraphQL::Model::PageUnion'
+          class_resolver :connection_class, 'Ecoportal::API::GraphQL::Connection::Page'
+
+          private
+
+          def basic_block(&block)
+            connection_block = block || default_connection_block
+            proc {
+              query(
+                searchConf: :Search,
+                after:      :string,
+                before:     :string,
+                first:      :int,
+                last:       :int
+              ) {
+                currentOrganization {
+                  templates(
+                    searchConf: :searchConf,
+                    after:      :after,
+                    before:     :before,
+                    first:      :first,
+                    last:       :last,
+                    &connection_block
+                  )
+                }
+              }
+            }
+          end
+
+          def default_connection_block
+            proc {
+              totalCount
+              pageInfo {
+                endCursor
+                hasNextPage
+              }
+              nodes {
+                spread :PageFields
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -19,6 +19,7 @@ require_relative 'query/page_activities'
 require_relative 'query/auth_logs'
 require_relative 'query/permissions'
 require_relative 'query/person_member_changelogs'
+require_relative 'query/person_members'
 require_relative 'query/dashboard_search'
 require_relative 'query/page'
 require_relative 'query/pages'
@@ -31,3 +32,4 @@ require_relative 'query/file_upload_signature'
 
 require_relative 'query/page_with_forces'
 require_relative 'query/pages_workflow_commands'
+require_relative 'query/template_change_log'

data/lib/ecoportal/api/graphql_version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    GRAPQL_VERSION = '2.0.0'.freeze
+    GRAPQL_VERSION = '2.2.0'.freeze
   end
 end

data/lib/ecoportal/api-graphql.rb

@@ -1,10 +1,10 @@
-require "ecoportal/api-v2"
-require "ecoportal/api/graphql_version"
-
-module Ecoportal
-  module API
-  end
-end
-
-require_relative "api/common.graphql"
-require_relative "api/graphql"
+require "ecoportal/api-v2"
+require "ecoportal/api/graphql_version"
+
+module Ecoportal
+  module API
+  end
+end
+
+require_relative "api/common.graphql"
+require_relative "api/graphql"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-graphql
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Oscar Segura
@@ -160,7 +160,7 @@ dependencies:
         version: '3.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.3.3
+        version: 3.3.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -170,7 +170,7 @@ dependencies:
         version: '3.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.3.3
+        version: 3.3.5
 - !ruby/object:Gem::Dependency
   name: graphlient
   requirement: !ruby/object:Gem::Requirement
@@ -203,14 +203,12 @@ files:
 - lib/ecoportal/api-graphql.rb
 - lib/ecoportal/api/common.graphql.rb
 - lib/ecoportal/api/common/graphql.rb
-- lib/ecoportal/api/common/graphql/CLAUDE.md
 - lib/ecoportal/api/common/graphql/auth_service.rb
 - lib/ecoportal/api/common/graphql/class_helpers.rb
 - lib/ecoportal/api/common/graphql/client.rb
 - lib/ecoportal/api/common/graphql/hash_helpers.rb
 - lib/ecoportal/api/common/graphql/http_client.rb
 - lib/ecoportal/api/common/graphql/model.rb
-- lib/ecoportal/api/common/graphql/model/CLAUDE.md
 - lib/ecoportal/api/common/graphql/model/as_input.rb
 - lib/ecoportal/api/common/graphql/model/diffable.rb
 - lib/ecoportal/api/common/graphql/model/diffable/classic_diff_service.rb
@@ -221,9 +219,7 @@ files:
 - lib/ecoportal/api/common/graphql/patches.rb
 - lib/ecoportal/api/common/graphql/query_integration.rb
 - lib/ecoportal/api/graphql.rb
-- lib/ecoportal/api/graphql/CLAUDE.md
 - lib/ecoportal/api/graphql/base.rb
-- lib/ecoportal/api/graphql/base/CLAUDE.md
 - lib/ecoportal/api/graphql/base/action.rb
 - lib/ecoportal/api/graphql/base/action_category.rb
 - lib/ecoportal/api/graphql/base/action_event.rb
@@ -316,8 +312,8 @@ files:
 - lib/ecoportal/api/graphql/base/register.rb
 - lib/ecoportal/api/graphql/base/resource.rb
 - lib/ecoportal/api/graphql/base/template.rb
+- lib/ecoportal/api/graphql/base/template/change_log_entry.rb
 - lib/ecoportal/api/graphql/builder.rb
-- lib/ecoportal/api/graphql/builder/CLAUDE.md
 - lib/ecoportal/api/graphql/builder/action.rb
 - lib/ecoportal/api/graphql/builder/contractor_entity.rb
 - lib/ecoportal/api/graphql/builder/kickstand.rb
@@ -358,6 +354,7 @@ files:
 - lib/ecoportal/api/graphql/connection/person_member_changelog.rb
 - lib/ecoportal/api/graphql/connection/preset_view.rb
 - lib/ecoportal/api/graphql/connection/preview_page.rb
+- lib/ecoportal/api/graphql/connection/template_change_log.rb
 - lib/ecoportal/api/graphql/diff.rb
 - lib/ecoportal/api/graphql/diff/change.rb
 - lib/ecoportal/api/graphql/diff/command_synthesizer.rb
@@ -400,6 +397,7 @@ files:
 - lib/ecoportal/api/graphql/fragment/permissions.rb
 - lib/ecoportal/api/graphql/fragment/person_member_changelog.rb
 - lib/ecoportal/api/graphql/fragment/template.rb
+- lib/ecoportal/api/graphql/fragment/template_change_log.rb
 - lib/ecoportal/api/graphql/helpers.rb
 - lib/ecoportal/api/graphql/helpers/locations_tree.rb
 - lib/ecoportal/api/graphql/input.rb
@@ -534,6 +532,7 @@ files:
 - lib/ecoportal/api/graphql/input/workflow_command/field_config/select.rb
 - lib/ecoportal/api/graphql/input/workflow_command/field_config/signature.rb
 - lib/ecoportal/api/graphql/input/workflow_command/field_config/table.rb
+- lib/ecoportal/api/graphql/input/workflow_command/manage_copy_page_configuration.rb
 - lib/ecoportal/api/graphql/input/workflow_command/move_field.rb
 - lib/ecoportal/api/graphql/input/workflow_command/move_stage.rb
 - lib/ecoportal/api/graphql/input/workflow_command/move_viewable_field.rb
@@ -626,6 +625,7 @@ files:
 - lib/ecoportal/api/graphql/model/register.rb
 - lib/ecoportal/api/graphql/model/resource.rb
 - lib/ecoportal/api/graphql/model/template.rb
+- lib/ecoportal/api/graphql/model/template/change_log_entry.rb
 - lib/ecoportal/api/graphql/model/user.rb
 - lib/ecoportal/api/graphql/mutation.rb
 - lib/ecoportal/api/graphql/mutation/action.rb
@@ -764,8 +764,10 @@ files:
 - lib/ecoportal/api/graphql/query/pages_workflow_commands.rb
 - lib/ecoportal/api/graphql/query/permissions.rb
 - lib/ecoportal/api/graphql/query/person_member_changelogs.rb
+- lib/ecoportal/api/graphql/query/person_members.rb
 - lib/ecoportal/api/graphql/query/register_preset_views.rb
 - lib/ecoportal/api/graphql/query/register_preview_pages.rb
+- lib/ecoportal/api/graphql/query/template_change_log.rb
 - lib/ecoportal/api/graphql/query/templates.rb
 - lib/ecoportal/api/graphql_version.rb
 homepage: https://www.ecoportal.com

data/lib/ecoportal/api/common/graphql/CLAUDE.md

@@ -1,36 +0,0 @@
-# common/graphql
-
-Shared HTTP transport, authentication, and base model infrastructure used by the gem — nothing here is EcoPortal-domain-specific.
-
-## Contents
-
-| File / class | Purpose |
-|---|---|
-| `auth_service.rb` / `AuthService` | OAuth2 password + refresh-token flow; included in both client classes |
-| `client.rb` / `Client` | Graphlient-based GraphQL client (builds bearer-token headers, constructs endpoint URL) |
-| `http_client.rb` / `HttpClient` | Raw HTTP client (extends `Common::Client`); `execute` sends query strings + variables; supports v0–v3 + graphql API version modes |
-| `class_helpers.rb` / `ClassHelpers` | `becomes(klass)` instance casting + `const?` class helper |
-| `hash_helpers.rb` / `HashHelpers` | Deep key transforms (`keys_to_sym_deep`, `deep_dup`, `remove_nil_keys_deep`) — used by diff and input serialisation |
-| `query_integration.rb` / `QueryIntegration` | Class macro `query(:method, query_klass:)` that wires a named query method on `Model::Organization` |
-| `model.rb` / `Model` | Base model class: `DoubleModel` + `Diffable` + `AsInput`; all GraphQL models ultimately inherit this |
-| `patches.rb` | Reserved placeholder (empty) |
-| `model/diffable.rb` | `as_update` / `dirty?` — delegates to `DiffService` |
-| `model/as_input.rb` | `as_input` (instance) and `as_input(hash)` (class method) — converts diff to GraphQL mutation variables |
-| `model/diffable/diff_service.rb` | Main diff engine: flat classic diff + cascaded reduce through nested `GraphQL::Model` objects |
-| `model/diffable/classic_diff_service.rb` | Low-level change-data extraction (compares `curr_doc` vs `prev_doc`) |
-| `model/diffable/hash_diff.rb` | Hash equality / change detection helpers |
-| `model/diffable/hash_diff_nesting.rb` | Nested key path helpers (`dig_set!`, `dig_delete!`, `dig_path?`) |
-
-## Conventions
-
-- `Client` is graphlient-based and used for schema introspection; `HttpClient` is the actual request sender used in production (set as `client.http_client`).
-- `HashHelpers` is used as both a module mixin (include) and directly via `HashHelpers.keys_to_sym_deep(...)`.
-- `DiffService` handles the `flat:` flag: `flat: true` does a single-level diff; `flat: false` (default) cascades through nested `GraphQL::Model` objects.
-- Root-class objects (`root!` declared) are excluded from cascaded diffs — they represent independent server entities.
-- `AsInput#as_input(target_class:)` delegates to `Input::X.from_model(self)` when a target class is given.
-
-## Related
-
-- `../graphql/logic/base_model.rb` — adds `SnakeCamelAccess` on top of `Common::GraphQL::Model`
-- `../graphql/logic/input.rb` — `Logic::Input` base class built on top of `Model`
-- `../graphql/logic/base_query.rb` — consumes `HttpClient#execute` and `HashHelpers`

data/lib/ecoportal/api/common/graphql/model/CLAUDE.md

@@ -1,28 +0,0 @@
-# common/graphql/model
-
-Concerns that add dirty-tracking diff (`Diffable`) and mutation-input serialisation (`AsInput`) to the base `Common::GraphQL::Model`.
-
-## Contents
-
-| File / class | Purpose |
-|---|---|
-| `diffable.rb` / `Model::Diffable` | Provides `as_update` (returns changed-field hash or nil) and `dirty?`; delegates to `DIFF_CLASS` (defaults to `DiffService`) |
-| `as_input.rb` / `Model::AsInput` | Instance `as_input` (wraps diff as mutation variables) + class-level `as_input(hash)` (key-sym + nil-id cleanup) |
-| `diffable/diff_service.rb` / `DiffService` | Primary diff engine: flat classic diff then cascaded reduce over nested `GraphQL::Model` children |
-| `diffable/classic_diff_service.rb` / `ClassicDiffService` | Low-level diff: compares `curr_doc` vs `prev_doc`, returns `{ id:, changed_field: new_value }` or nil |
-| `diffable/hash_diff.rb` / `HashDiff` | Primitive equality helpers used by `ClassicDiffService` |
-| `diffable/hash_diff_nesting.rb` / `HashDiffNesting` | Nested path helpers: `dig_set!`, `dig_delete!`, `dig_path?` used when building cascaded diff results |
-
-## Conventions
-
-- `DIFF_CLASS = DiffService` is a constant on `Diffable` — subclasses can override it to swap diff strategies.
-- `DiffService` `flat: true` produces a single-level diff (current model only); `flat: false` (default) recurses via `cascaded_reduce` through nested `GraphQL::Model` objects.
-- Objects declared with `root!` in their class are skipped during cascaded diff — they are independent server entities (look-ups only).
-- `as_input` on a model calls `as_update` first; returns `nil` when nothing has changed so callers can skip the mutation.
-- `as_input(target_class:)` is the preferred path when a corresponding `Input::X` class exists — delegates to `target_class.from_model(self)`.
-
-## Related
-
-- `../hash_helpers.rb` — `HashHelpers` used inside `DiffService` for key transforms
-- `../../graphql/logic/input.rb` — `Logic::Input.from_model` is the canonical consumer of `as_update`
-- `../../graphql/logic/base_model.rb` — all concrete models inherit this chain

data/lib/ecoportal/api/graphql/CLAUDE.md

@@ -1,37 +0,0 @@
-# graphql (gem root)
-
-The entry point for the gem: `Ecoportal::API::GraphQL` is the top-level class consumers instantiate; it holds the `client`, wires the `HttpClient`, and exposes builder/compat entry points.
-
-## Contents
-
-| File / class | Purpose |
-|---|---|
-| `graphql.rb` / `GraphQL` | Main entry class — `initialize` builds `Client` + `HttpClient`, exposes `pages`, `registers`, `page`, `action`, `contractorEntity`, `locationStructure`, `currentOrganization` |
-| `graphql_version.rb` | Gem `VERSION` constant |
-| `base/` | Data-only model base classes (no resolvers, no `client`); see `base/CLAUDE.md` |
-| `builder/` | Facade builders that group related mutations under one object |
-| `compat/` | v2-compatible API layer for eco-helpers scripts |
-| `concerns/` | Shared Ruby mixins (`PageCompat`, `DataFieldAccess`, `SnakeCamelAccess`, `FragmentDefinitions`) |
-| `connection/` | `Logic::Connection` subclasses — typed pagination wrappers per entity |
-| `error/` | Domain error classes (`ValidationErrors`, `LocationsError`, `LocationsValidationError`) |
-| `fragment/` | GraphQL fragment heredoc strings + `Fragment.assemble(*syms)` |
-| `helpers/` | Utility modules (`LocationsTree`) |
-| `input/` | Mutation input serialisers; `SearchConf` is a chainable value object |
-| `interface/` | Abstract base models shared by `Base::` and `Model::` (e.g. `BasePage`, `LocationStructure`) |
-| `logic/` | Abstract base classes for queries, mutations, connections — no domain code |
-| `model/` | Concrete domain models with `class_resolver` wiring; subclass their `Base::` counterparts |
-| `mutation/` | Concrete mutation execution classes |
-| `payload/` | Mutation response payload wrappers |
-| `query/` | Concrete query execution classes |
-
-## Conventions
-
-- Load order in `graphql.rb` matters: `logic/base_model` → `error` → `interface` → `base` → `model` → rest.
-- `#pages` returns `Compat::Pages` (v2-compatible); `#page` returns `Builder::Page` (raw mutation facade).
-- `#currentOrganization` returns `Model::Organization` class (not instance) with `client` set — query methods are class-level.
-- `GraphQL` (not `GraphQL`) is the namespace: use `Ecoportal::API::Graphql` alias only for legacy references; internal code uses `GraphQL`.
-
-## Related
-
-- `../../common/graphql/` — HTTP client, auth, and base model infrastructure
-- Downstream: `eco-helpers` calls `.pages` and `.registers` exclusively via `Compat::*`

data/lib/ecoportal/api/graphql/base/CLAUDE.md

@@ -1,50 +0,0 @@
-# base
-
-Data-only model base classes — these declare fields and structure but hold no `client`, no query resolvers, and no business logic.
-
-## Contents
-
-| File / class | Purpose |
-|---|---|
-| `action.rb` / `Base::Action` | Action fields (id, name, status, dates, assignee IDs); declared `root!` so excluded from cascaded diffs |
-| `action_category.rb` / `Base::ActionCategory` | Action category fields |
-| `contractor_entity.rb` / `Base::ContractorEntity` | Contractor entity fields |
-| `contractor_entity/member_changes.rb` | Nested member-changes sub-model |
-| `date_time.rb` / `Base::DateTime` | Wraps `{ dateTime:, timeZone: }` response objects |
-| `delta_result.rb` / `Base::DeltaResult` | `pageDelta` result item: `id` + `delta` enum (UPDATED/NOT_FOUND/NEW) |
-| `field.rb` / `Base::Field` | Generic field model |
-| `file_attachment.rb` / `Base::FileAttachment` | File attachment metadata |
-| `file_container.rb` / `Base::FileContainer` | File container wrapper |
-| `location_classification_type.rb` | Classification type (name) |
-| `location_node.rb` / `Base::LocationNode` | Location node with ancestors and classifications |
-| `location_structure.rb` / `Base::LocationStructure` | Location structure tree model |
-| `location_structure/draft.rb` | Draft structure model |
-| `location_structure/draft/structure.rb` | Nested draft structure detail |
-| `organization.rb` / `Base::Organization` | Thin organization base (id, name) |
-| `page.rb` | Namespace module; requires `basic`, `data_field`, `section`, `section_collection`, `phased` |
-| `page/basic.rb` / `Base::Page::Basic` | BasicPage — inherits `Interface::BasePage`; no extra fields |
-| `page/phased.rb` / `Base::Page::Phased` | PhasedPage — inherits `Interface::BasePage`; `embeds_many :stages` |
-| `page/phased/stage.rb` / `Base::Page::Phased::Stage` | Single stage: id, name, ordering, state, sections, components |
-| `page/section.rb` / `Base::Page::Section` | Section wrapper (ContentSection or SplitSection); merges left/right dataFields into `components` |
-| `page/section_collection.rb` / `Base::Page::SectionCollection` | Enumerable wrapper over sections; provides `get_by_type`, `get_by_heading`, `components` |
-| `page/data_field.rb` / `Base::Page::DataField` | Base data field class; `TYPE_MAP` dispatches `from_doc` to typed subclasses |
-| `page/data_field/` | 10 typed subclasses (PlainText, RichText, DateField, Number, Gauge, People, Select, Checklist, TagField, Geo) + `Collection` |
-| `page_info.rb` / `Base::PageInfo` | Cursor pagination info (endCursor, hasNextPage) |
-| `person_member.rb` / `Base::PersonMember` | Person member (name, email, id) |
-| `preview_page.rb` / `Base::PreviewPage` | Lightweight page preview (no field data) |
-| `resource.rb` / `Base::Resource` | Resource model (inherits `Logic::BaseModel` directly) |
-| `pages_workflow.rb` / `Base::PagesWorkflow` | PagesWorkflow top-level model: `autoPageCreationEnabled`, `fields` (RegisterField), `stages`; sub-files under `pages_workflow/` cover RegisterField, CallbackType, OperationInterface, TriggerInterface, and supporting types |
-
-## Conventions
-
-- `Base::` classes are data-only: `passkey`, `passthrough`, `passboolean`, `passarray`, `embeds_one`, `embeds_many` only — no business methods, no resolvers.
-- `Model::` subclasses in `../model/` add `class_resolver` wiring and may add behaviour (e.g. `Model::Page::Phased#stages` wraps the array in `Compat::StageCollection`).
-- `Interface::BasePage` is the shared parent of both `Basic` and `Phased`; field declarations that apply to both page types live there.
-- `Base::Action` declares `root!` — this marks it as an independent server entity, excluded from cascaded `as_update` diffs.
-- When adding a new field to a page type, add it to `Interface::BasePage` if it applies to both, or to the appropriate `Base::Page::*` class.
-
-## Related
-
-- `../interface/base_page.rb` — common parent for Basic + Phased page base classes
-- `../model/` — concrete models that subclass these bases
-- `../model/page_union.rb` — factory that dispatches `__typename` to `Model::Page::Basic` or `Model::Page::Phased`

data/lib/ecoportal/api/graphql/builder/CLAUDE.md

@@ -1,65 +0,0 @@
-# builder
-
-Façade classes that group related mutations (and occasional queries) under a single object.
-Consumers interact with builders rather than instantiating `Logic::Mutation` / `Logic::Query`
-subclasses directly.
-
-## Contents
-
-| File / class | Exposed from `GraphQL` as | Purpose |
-|---|---|---|
-| `action.rb` / `Builder::Action` | `GraphQL#action` | `create`, `update`, `archive` — wraps `Mutation::Action::*` |
-| `contractor_entity.rb` / `Builder::ContractorEntity` | `GraphQL#contractorEntity` | `create`, `update`, `destroy` — wraps `Mutation::ContractorEntity::*` |
-| `location_structure.rb` / `Builder::LocationStructure` | `GraphQL#locationStructure` | `nodeClassifications` (query), `applyCommandsInput`, `applyCommands`, `draft` sub-builder |
-| `location_structure/draft.rb` / `Builder::LocationStructure::Draft` | via `locationStructure.draft` | Location structure draft mutations |
-| `page.rb` / `Builder::Page` | `GraphQL#page` | Full page lifecycle: `update`, `archive`, `unarchive`, `build_from_template`, `create_from_template`, `create_draft`, `delete_draft`, `publish_draft`, `approve/reject/restart/undo/batch_update_review_task`, `execute_workflow_commands` (new), `execute_force_commands` (deprecated) |
-| `register.rb` / `Builder::Register` | *(not yet exposed)* | **Stub** — all methods commented out. No `Mutation::Register::*` classes exist yet. See TODO below. |
-
-## How builders are exposed
-
-All active builders are wired in `lib/ecoportal/api/graphql.rb` as instance methods:
-
-```ruby
-def page
-  Builder::Page.new(client)
-end
-def action
-  Builder::Action.new(client)
-end
-# etc.
-```
-
-`registers` (note: plural, lowercase) returns `Compat::Registers`, **not** `Builder::Register`.
-`Builder::Register` is a stub and is not yet wired into the top-level class.
-
-## Builder::Register — TODO
-
-`builder/register.rb` contains a stub class with all methods commented out.
-Before it can be implemented:
-
-1. Research which Register mutations exist in the schema (`createRegister`,
-   `updateRegister`, `archiveRegister`, etc.) — none are currently documented
-   in `.ai-assistance/code/ecoportal_schema_reference.md`.
-2. Create `Mutation::Register::*` + `Input::Register::*` + `Payload::Register::*`
-   following the pattern of `Mutation::Page::*`.
-3. Expose `Builder::Register` from `GraphQL#register` (distinct from `#registers`
-   which is the compat search layer).
-
-Until then, register mutation callers must instantiate `Mutation::Register::*` directly
-(none exist yet), or use `Compat::Registers` for search.
-
-## Conventions
-
-- One builder per domain entity. Sub-builders (e.g. `LocationStructure::Draft`) are
-  nested under their parent builder's folder and exposed via a method on the parent.
-- Builder methods are snake_case public API; private helper methods are camelCase
-  (matching the existing convention: `updateMutation`, `archiveMutation`, etc.).
-- Builders never hold state — each method instantiates a fresh mutation/query object.
-- Builders do not implement pagination; callers use `QueryConnection#each` for that.
-
-## Related
-
-- `../mutation/` — concrete mutation classes that builders delegate to
-- `../query/` — concrete query classes (some builders also expose query shortcuts)
-- `../compat/` — v2-compatible layer (`Compat::Pages`, `Compat::Registers`) that
-  wraps builders + queries with an eco-helpers-compatible interface