ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/code/ecoPortal_architecture/00_overview_and_index.md

@@ -1,55 +0,0 @@
-# EcoPortal Architecture — Agent Reference Manual
-
-**Purpose:** Enable an AI agent to read this folder, then immediately navigate the
-ecoPortal source code, customer documentation, and integration gems with full context.
-Covers: platform purpose, data model, naming conventions, API layers, workflows,
-search, integrations, and documentation gaps.
-
-**Session:** Accumulated 2026-06-07 from developer context, production Insomnia queries,
-corpus documents, eco-helpers source audit, and GraphQL schema introspection.
-
----
-
-## Document Index
-
-| File | Content |
-|------|---------|
-| `00_overview_and_index.md` | This file — platform summary + index |
-| `01_terminology_dictionary.md` | Every name things are called — Rosetta Stone for disambiguating |
-| `02_data_model.md` | Page hierarchy, types, MongoDB structure, genome, field ID |
-| `03_api_layers.md` | APIv2 vs GraphQL — differences, retirement timeline, access |
-| `04_graphql_queries_mutations.md` | All known queries/mutations, fragments, CommonPageUnion |
-| `05_page_workflows.md` | Create/Update/Archive/Submit — 2-step sequences, stage logic |
-| `06_search_and_filters.md` | Org search vs register search, SearchConf, filter operations |
-| `07_data_fields.md` | All 20+ field types, DataFieldInput, update/addition patterns |
-| `08_stages_sections.md` | Stage lifecycle, permissions, sections, HasSectionsInterface |
-| `09_people_contractors_locations.md` | PersonMember, ContractorEntity, IdDiff, location tags |
-| `10_forces_workflow_builder.md` | Forces (AngularJS legacy), Workflow Builder (in progress) |
-| `11_integration_gems.md` | eco-helpers, ecoportal-api-v2, ecoportal-api-graphql chain |
-| `12_ai_documentation_sources_gaps.md` | All knowledge sources + gaps + improvements for AI agents |
-
----
-
-## Platform Summary
-
-EcoPortal is a SaaS **governance, risk and compliance (GRC)** platform built for
-enterprise customers. It enables organisations to manage:
-- Risk registers (pages = records in a workflow-driven register)
-- Incident reporting
-- Contractor management
-- Action tracking
-- Location/reporting structure management
-- Visitor management (check-in)
-- Notifications, dashboards, analytics
-
-**Technology stack:**
-- Backend: Ruby on Rails, MongoDB (NoSQL document store)
-- Frontend: AngularJS (legacy, being replaced) → React (current, in progress)
-- APIs: APIv2 REST (being retired), GraphQL (current standard)
-- Search/analytics: Elasticsearch
-- Deployment: Docker, cloud-hosted
-
-**Key architectural principle:** MongoDB's flexible document model means page records
-("instances") are cloned from templates. Field structure is defined in the template;
-field data is stored per-instance. Field IDs are assigned by MongoDB on creation and
-are instance-specific (not predictable from the template alone).

data/.ai-assistance/code/ecoPortal_architecture/01_terminology_dictionary.md

@@ -1,181 +0,0 @@
-# EcoPortal Terminology Dictionary
-
-An AI agent MUST read this before working with ecoPortal code or customer requests.
-The same concept has different names depending on who is talking and which layer of
-the system is being discussed. Misunderstanding these leads to wrong assumptions.
-
----
-
-## Core Entity Names
-
-### Pages / Records / Ooze / Forms
-
-| Context | Name used | Notes |
-|---------|-----------|-------|
-| Customer-facing (product UI) | **Page**, **Record** | "Page" is the UI term; "Record" used in registers |
-| eco-helpers scripts (internal) | **Ooze** | Internal dev shorthand, from legacy gem name |
-| eco-helpers class names | `OozeBase`, `RegisterUpdate` | Script use case base classes |
-| Confluence docs | **Page** | |
-| APIv2 gem | `Ecoportal::API::V2::Page` | |
-| GraphQL schema | `BasicPage`, `PhasedPage`, `PageUnion` | Two concrete types |
-| GraphQL queries | `page(id:)`, `pages(...)` | |
-| ecoportal-api-graphql gem | `Model::Page::Basic`, `Model::Page::Phased` | |
-
-**Disambiguation rule:** When a customer says "record" or "page", they mean a page
-instance — NOT a template. Templates are a separate concept (see below).
-
-### Stages / Workflow Steps / Flow Nodes
-
-| Context | Name used | Notes |
-|---------|-----------|-------|
-| Customer-facing (product UI) | **Stage** | |
-| Backend Enzyme namespace (old) | **flow_nodes** | Old Rails model name |
-| Backend NewEp namespace (current) | **stages** | |
-| APIv2 | **stages** | |
-| GraphQL schema | `Stage`, `StageIndex`, `StageStateEnum` | |
-| eco-helpers | **stages** | `page.stages[name]`, `page.stages.ordered` |
-
-### Sections / Content Containers / Flow Node Sub-elements
-
-| Context | Name used | Notes |
-|---------|-----------|-------|
-| Customer-facing (UI) | **Section** | Within a stage |
-| Backend Enzyme namespace (old) | **flow_nodes** sub-elements | No clean separation |
-| Backend NewEp namespace (current) | **sections** | `HasSectionsInterface` |
-| APIv2 | **sections** | `page.sections` |
-| GraphQL schema | `SectionUnion`, `ContentSection`, `SplitSection` | Two section types |
-| eco-helpers | **sections** | `entry.sections.get_by_type(:content_section)` |
-
-**Important:** BasicPage (no stages) has sections DIRECTLY. PhasedPage has sections
-WITHIN each stage. This is why `page.sections` on a PhasedPage requires knowing which
-stage you're in.
-
-### Data Fields / Components / Membranes / Field Instances
-
-| Context | Name used | Notes |
-|---------|-----------|-------|
-| Customer-facing (UI) | **Field** | Form field within a section |
-| Backend Enzyme namespace (old) | **Membrane**, `Enzyme::Membrane` | Old model name |
-| Backend NewEp namespace (current) | **DataField**, `NewEp::DataField` | |
-| APIv2 | **component** | `page.components`, `component.type` |
-| GraphQL schema | `DataFieldUnion`, `DataFieldsInterface` | 20+ concrete types |
-| eco-helpers | **components** | `entry.components.get_by_type(:plain_text)` |
-| ecoportal-api-graphql gem | `DataField::PlainText`, `DataField::Select`, etc. | |
-
-**CRITICAL:** A "field" in the UI is an INSTANCE of a field definition. The template
-defines the field structure (label, type, options). The page instance has the actual
-field with server-assigned MongoDB ID and stored value. The instance field ID CANNOT be
-predicted from the template alone — must be fetched after creation via `buildFromTemplate`.
-
-### Registers / Registries / Page Collections
-
-| Context | Name used | Notes |
-|---------|-----------|-------|
-| Customer-facing (UI) | **Register** | A themed collection of pages with a shared template |
-| GraphQL schema | `Register`, `register(id:)` | |
-| eco-helpers | **register** | `registers.search(register_id, ...)` |
-
-### Templates
-
-| Context | Name used | Notes |
-|---------|-----------|-------|
-| Customer-facing (UI) | **Template** | A "page type" defining field structure |
-| GraphQL schema | `PageUnion` (templates are also pages), `Template` type | |
-| eco-helpers | **template** | `pages.get_new(template_id)` |
-
-**IMPORTANT:** Engineering does NOT want templates updated via GraphQL currently.
-Template editing uses the old AngularJS front-end. Template mutations exist in the
-schema but are not production-approved for scripting.
-
----
-
-## Field-Level Terminology
-
-### ref / Field ID / ES Key / System ID (future)
-
-The `ref` property on a data field (`Enzyme::Membrane` / `NewEp::DataField`) is the
-**Elasticsearch index key** for that field. It determines how analytics, charts, filters,
-and cross-register configurations identify the field.
-
-**Composition:** `type_shorthand.hash_of_label`
-- `type_shorthand`: e.g. `plain_text`, `date`, `select_str`, `select_num`, `gauge`,
-  `rich_text`, `actions_list`, `files`
-- Hash of the label name (truncated when label > 3 characters)
-- Formula: `Ecoportal::API::Common::Content::StringDigest` in `ecoportal-api-v2`
-
-**Future:** The team is planning to formalise this as a user-visible "Field ID" (as
-opposed to the internal MongoDB `id`). Currently it is only used internally.
-
-**In search/sorters:** The `key` field in sorters (`{ key: 'updated_at', direction: 'asc' }`)
-references this ref value, not the MongoDB field `id`.
-
-### patchVer / Optimistic Concurrency
-
-`patchVer: Int!` on every page. The server uses this for optimistic concurrency control.
-**Any update mutation MUST include the current `patchVer` value fetched from the page.**
-If two scripts try to update the same page concurrently, the second will get a stale-patchVer
-error. Scripts must re-fetch the page to get the current `patchVer` before retrying.
-
-### Genome Signature (mostly unused)
-
-The genome signature was designed to pair fields ACROSS pages and their source templates.
-Purpose: know that "this field in page X is the same field as this field in template Y".
-**Current state:** Mostly unused. The Migrator Rails service that used it was abandoned.
-Not indexed in ES. Many fields have broken genomes due to bulk tech scripts that added
-fields without copying from the template. Do NOT design scripting around genome.
-
-### Forces (legacy front-end snippets)
-
-Forces are AngularJS embedded code snippets that attach to specific stages via bindings.
-They implement conditional field behaviour (show/hide sections, computed risk matrices).
-**Being replaced** by the Workflow Builder. Not accessible or useful via GraphQL.
-Low scripting priority.
-
----
-
-## State / Status Names
-
-### Page State (`StateEnum`)
-
-| Value | Meaning |
-|-------|---------|
-| `active` | Normal working state |
-| `archived` | Soft-deleted/hidden — can be unarchived |
-| `draft` | Not yet published (also `draft: Boolean` field) |
-| `inprogress` | In a workflow stage (used in some contexts) |
-
-### Stage State (`StageStateEnum`)
-
-| Value | Meaning |
-|-------|---------|
-| `pending` | Not yet started |
-| `inprogress` | Currently active |
-| `complete` | Completed (all tasks done) |
-
-### Task State
-
-Tasks (`TaskInterface`, `CompletePage`, `ReviewPage`) have their own states related to
-completion. Stage close-out is triggered by task completion.
-
----
-
-## API Layer Names
-
-| Layer | Name | Status |
-|-------|------|--------|
-| Legacy REST | **APIv2**, `ecoportal-api-v2` gem | Being retired (3 weeks from 2026-06-07) |
-| Current GraphQL | **GraphQL API**, `ecoportal-api-graphql` gem | Current standard |
-| Internal REST (auth) | **APIv1** (OAuth) | Still in use for authentication only |
-| Future | **APIv3** (page render / custom exports) | In development, not production |
-
----
-
-## Backend Namespace Names
-
-| Namespace | Description | Location |
-|-----------|-------------|----------|
-| `Enzyme` | Old Rails model namespace (AngularJS era) | `C:\docker\ecoPortal_master\` |
-| `NewEp` | Current Rails model namespace (React era migration) | Same repo |
-| `Ecoportal::API::V2` | REST API gem | `C:\ruby_scripts\git\ecoportal-api-v2` |
-| `Ecoportal::API::GraphQL` | GraphQL gem | THIS REPO |
-| `Eco` (eco-helpers) | Integration scripts helper gem | `C:\ruby_scripts\git\eco-helpers` |

data/.ai-assistance/code/ecoPortal_architecture/02_data_model.md

@@ -1,192 +0,0 @@
-# EcoPortal Data Model
-
----
-
-## Top-Level Hierarchy
-
-```
-Organisation
-  ├── Registers (themed page collections)
-  │     ├── Templates (page type definitions)
-  │     │     ├── Stages (workflow steps — PhasedPage templates)
-  │     │     │     └── Sections
-  │     │     │           └── DataField definitions (with label, type, options)
-  │     │     └── Sections (for BasicPage templates)
-  │     │           └── DataField definitions
-  │     └── Pages / Instances (created from templates)
-  │           ├── [BasicPage] Sections → DataFields (actual data, server IDs)
-  │           └── [PhasedPage] Stages → Sections → DataFields (actual data, server IDs)
-  ├── People (PersonMember)
-  ├── Contractor Entities
-  ├── Location Structure (reporting structure / RS)
-  │     └── Location Nodes (hierarchical tree)
-  ├── Actions (standalone or linked to pages)
-  └── User Groups / Permissions
-```
-
----
-
-## `externalId` — per-org unique key for integrations (VERIFIED, Oscar 2026-07-02)
-
-`externalId` exists on models (pages, and other objects) as the **integration pairing key**:
-
-- **Uniqueness is per-organization, per-model:** an `externalId` must be unique among objects of
-  the *same model* within one ecoPortal organization. It is the mechanism the platform uses to
-  **prevent double-ups** and to give a customer integration a stable way to **pair its own record
-  ids with ecoPortal's objects** (set `externalId` = the customer's key; look up / upsert by it).
-- **Implication for integrations:** when you control the source data, prefer keying create/upsert
-  on `externalId` (guaranteed unique, server-enforced) over searching a data-field value. A
-  field-value search can miss (wrong key, analyzer semantics — see the cans-upsert dup incident in
-  `search_filters.md`) and silently create duplicates; an `externalId` collision is rejected.
-- **Archiving contingency:** clear the `externalId` only when archiving is a *cleanup of a failed /
-  duplicate creation* (so the freed id can be reused); a genuine historical archive should **keep**
-  its `externalId`. The backend `archivePage` mutation takes only `id` (no clear-externalId arg), so
-  this is a **client composition**: `updatePage(page:{externalId:null})` + `archivePage`, in one
-  document (the maintainer's Insomnia sample gates the updatePage with `@include(if:$blank_external_id)`).
-  WIRED as **`Builder::Page#archive(clear_external_id: false)`** (default keeps it) — implemented as
-  two serial mutations (blank-then-archive) reusing the existing update/archive mutations.
-- **Note:** the cans-upsert case does NOT use `externalId` (it keys on the `Identifier:` data
-  field) — which is exactly why a wrong search key produced duplicates. An `externalId`-based
-  upsert would have been collision-safe.
-
----
-
-## Page Types (PageUnion)
-
-The GraphQL `PageUnion = BasicPage | PhasedPage`. Both implement `BasePageInterface`.
-
-### BasicPage
-
-- Has sections DIRECTLY (no stages)
-- Used for: simple forms, non-workflow records
-- `implements: BasePageInterface, HasSectionsInterface`
-- `sections: [SectionUnion!]!` — direct access
-
-### PhasedPage
-
-- Has stages, each stage has sections
-- Used for: workflow-driven records (risk assessments, incident reports, inspections)
-- `implements: BasePageInterface`
-- `stages: [Stage!]!` — access via StageCollection
-- `stagesIndex: [StageIndex!]!` — lightweight stage summary
-- `currentStage: Stage!` — the currently active stage
-
-### Identifying the Type
-
-Always include `__typename` in page queries. The server returns `'BasicPage'` or
-`'PhasedPage'`. In the ecoportal-api-graphql gem, `Model::PageUnion.new(doc)` dispatches
-on `__typename` to create the right concrete class.
-
----
-
-## MongoDB Document Structure
-
-Pages are stored as MongoDB documents. The document structure is flexible — field
-instances are embedded within the stage/section hierarchy.
-
-**Key implications:**
-1. **Field IDs are MongoDB ObjectIds** assigned at creation. They are DIFFERENT from
-   the template's field IDs. An instance field ID cannot be predicted — must be fetched.
-2. **patchVer** is an integer version counter incremented on every save. Required for
-   all update mutations.
-3. **Partial updates** — the GraphQL `updatePage` mutation only changes the fields you
-   specify. The rest remain unchanged. This is different from APIv2 which sometimes sent
-   the full document.
-4. **Stages are embedded** within the page document. Fetching a page gets all stages.
-
----
-
-## Template vs Instance
-
-| Aspect | Template | Instance (Page) |
-|--------|----------|-----------------|
-| Created by | Admins via UI | Scripts or end users |
-| Field IDs | Template-specific ObjectIds | NEW ObjectIds assigned on creation |
-| patchVer | Yes | Yes |
-| Stage structure | Defines stage names/order | Inherited at creation, runtime state |
-| DataField content | Default values only | Actual user-entered values |
-| GraphQL access | `templates(...)` query | `pages(...)` or `page(id:)` |
-
-**CRITICAL for scripting:** After `buildFromTemplate`, the response contains the
-INSTANCE field IDs. These are the IDs to use for `dataFields.updates` in
-`createFromTemplate`. The template field IDs are irrelevant for instance operations.
-
----
-
-## Stage Model (PhasedPage)
-
-Each stage in a PhasedPage:
-- Has a unique `id` (MongoDB ObjectId)
-- Has `name` (the stage name configured in the template)
-- Has `ordering` (display order, integer)
-- Has `state` (`StageStateEnum`: pending/inprogress/complete)
-- Has `active: Boolean` (whether stage is currently active for input)
-- Has `started: Boolean` (whether any input has been recorded)
-- Has `sections: [SectionUnion!]!` — the stage's content sections
-- Has task references: `latestCompletePageTask`, `latestReviewPageTask`, `activeTask`
-
-**Stage permissions:**
-- Each stage can have user group restrictions
-- People fields can grant direct stage access based on their values
-- Configuration enum on people fields determines scope (stage-specific vs page-wide)
-- GraphQL silently omits stages the user cannot access (no access errors)
-
-**Stage transitions:**
-- Triggered by task completion (complete task = stage done → next stage starts)
-- Two task types: `CompletePage` (fill-in) and `ReviewPage` (sign-off)
-- Submitting a stage via GraphQL `updatePage(stageId:, submit: true)` triggers the
-  server-side task assignment rules (who gets the next task per workflow config)
-
----
-
-## Section Model
-
-Two types (`SectionUnion = ContentSection | SplitSection`):
-
-### ContentSection
-- `heading: String` — section heading
-- `dataFields: [DataFieldUnion!]!` — fields in this section
-
-### SplitSection
-- `heading: String`
-- `leftDataFields: [DataFieldUnion!]!`
-- `rightDataFields: [DataFieldUnion!]!`
-
-Both implement `HasSectionsInterface`. When a section's fields need to be accessed
-together, merge `dataFields + leftDataFields + rightDataFields`.
-
----
-
-## Genome Signature (Field Pairing — Mostly Unused)
-
-Each field definition (in template and in instances) carries a **genome signature** —
-a hash intended to identify that a field is "the same" across template and instances.
-
-**Original design:** Enable the Migrator service to propagate template changes to
-existing pages by pairing fields via genome.
-
-**Current reality:**
-- Largely abandoned — the Migrator service is inactive
-- Many instances have broken genomes (bulk tech scripts that added fields
-  without copying from the template gave them random creation-time genomes)
-- Not indexed in Elasticsearch
-- Unknown whether `NewEp` fully ported the genome from `Enzyme`
-- Do NOT design scripting logic around genome — it cannot be relied upon
-
----
-
-## Location Structure (Reporting Structure)
-
-The organisation has a hierarchical location tree. Locations are used for:
-- Tagging pages (assigning pages to locations/departments)
-- Filtering in searches (`location_ids` filter)
-- Permissions scoping
-- Analytics/dashboard scoping
-
-The location tree is managed via dedicated mutations (`draft` system for structural edits).
-Location nodes have: `id`, `name`, `weight`, `archived`, `archivedToken`, `classifications`,
-`ancestors`, `parent`, `children`.
-
-**`baseTags` vs `otherTags`:**
-- `baseTags` — location tags inherited from the base template configuration
-- `otherTags` — additional free-text tags attached to a page instance

data/.ai-assistance/code/ecoPortal_architecture/03_api_layers.md

@@ -1,147 +0,0 @@
-# EcoPortal API Layers
-
----
-
-## Overview
-
-EcoPortal has three API access layers, each serving different purposes and eras:
-
-| Layer | Type | Status | gem |
-|-------|------|--------|-----|
-| APIv1 (OAuth) | REST | Active — auth only | n/a (direct HTTP) |
-| APIv2 | REST | **BEING RETIRED** (~2026-06-07 + 3 weeks) | `ecoportal-api-v2` |
-| GraphQL API | GraphQL | **Current standard** | `ecoportal-api-graphql` |
-| APIv3 (page render) | REST (likely) | In development — custom exports | Not yet public |
-
----
-
-## Authentication (APIv1 / OAuth)
-
-All access goes through OAuth 2.0 password grant:
-
-```
-POST https://live.ecoportal.com/oauth/token
-Content-Type: application/json
-
-{
-  "grant_type": "password",
-  "email": "user@example.com",
-  "password": "..."
-}
-```
-
-Response includes `access_token` (Bearer) and `refresh_token`.
-
-**Token refresh:**
-```
-POST /oauth/token
-{ "grant_type": "refresh_token", "refresh_token": "..." }
-```
-
-The `access_token` is passed as `Authorization: Bearer <token>` on all subsequent calls.
-
----
-
-## APIv2 (REST) — Being Retired
-
-**Base URL:** `https://live.ecoportal.com/api/<org_id>/`
-
-**Ruby gem:** `Ecoportal::API::V2` in `ecoportal-api-v2`
-
-**Local path:** `C:\ruby_scripts\git\ecoportal-api-v2`
-
-**Key characteristics:**
-- REST API with resource-based endpoints
-- Returns full page documents as JSON
-- Stage rendering: one GET request per stage (pages with stages must be fetched
-  stage-by-stage due to access control — each stage can have different user permissions)
-- Only pages WITHOUT stages AND templates can be fetched/updated as a whole document
-- Full document sent on update (partial updates not cleanly supported)
-- Page updates tracked via `as_update` (dirty diff) which generates a JSON patch
-
-**eco-helpers interface:**
-```ruby
-apiv2.pages.get(id, stage_id: nil)        # fetch page (or specific stage)
-apiv2.pages.get_new(template_id)           # build draft from template
-apiv2.pages.create(page, from: template_id) # create instance
-apiv2.pages.update(page)                   # save changes
-apiv2.registers.search(register_id, opts) { |result| ... }  # paginated search
-```
-
----
-
-## GraphQL API — Current Standard
-
-**Endpoint:** `POST https://live.ecoportal.com/api/<org_id>/external/graphql`
-
-**Headers required:**
-- `Content-Type: application/json`
-- `Authorization: Bearer <access_token>`
-
-**Request payload:**
-```json
-{
-  "query": "query MyQuery($id: ID!) { ... }",
-  "variables": { "id": "..." },
-  "operationName": "MyQuery"
-}
-```
-
-**Key characteristics:**
-- ONE endpoint — no URL variation by resource
-- Client specifies exactly which fields to return
-- Full page fetched in ONE request (all stages included)
-- Stage-specific operations via `stageId` parameter
-- `patchVer` required on all update mutations (optimistic concurrency)
-- Multiple mutations can be combined in one request (executed in declaration order)
-- `searchConf` is a Hash type (`Search`) — not a typed GraphQL input
-
-**GraphQL gem:** `Ecoportal::API::GraphQL` in `ecoportal-api-graphql`
-
-**Local path:** `C:\ruby_scripts\git\ecoportal-api-graphql` (THIS REPO)
-
-**Schema reference:** Live schema at `https://live.ecoportal.com/api-docs/graphql`
-(requires login). Updated on every deployment.
-
----
-
-## APIv3 (Page Render / Custom Exports) — In Development
-
-**Purpose:** Custom page rendering for exports (PDF, etc.). Provides a page render
-endpoint separate from the main GraphQL API.
-
-**Status:** In development as of 2026-06-07. Not yet production-stable for scripting.
-Not covered in this gem.
-
----
-
-## APIv2 vs GraphQL: Key Differences for Scripts
-
-| Concern | APIv2 | GraphQL |
-|---------|-------|---------|
-| Stage fetch | One request per stage | Full page in one request |
-| Field IDs | Available after get | Available after buildFromTemplate |
-| Update scope | Full doc or stage doc | Partial: only specify what changes |
-| patchVer | Not required (v2 handles internally) | **REQUIRED** on all updates |
-| Filter format | `{ type: "date_filter", lbound:, ubound: }` | `{ operation: "date_filter", params: { gte:, lte: } }` |
-| Archived pages | Search returns them with flag | Default excluded; `includeArchived: true` opt-in |
-| Template update | Supported | **NOT recommended** (Engineering block) |
-| Search result | Full page data | Org: full DB page; Register: ES preview only |
-
----
-
-## eco-helpers Compat Layer
-
-Since APIv2 is being retired, the `ecoportal-api-graphql` gem provides a compatibility
-layer so existing eco-helpers scripts can work without modification:
-
-```ruby
-graphql = Ecoportal::API::GraphQL.new(email:, pass:, org_id:)
-graphql.pages     # → Compat::Pages (same interface as apiv2.pages)
-graphql.registers # → Compat::Registers (same interface as apiv2.registers)
-```
-
-Page models include `Concerns::SnakeCamelAccess` — all camelCase methods accessible
-as snake_case (`external_id`, `patch_ver`, `source_template_id`, `creator_name`, etc.).
-
-See `11_integration_gems.md` for full compat layer details.