ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/projects/api-v2-to-graphql-migration/notes/cutover-usecase-gap-audit.md

@@ -0,0 +1,139 @@
+# Cutover gap audit — 3 use cases on GraphQL (TODO 8.5)
+
+## Update — 2026-06-29
+
+> Status refresh after the WRITE/value/submit path went **live-green** on `mini`. The full
+> mini automated suite now runs **35/35**. Several items the 2026-06-28 audit listed as gaps
+> or "coded-but-untested" are now RESOLVED and live-validated. History below is preserved;
+> read the per-use-case lines together with this block.
+
+**RESOLVED since the 2026-06-28 audit:**
+- **Field value round-trips (TODO 8.1) — DONE & LIVE-GREEN.** PlainText, Number, Select,
+  People (`people_ids`), CrossReference (`page_ids`/`reference_ids`) all round-trip
+  (set → `updatePage` → re-read → persisted). The P2 "coded-but-untested array writes"
+  (People `<<`, CrossRef `add`/`clear`) are now **validated live** — full mini suite 35/35.
+- **`submit!` / stage completion (TODO 8.2) — DONE & LIVE-GREEN.** Root cause of the old
+  stuck-stage failure: the stage carries a **review-task config**, so `completePageTask`
+  ALONE moves it to "reviewing" and never advances. Fix =
+  `updatePage(submit: true, task: { completePageTask: { signOff: true } })` — the inline
+  sign-off auto-approves the review and advances the stage. Gem gained sugar:
+  `Input::Page::Update.from_model(complete_page_task: { sign_off:, forced_complete:, notes: })`.
+  New test `compat_v2/page/submit_signoff_on_create` passes; old `stage_submit` flipped to the
+  confirmed call.
+- **Phased write-path identity (was P0 — "the most important gem fix") — RESOLVED & validated**
+  via `compat_v2/page/stage_write`: a value set through `stage.components` now persists through
+  `updatePage`. The `stage.components` vs flat `page.field_collection` dup'd-doc risk is closed.
+- **`get_by_name(type:)` — DONE** (2026-06-28).
+- **FilterTranslator `text_filter`→`match_filter`, `options_filter`→`one_of`/`none_of` — LANDED**
+  (commit 7725f96). Reclassified from a **code gap** to a **validation item**: still needs LIVE
+  validation against a real `registers.search` (see 8.3 below). Not a blocker for the translator
+  existing.
+
+**STILL OUTSTANDING (carry forward):**
+- **BasicPage reads (TODO 8.4)** — `CommonPageUnion` lacks `... on BasicPage { sections }`,
+  so basic pages get `corePageData` only. **IN PROGRESS** on branch `cutover/basicpage-sections`.
+- **Live-validate translated text/options filters (TODO 8.3)** — confirm `match_filter` /
+  `one_of`/`none_of` against a real `registers.search` on `mini`.
+- **Gem RSpec read-path regression specs (TODO 8.6)** — **IN PROGRESS** on branch
+  `cutover/regression-specs-8-6`.
+- **Collection-level write review (TODO 8.7)** — add/remove/reorder fields, multi-section
+  identity; deferred from the phased-flatten work.
+- **eco-helpers** — farmers must `include OozeRedirect` (else hits the dead v2 server);
+  `submit!` must pass `stageId` + map `force:` → `forced_complete:` (the gem now supports
+  `forced_complete:`; eco-helpers draft in progress).
+- **cans dedup rework** — membranes previews carry no field values (customer script).
+- **Release/pin the `pages` branch — HARD PREREQUISITE.** Released 1.3.4 lacks `base/page/`;
+  FieldPatches silently no-op against it.
+
+---
+
+> Audited 2026-06-28 (background pass). Gem `pages` branch + eco-helpers OozeRedirect.
+> Two compat layers: the **gem** (`Compat::Pages`/`Registers` + native `DataField` DSL) and
+> **eco-helpers `OozeRedirect`** (`FieldPatches.apply!` monkey-patches the gem field classes
+> to add the v2-API methods `select`/`values`/`options`, CrossRef `add`/`clear`/`reference_ids`,
+> dirty `people_ids <<`, `submit!`, and the v2 `===` dispatch). The v2-API field methods come
+> from FieldPatches, NOT the gem. Memory: [[project-apiv2-cutover-usecases]].
+
+## Cross-cutting facts (verified)
+- `session.api(version: :oozes)` → `:v2` → **dead v2 server** unless `OozeRedirect#api_v2/apiv2`
+  aliases it to `graphql`. Only classes that `include OozeRedirect` get the redirect.
+- `Collection#get_by_name` took **one arg** (no `type:`) — **FIXED 2026-06-28** (added `type:`).
+- **Phased write-path identity risk (HIGH)** — **RESOLVED 2026-06-29** (see Update block).
+  *Original concern:* `DataField.new`/`Section.new` `.dup` their raw doc; a phased page builds
+  TWO independent `DataField::Collection`s (flat `page.field_collection` vs `Stage#components`
+  → `sections.components`), so mutating a field from `stage.components` might not reach the page
+  update payload. *Outcome:* `compat_v2/page/stage_write` confirms a value set via
+  `stage.components` now persists through `updatePage`. cans + toocs `with_fields` writes reach
+  the payload.
+
+## Per-use-case status
+**farmers / supplier_documents** (`Custom::UseCase`, **no OozeRedirect**, no stages):
+- 🔴 `api_v2 = session.api(version: :oozes)` → dead v2 server (no redirect). **Biggest gap** —
+  `include OozeRedirect` or switch to `session.api(version: :graphql)`. Despite the old "do
+  FIRST / most compat-friendly" note, farmers is the **least ready** (bypasses OozeRedirect).
+- 🟠 `options_filter` → `one_of`/`none_of` now **translated** in FilterTranslator (commit 7725f96);
+  needs LIVE validation against a real `registers.search` (8.3).
+- 🔴 Select `.values`/`.select`, CrossRef `.add` — FieldPatches-only; won't load for a
+  non-OozeRedirect class → NoMethodError.
+- ✅ (now) `get_by_name(..., type:)` — gem fix landed.
+- ✅ `registers.search` date_filter, `pages.get`/`get_new`/`create`/`update` (flat).
+- ✅ Field value round-trips (PlainText/Number/Select/People/CrossRef) — LIVE-GREEN 2026-06-29.
+
+**jamestrong / cans_upsert** (`OozeSamples::TargetOozesUpdateCase`, includes OozeRedirect, phased 'Details'):
+- 🟠 `text_filter` → `match_filter` now **translated** (commit 7725f96); needs LIVE validation (8.3).
+- 🔴 dedup via `page_result.membranes` — previews carry no field values; rework to fetch full
+  page per candidate or server-side filter.
+- 🟠 `submit!` sent with no `stageId` (script submits a specific stage) — eco-helpers must pass
+  `stageId`; draft in progress. (Stage *completion* mechanics now confirmed — see ✅.)
+- ✅ **phased write-path identity** — RESOLVED 2026-06-29 (`stage.components` writes persist via
+  `updatePage`; `compat_v2/page/stage_write`).
+- ✅ `submit!`/stage completion mechanics — confirmed 2026-06-29:
+  `updatePage(submit: true, task: { completePageTask: { signOff: true } })` advances a
+  review-task stage (`compat_v2/page/submit_signoff_on_create`).
+- ✅ search query, stage lookup, v2 `===` dispatch, PlainText/Number `value=`, Select
+  `select`/`values`/`options` (live-validated).
+
+**act-gov / toocs_coding** (`OozeSamples::TargetOozesUpdateCase`, includes OozeRedirect, phased 'Coding'):
+- ✅ People `people_ids <<` + CrossRef `add`/`clear` — **VALIDATED LIVE 2026-06-29** (the
+  previously-skipped array writes; full mini suite 35/35).
+- 🟠 `submit!(force: true)` — gem now supports `forced_complete:` (via
+  `from_model(complete_page_task: { forced_complete: })`); eco-helpers still needs to map
+  `force:` → `forced_complete:` and pass `stageId`. Draft in progress.
+- ✅ **phased write-path identity** — RESOLVED 2026-06-29 (same fix as cans; `stage_write`).
+- ✅ v2 `===` (People/CrossRef), CrossRef `reference_ids`/`clear`, stage lookup.
+
+## Prioritized remaining work
+
+> Re-prioritized 2026-06-29. The old P0 gem blockers (phased write-path identity, value
+> round-trips, submit!/stage advance) are RESOLVED & live-green. What remains is mostly
+> validation, eco-helpers/script wiring, and the release gate.
+
+**P0 (blockers):**
+1. **Release/pin `pages`** — released 1.3.4 lacks `base/page/`; FieldPatches silently no-op.
+   **HARD PREREQUISITE** for everything downstream.
+2. **farmers** — wire `include OozeRedirect` (or `session.api(version: :graphql)`) so it stops
+   hitting the dead v2 server. (script/eco-helpers)
+
+**P0 — RESOLVED 2026-06-29 (kept for history):**
+- ✅ **Phased write-path identity** — `stage.components` mutations now reach `updatePage`
+   (cans+toocs); validated `compat_v2/page/stage_write`. Was "most important gem fix".
+- ✅ **Field value round-trips (8.1)** — PlainText/Number/Select/People/CrossRef live-green.
+- ✅ **`submit!`/stage completion (8.2)** — review-task stage advances via inline sign-off.
+
+**P1 (functional gaps / validation):**
+3. ✅ `Collection#get_by_name(type:)` — DONE 2026-06-28.
+4. ✅ `FilterTranslator`: `text_filter`→`match_filter`, `options_filter`→`one_of`/`none_of`
+   — LANDED 2026-06-29 (commit 7725f96). **Now a validation item, not a code gap:** LIVE-validate
+   against a real `registers.search` (8.3). `compat/filter_translator.rb`.
+5. **BasicPage reads (8.4)** — add `... on BasicPage { sections }` to `CommonPageUnion`.
+   IN PROGRESS on branch `cutover/basicpage-sections`.
+6. **Gem RSpec read-path regression specs (8.6)** — IN PROGRESS on branch
+   `cutover/regression-specs-8-6`.
+7. **Collection-level write review (8.7)** — add/remove/reorder fields, multi-section identity.
+8. cans dedup rework (membranes → full-page fetch / server-side filter). (script)
+9. eco-helpers `submit!` — pass `stageId` + map `force:` → `forced_complete:` (gem supports it).
+   Draft in progress.
+
+**P2 (validate coded-but-untested):** ✅ People `<<` + CrossRef `add`/`clear` array writes
+— VALIDATED LIVE 2026-06-29 (mini suite 35/35). Remaining P2 validation = search filters
+live (8.3, folded into P1#4 above).

data/.ai-assistance/projects/dynamic-model-generation/INTENT.md

@@ -0,0 +1,93 @@
+# Project: Dynamic / Auto-generated GraphQL Models
+
+**Created:** 2026-06-05
+**Status:** idea — not started
+**Depends on:** `ecoportal-api-v2-doublemodel-review` project (DoubleModel must be stable first)
+
+---
+
+## Goal
+
+Explore generating the `ecoportal-api-graphql` model layer from the GraphQL schema, rather
+than hand-authoring Ruby classes for every type. Two variants to evaluate:
+
+- **Static generation** — run a generator at gem-build time (or as a developer task) that
+  produces Ruby source files from schema introspection. Output is committed and readable.
+- **Dynamic generation** — generate model classes at Ruby load time (per execution), from
+  the live schema or a cached schema file.
+
+---
+
+## Motivation
+
+The current hand-authored model layer requires manual updates whenever the ecoPortal GraphQL
+schema evolves. Auto-generation would eliminate that maintenance burden and make the client
+automatically up to date with the schema.
+
+---
+
+## Hard Constraints
+
+These are non-negotiable design requirements, arising from how the `ecoportal-api-*` gem
+family is used in practice:
+
+### 1. Transparency to the source of backend issues
+
+The `ecoportal-api-*` gems are deliberately designed so that when an ecoPortal backend
+returns an unexpected response, the problem is easy to trace — there is static code to
+read and point to. Integration teams and the engineering team both rely on this to avoid
+prolonged debates about whether a bug is client-side or server-side.
+
+Any model generation approach must preserve this traceability. Concretely:
+
+- A generated (or dynamically created) model class must produce a log entry (at an
+  appropriate level) when it encounters a field it did not expect, or when a field it
+  expected is absent from the response.
+- Silent field drops, silent type coercions, and silent diff misses are not acceptable.
+- Where auto-generation is used, there must be a deterministic and inspectable record
+  of what was generated and from which schema version — ideally committed source files
+  for the static variant, or a structured schema-version log for the dynamic variant.
+
+### 2. Integration with `ecoportal-api-v2` DoubleModel
+
+The `as_update` / `as_input` diff pipeline relies on the `DoubleModel` contract:
+`doc` (current state), `original_doc` (server-confirmed state), `initial_doc` (state
+at render time). Auto-generated models must honour this contract fully — including
+cascaded diff, `root?` / `read_only?` semantics, and `patch_ver` propagation.
+
+This is why this project depends on the DoubleModel review being complete first: the
+contract must be stable and well-specified before we try to generate classes that
+implement it.
+
+### 3. Render-to-mutation conversion gap
+
+GraphQL schema definitions cannot express how a render model converts to a mutation
+input model. This is a permanent gap in the GraphQL specification. Any model generation
+approach must either:
+- Generate the render model only, leaving mutation input classes hand-authored (acceptable),
+- Or provide a deterministic, scriptable convention for deriving mutation input shapes
+  from render models — not an AI-generated approximation.
+
+Ad-hoc or AI-generated conversion code is not acceptable as the primary mechanism here,
+because it cannot be deterministically verified.
+
+---
+
+## Open Questions
+
+- Static vs dynamic: the dynamic variant is technically more interesting but harder to
+  debug when a field silently misroutes a diff. Static generation + commit is more
+  transparent. Which is the right default?
+- Can the `DoubleModel` contract be expressed as a generator template robustly enough
+  to produce correct `doc` / `original_doc` handling for Array-indexed (CollectionModel)
+  paths? This is likely the hardest part.
+- How do we handle schema evolution between gem releases? Version-lock the schema file?
+  Validate at load time?
+
+---
+
+## Out of scope until DoubleModel review is complete
+
+Do not begin design or implementation of this project until
+`.ai-assistance/projects/ecoportal-api-v2-doublemodel-review` reaches a stable conclusion
+on the `doc` memoization and sync semantics.

data/.ai-assistance/projects/eco-helpers-compat/INTENT.md

@@ -0,0 +1,244 @@
+# Project: eco-helpers GraphQL Compat Layer
+
+**Created:** 2026-06-07
+**Status:** Starting — URGENT (APIv2 retires in ~3 weeks)
+
+---
+
+## Goal
+
+Existing eco-helpers scripts work against `ecoportal-api-v2` (REST). They must continue
+to work against `ecoportal-api-graphql` (GraphQL) **without changing one line of script code**
+related to pages.
+
+The compat layer wraps `Ecoportal::API::GraphQL` and exposes the same interface that
+eco-helpers scripts currently call against `Ecoportal::API::V2`.
+
+---
+
+## eco-helpers API Surface (audited 2026-06-07)
+
+### Pages
+
+| v2 call | Description | GraphQL equivalent |
+|---|---|---|
+| `apiv2.pages.get(id)` | Fetch page by ID | `Query::Page.new(client).query(id: id)` |
+| `apiv2.pages.get_new(template_id)` | Build draft from template | `Mutation::Page::BuildFromTemplate` (via `buildPageFromTemplate`) |
+| `apiv2.pages.create(page, from: template_id)` | Create from filled draft | `Mutation::Page::CreateFromTemplate` |
+| `apiv2.pages.update(page)` | Update changed page | `Mutation::Page::Update` with `Input::Page::Update.from_model` |
+| `apiv2.pages.get_body(page)` | Get patch doc of changes | `page.as_update` |
+
+### Registers / Search
+
+| v2 call | Description | GraphQL equivalent |
+|---|---|---|
+| `apiv2.registers.search(register_id, opts) { \|r\| }` | Paginated search | `Query::RegisterPreviewPages` (fast/ES) for existence; org search for full data |
+
+Search options v2 → GraphQL mapping:
+- `sort: 'created_at'`, `dir: 'asc'` → `SearchConf.new.sort(:created_at, :asc)`
+- `query: text` → `SearchConf.new.query(text)`
+- `filters: [...]` → `SearchConf` with appropriate filter objects
+
+### Page object API
+
+| v2 accessor | v2 type | GraphQL equivalent |
+|---|---|---|
+| `.id` | String | `Model::Page::Basic#id` |
+| `.state` | String | `#state` |
+| `.template_id` | String | `#sourceTemplateId` |
+| `.created_at` | String | `#createdAt` |
+| `.updated_at` | String | `#updatedAt` |
+| `.stages?` | Boolean | `#stages.any?` |
+| `.current_stage_id` | String | `Model::Page::Phased#currentStage.id` |
+| `.stages` | Collection | `#stages` |
+| `.stages.get_by_name(name)` | Stage | filtered stages |
+| `.sections` | Collection | stage `.sections` or BasicPage `.sections` |
+| `.components` | Collection | sections → dataFields (APIv2 name for fields) |
+| `.tags` | Array | `#otherTags` (or `#baseTags` for base tags) |
+| `.base_tags` | Array | `#baseTags` |
+| `.external_id` | String | `#externalId` |
+| `.validate` | String or nil | custom validation (not in GraphQL schema) |
+| `page.consolidate!` | void | `page.original_doc = page.doc.dup` (reset dirty tracking) |
+
+### Dirty state tracking
+
+v2 uses `dirty?(page)` which checks if `patch_doc(page)['page']` is non-empty.
+GraphQL uses `page.as_update` — returns nil if no changes, hash if changed.
+
+Equivalence:
+```ruby
+# v2
+dirty?(page)
+# GraphQL compat
+!page.as_update.nil?
+```
+
+### Response objects
+
+| v2 | GraphQL |
+|---|---|
+| `response.success?` | `payload.success?` |
+| `response.status` | `payload.error? ? :error : :ok` |
+| `response.body` | `payload.error_doc` |
+
+---
+
+## Design: CompatPages and CompatRegisters
+
+Two wrapper objects that expose the v2-compatible interface:
+
+```ruby
+module Ecoportal::API::GraphQL::Compat
+  class Pages
+    def initialize(client); @client = client; end
+    def get(id, **kargs) = ...
+    def get_new(template_id) = ...
+    def create(page, from:) = ...
+    def update(page) = ...
+    def get_body(page) = page.as_update
+  end
+
+  class Registers
+    def initialize(client); @client = client; end
+    def search(register_id, options = {}, &block) = ...
+  end
+end
+```
+
+And on the top-level `Ecoportal::API::GraphQL` class:
+```ruby
+def pages     = Compat::Pages.new(client)
+def registers = Compat::Registers.new(client)
+```
+
+**Key constraints:**
+- `pages.get` must return an object that responds to all page accessors above
+- `pages.create` must return a reference object with `.page_id` and `.active_stage_id`
+- `page.consolidate!` must reset dirty state
+- `registers.search` must yield results in the same shape as v2 (block with `.id`)
+
+---
+
+## Architectural Differences: APIv2 vs GraphQL (critical for compat)
+
+### Stage rendering and updating
+
+**APIv2:** Instance pages (pages with stages) are rendered ONE STAGE PER REQUEST.
+Every `pages.get(id, stage_id:)` call fetches a single stage view. Updating is also
+done per-stage. This is a known limitation.
+
+**GraphQL:** Fetches the full page in one request. Can update all stages at once via
+`updatePage`. Can also do stage-specific updates via `stageId` in `UpdatePageInput`.
+
+**Implication for compat:**
+- eco-helpers `RegisterUpdate` loops through stages by fetching each one. In GraphQL
+  compat, we fetch the full page once and let the script work on a client-side stage view.
+- Stage-specific submit (e.g. close-out stage N to trigger fill-in task on stage N+1)
+  STILL requires `stageId` in the GraphQL mutation. The submit trigger (creating/starting
+  the next fill-in task) is server-side logic keyed on `stageId`.
+- `Compat::Pages#get(id, stage_id:)` currently ignores `stage_id` — this is a GAP.
+  A future improvement: if `stage_id` is provided, filter the returned page to show only
+  that stage's fields. But the mutation must still include `stageId`.
+
+### Stage permissions
+
+**APIv2:** Per-stage permissions enforced at fetch time — requesting a forbidden stage
+returns no data or an error.
+
+**GraphQL:** Stage data is included or excluded silently based on permissions — no
+access errors, just reduced data. A stage the user can't access simply won't appear in
+`stages` or `stagesIndex`. (Needs double-check with Engineering.)
+
+**Implication:** Scripts that rely on access errors from APIv2 to detect permission
+boundaries may not get the same signal from GraphQL. Scripts should check whether the
+stage they expect is present in the response.
+
+### `as_update` usage in eco-helpers
+
+`as_update` is called in eco-helpers for two purposes:
+1. **Simulate/dry_run mode:** Print what would change without sending the request.
+2. **Dirty detection:** `dirty?(page)` = `!page.as_update.nil?` (v2 pattern).
+
+Our compat `dirty?` already delegates to `as_update` via `PageCompat`. ✓
+
+For simulate mode: when `graphql.pages.update(page)` is called in dry_run mode,
+eco-helpers should call `pages.get_body(page)` (= `page.as_update`) and display the
+diff without making the HTTP request.
+
+### `add_component` / `add_field` gap
+
+APIv2 allows adding NEW fields to a page via `components.add(...)`. In GraphQL,
+`updatePage` has `dataFields: { additions: [DataFieldInput], updates: [...], deletions: [ID] }`.
+We implemented `updates` only. `additions` is not yet supported in the compat layer.
+
+**Consequence:** Scripts that call `add_field` or `components.add` will not work yet.
+This is a known gap. Document it for the integration test phase.
+
+### `apiv2.pages.create|update` redirect
+
+The eco-helpers `Eco::API::Session` manages an `apiv2` object. Redirecting to GraphQL
+requires swapping the `apiv2` session backend without changing scripts. Two approaches:
+
+1. **Session-level swap (eco-helpers):** Override `apiv2.pages` and `apiv2.registers`
+   in the eco-helpers session to return the GraphQL compat objects. Scripts are unchanged.
+   This is the cleanest approach for the 3-week deadline.
+
+2. **Proxy class:** Create `Ecoportal::API::GraphQL::V2Proxy` that mimics the full V2
+   API surface. Assign this as the session backend when GraphQL mode is active.
+
+The GraphQL gem already provides `graphql.pages` and `graphql.registers`. The eco-helpers
+change is only in how the session wires the backend — NOT in the scripts themselves.
+
+### Template updates
+
+Engineering does NOT want template updates via GraphQL currently — templates are still
+managed via the old AngularJS front-end. Do NOT expose template mutation endpoints from
+the compat layer. `Query::Templates` (read-only list) is fine. Mutations against templates
+should be blocked or at minimum undocumented.
+
+### Forces (AngularJS front-end snippets)
+
+Forces are embedded front-end code snippets that attach to specific stages based on
+their bindings. They are being REPLACED by the Workflow Builder (see below). Low priority
+for scripting integration. Forces are not queryable/mutable via GraphQL in a meaningful way.
+
+### Workflow Builder (in progress, high change velocity)
+
+The Workflow Builder (`pagesWorkflow`) allows configuring automated behaviours:
+- Deployed: notifications, auto page creation, task assignments
+- Not yet deployed: conditional field/section workflows (show/hide sections based on
+  field values, computed risk ratings, gauge/select interdependencies)
+- Recently refactored (quick fixes via CI/CD for new customers)
+
+**Implication for scripting:** Workflow Builder operations are not part of the
+eco-helpers compat scope. However, scripts must be aware that workflow triggers
+(task creation, stage transitions) can fire as side effects of `updatePage`.
+
+### DSL location decision (confirmed 2026-06-07)
+
+The compat DSL (page accessors, `components`, `stages[name]`, `consolidate!`, etc.)
+sits in `ecoportal-api-graphql` as concerns included on page models. This is correct
+because these are upstream-dependency concerns of this gem.
+
+The eco-helpers `OozeBase` / `RegisterUpdate` inheritance chain will transparently
+use the GraphQL-backed models once the session backend is swapped. No script code changes.
+
+However: some DSL methods (`add_field`, `add_component`, stage-specific submit) may
+need to live in eco-helpers itself if they cannot be cleanly expressed at the gem level.
+
+---
+
+## Open Questions (Resolved 2026-06-07)
+
+1. ✓ Filter format: translated in `Compat::Registers` (date_filter lbound/ubound → gte/lte)
+2. ✓ Components naming: `components` aliased to `field_collection` via `DataFieldAccess`
+3. ✓ `get_new` shape: `buildFromTemplate` returns full page with field IDs via `CommonPageUnion`
+4. ✓ Stage access: `StageCollection` wrapper provides `[]`, `get_by_name`, `ordered`
+5. Script repo access: pending `.claude/settings.json` rules configuration
+
+## Remaining Gaps
+
+- `stage_id` in `pages.get` currently ignored — stage-specific view not filtered client-side
+- `stageId` in `updatePage` not yet passed through compat — needed for stage submit/close-out
+- `add_field` / `add_component` (dataFields.additions) not implemented
+- Stage-specific permissions may behave differently (silent omission vs error)