ecoportal-api-graphql 1.3.5 → 1.3.9

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

@@ -0,0 +1,266 @@
+# eco-helpers → GraphQL Migration Guide
+
+*Migrating eco-helpers scripts from `ecoportal-api-v2` to `ecoportal-api-graphql`.*
+
+---
+
+## TL;DR
+
+For most page scripts: **change one line** (the API initialiser). Everything else stays the same.
+
+```ruby
+# Before (APIv2)
+api = Ecoportal::API::V2.new(email: ENV['EMAIL'], pass: ENV['PASS'], org_id: ENV['ORG'])
+
+# After (GraphQL)
+api = Ecoportal::API::GraphQL.new(email: ENV['EMAIL'], pass: ENV['PASS'], org_id: ENV['ORG'])
+```
+
+`api.pages` and `api.registers` expose the same interface — the same method names,
+the same argument shapes, the same block and return-value patterns.
+
+---
+
+## What Changes
+
+### Initialiser
+
+| | APIv2 | GraphQL |
+|---|---|---|
+| Class | `Ecoportal::API::V2` | `Ecoportal::API::GraphQL` |
+| Gem | `ecoportal-api-v2` | `ecoportal-api-graphql` |
+| `email:` | ✓ | ✓ |
+| `pass:` | ✓ | ✓ |
+| `org_id:` | ✓ | ✓ |
+| `host:` | ✓ (default `live.ecoportal.com`) | ✓ (same default) |
+
+### Gem dependency in your script's Gemfile
+
+```ruby
+# Remove:
+gem 'ecoportal-api-v2'
+
+# Add:
+gem 'ecoportal-api-graphql'
+```
+
+---
+
+## What Stays the Same
+
+### `pages` interface
+
+| Method | APIv2 signature | GraphQL compat | Notes |
+|---|---|---|---|
+| `get(id)` | `pages.get(id)` | ✓ identical | |
+| `get(id, stage_id:)` | `pages.get(id, stage_id: sid)` | ✓ identical | Returns `StageView` |
+| `get_new(template_id)` | `pages.get_new(tid)` | ✓ identical | Returns built PageUnion |
+| `create(page, from:)` | `pages.create(page, from: tid)` | ✓ identical | Returns `PageReference` |
+| `update(page)` | `pages.update(page)` | ✓ identical | Returns `Response` |
+| `get_body(page)` | `pages.get_body(page)` | ✓ identical | Returns change hash |
+
+### Page model accessors
+
+| Accessor | Works? | Notes |
+|---|---|---|
+| `page.id` | ✓ | |
+| `page.name` | ✓ | |
+| `page.external_id` | ✓ | maps to `externalId` |
+| `page.template_id` | ✓ | maps to `sourceTemplateId` |
+| `page.stages?` | ✓ | |
+| `page.stages['Stage Name']` | ✓ | via `Compat::StageCollection` |
+| `page.stages.get_by_name(n)` | ✓ | |
+| `page.stages.ordered.map(&:id)` | ✓ | |
+| `page.current_stage_id` | ✓ | on PhasedPage only |
+| `page.components` | ✓ | returns `DataField::Collection` |
+| `page.components.get_by_name(l)` | ✓ | case-insensitive |
+| `page.components.get_by_type(t)` | ✓ | symbol or string |
+| `page.dirty?` | ✓ | |
+| `page.consolidate!` | ✓ | resets change tracking |
+| `page.validate` | ✓ (always nil) | server validates on mutation |
+| `stage.components` | ✓ | |
+| `stage.sections` | ✓ | |
+| `stage.active?` / `stage.started?` | ✓ | |
+
+### Page reference (after create)
+
+```ruby
+ref = api.pages.create(draft, from: template_id)
+ref.page_id         # ✓
+ref.active_stage_id # ✓
+ref.success?        # ✓
+```
+
+### `registers` interface
+
+| Method | APIv2 | GraphQL compat | Notes |
+|---|---|---|---|
+| `search(id, opts) { \|r\| }` | ✓ | ✓ | Cursor-paginated |
+| `result.id` in block | ✓ | ✓ | |
+| No-block → `.total` | ✓ | ✓ | via `SearchResults` |
+| `.total_before_filtering` | ✓ | ✓ | |
+
+---
+
+## What Requires Review
+
+### 1. Filter format in `registers.search`
+
+Scripts that pass v2-style filter hashes are **automatically translated** by
+`Compat::FilterTranslator`. You only need to review if your script passes filters
+in a non-standard or custom format.
+
+**Automatic translation (no action needed):**
+
+```ruby
+# v2 date_filter with lbound/ubound — automatically converted to gte/lte
+{ 'type' => 'date_filter', 'key' => 'updated_at', 'lbound' => '2025-01-01', 'ubound' => '2025-12-31' }
+# → { operation: 'date_filter', params: { key: 'updated_at', gte: '2025-01-01', lte: '2025-12-31' } }
+
+# tag_filter — passed through unchanged (same ES backend)
+{ 'type' => 'tag_filter', 'tags' => [...] }
+
+# register_filter — passed through unchanged
+{ 'type' => 'register_filter', 'params' => { 'ids' => [...] } }
+```
+
+**Requires review:** if your script builds filters with keys like `extact_filter`
+(typo), non-standard operation names, or custom filter shapes not listed above —
+those will pass through unchanged and may return empty results silently.
+See `search_filters.md` for the full list of valid operation names (all snake_case).
+
+**Quick search to run on your script repo:**
+
+```bash
+grep -rn "date_filter\|tag_filter\|filters.*type\|type.*filter" scripts/
+```
+
+### 2. `pages.update` — always fetch before update
+
+The GraphQL path requires `patchVer` for concurrency control.
+`Input::Page::Update.from_model` injects it automatically **if you fetched the page first**.
+
+```ruby
+# Correct — always fetch first
+page = api.pages.get(page_id)
+page.name = 'New Name'
+api.pages.update(page)
+
+# Incorrect — updating a page you constructed manually (no patchVer)
+page = MyManualPageObject.new(...)
+api.pages.update(page)  # ⚠ patchVer will be nil — server may reject
+```
+
+If your script fetches pages via `get` before updating, no change needed.
+If your script constructs page objects manually without fetching — review those paths.
+
+### 3. `get_new` — template ID must be the live template ID
+
+`pages.get_new(template_id)` calls `buildPageFromTemplate` on the GraphQL API.
+The `template_id` must be the live MongoDB ObjectId, same as in APIv2.
+
+The return value has the same structure as in APIv2 — `page.components`,
+`page.stages`, etc. Field IDs are server-assigned instance IDs, not template IDs.
+You must use these IDs when creating the page (the compat layer handles this
+automatically via `page.data_fields_updates`).
+
+---
+
+## Known Limitations
+
+### 1. Field types — read access only for some types
+
+The following field types are **readable** but cannot be written via `as_input`:
+
+| Type | Status | Notes |
+|---|---|---|
+| `Signature` | Read only | Captured via UI |
+| `Mailbox` | Read only | System-managed |
+| `ActionsList` | Read only | Manage via `api.action` builder |
+| `Law` | Read only | Legal snippets, not editable via script |
+| `AiSummary` | Read only | AI-generated |
+| `Table` | Read only | Complex structure |
+
+The following types **are writable** but require a file upload step first:
+
+| Type | Status | Notes |
+|---|---|---|
+| `File` | Writable* | Requires REST upload → fileContainerIds |
+| `ImageGallery` | Writable* | Same as File |
+
+\* File upload support is on the roadmap. For now, `file_container_ids=` will work
+if you already have `fileContainerIds` from a prior upload.
+
+### 2. `pages.search` — not implemented on `Compat::Pages`
+
+APIv2's `pages.search(...)` is not part of the compat layer.
+Use `api.registers.search(register_id, ...)` for register-scoped search,
+or use `Model::Organization.pages(searchConf: conf)` for org-wide search.
+
+### 3. Performance — org search is ~3s/page
+
+The GraphQL `pages.get` (and `pages.get_new`) fetches full DB-rendered page data.
+This is ~3s per page for large pages, compared to ~200ms in APIv2 for the same data.
+
+Mitigation: batch fetches, or use `api.registers.search` (ES-backed, fast) to
+get page IDs first, then fetch only the pages you actually need to update.
+
+### 4. `simulate?` / dry-run mode — no change
+
+The compat layer honours `get_body` / `dirty?` / `consolidate!` as before.
+Dry-run logic that checks `dirty?` and skips `update` if not dirty continues to work.
+
+---
+
+## Quick Verification Checklist
+
+Before switching a script to the GraphQL gem:
+
+- [ ] Grep for `API::V2.new` — replace with `API::GraphQL.new`
+- [ ] Grep for custom filter formats — verify they translate correctly
+- [ ] Grep for manual page construction (without `pages.get`) — check patchVer supply
+- [ ] Grep for `pages.search` — replace with `registers.search` or org search
+- [ ] Run the script in `simulate` mode against a staging org
+
+---
+
+## Example: minimal diff for a typical update script
+
+```ruby
+# Before
+require 'ecoportal/api-v2'
+api = Ecoportal::API::V2.new(email: ENV['EMAIL'], pass: ENV['PASS'], org_id: ENV['ORG'])
+
+api.registers.search('REG_ID', filters: [date_range_filter('updated_at', from: '2025-01-01')]) do |result|
+  page = api.pages.get(result.id)
+  next unless page.dirty?
+  page.components.get_by_name('Status')&.select_option('Active')
+  api.pages.update(page)
+  page.consolidate!
+end
+
+# After (change highlighted)
+require 'ecoportal/api-graphql'                                               # ← changed gem
+api = Ecoportal::API::GraphQL.new(email: ENV['EMAIL'], pass: ENV['PASS'], org_id: ENV['ORG'])  # ← changed class
+
+api.registers.search('REG_ID', filters: [date_range_filter('updated_at', from: '2025-01-01')]) do |result|
+  page = api.pages.get(result.id)
+  next unless page.dirty?
+  page.components.get_by_name('Status')&.select_option('Active')
+  api.pages.update(page)
+  page.consolidate!
+end
+# Everything else is identical.
+```
+
+---
+
+## Rollback
+
+If a script needs to revert to APIv2:
+
+1. Change the require back to `ecoportal/api-v2`
+2. Change the initialiser class back to `Ecoportal::API::V2`
+3. No other code changes needed
+
+The compat layer was designed so the rollback is always a one-line change.

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

@@ -0,0 +1,86 @@
+# TODOs — eco-helpers GraphQL Compat Layer
+
+> URGENT — APIv2 retires in ~3 weeks.
+> Natural order: 1 → 2 → 3 → 4 → 5 (resolve open questions before implementing)
+
+---
+
+## Step 1 — Resolve open questions (Done 2026-06-07)
+
+- [x] **1.1** Filter format confirmed: scripts use `tags_filter` and `date_range_filter`
+  helpers producing `type: "date_filter"` with `lbound`/`ubound` keys.
+  Translation: date_filter lbound→gte, ubound→lte. Other types pass through.
+
+- [x] **1.2** `registers.search` block result: yields individual PreviewPage objects (.id etc).
+  No-block form returns an object with `.total` and `.total_before_filtering`.
+  Implemented: `Compat::SearchResults` wraps connection with both properties.
+
+- [ ] **1.3** `pages.get_new` draft shape — still waiting on end-script repo access.
+  For now: `buildPageFromTemplate` returns PageUnion with field IDs and stagesIndex.
+
+- [x] **1.4** `pages.create` reference: only `.page_id` and `.active_stage_id` used.
+  `Compat::PageReference` implements both correctly.
+
+- [x] **1.5** Stage access: `stages[id_name]` AND `stages.get_by_name(id_name)` AND
+  `stages.ordered.map(&:id)`. Implemented via `Compat::StageCollection` wrapper
+  included via `Model::Page::Phased#stages` override.
+
+---
+
+## Step 2 — Scaffold `Compat::Pages` and `Compat::Registers` (Done 2026-06-07)
+
+- [x] **2.1** `lib/ecoportal/api/graphql/compat/pages.rb`: `get`, `get_new`, `create`, `update`, `get_body`.
+  *Done 2026-06-07*
+
+- [x] **2.2** `lib/ecoportal/api/graphql/compat/registers.rb`: `search` with cursor pagination
+  and v2 filter translation (date_filter lbound/ubound → gte/lte).
+  *Done 2026-06-07*
+
+- [x] **2.3** Wired from top-level `Ecoportal::API::GraphQL`: `pages` → `Compat::Pages`, `registers` → `Compat::Registers`.
+  *Done 2026-06-07*
+
+---
+
+## Step 3 — Page model compatibility wrapper (Done 2026-06-07)
+
+- [x] **3.1** `Concerns::PageCompat` included in `Interface::BasePage`:
+  `external_id`, `template_id`, `components`, `stages?`, `consolidate!`, `validate`, `dirty?`.
+  `current_stage_id` defined on `Model::Page::Phased` (reads in-progress stage from doc).
+  19 specs: `spec/ecoportal/api/graphql/concerns/page_compat_spec.rb`.
+  *Done 2026-06-07*
+
+- [x] **3.2** `Compat::StageCollection`: `stages[id_or_name]`, `get_by_name`, `ordered`.
+  Wrapped via `Model::Page::Phased#stages` override.
+  Specs: `spec/ecoportal/api/graphql/compat/stage_collection_spec.rb`.
+  *Done 2026-06-07*
+
+- [x] **3.3** `Compat::PageReference`: `.page_id` and `.active_stage_id` (via `current_stage_id`).
+  Fixed: was using `currentStage` (undefined accessor); now uses `current_stage_id`.
+  Specs: `spec/ecoportal/api/graphql/compat/page_reference_spec.rb`.
+  *Done 2026-06-07*
+
+---
+
+## Step 4 — Search/filter translation
+
+- [x] **4.1** `Compat::FilterTranslator.to_graphql(v2_filter)` — translates v2 filter hashes
+  to `SearchConf` objects. Handles `date_filter` (lbound→gte, ubound→lte), `tag_filter`,
+  `exact_filter`, `register_filter`; extracted from `Compat::Registers`.
+  *Done 2026-06-07 — 12 specs in `spec/ecoportal/api/graphql/compat/filter_translator_spec.rb`*
+
+- [x] **4.2** `Logic::BaseQuery#normalize_variables` auto-calls `.to_h` on value objects
+  (e.g. `SearchConf`) before passing as GraphQL variables — callers no longer need explicit `.to_h`.
+  *Done 2026-06-07 (commit cc72902)*
+
+---
+
+## Step 5 — Integration test + migration guide
+
+- [ ] **5.1** Run a real end-script against the compat layer (requires end-script repo access).
+  User will provide once `.claude/settings.json` rules are set.
+
+- [x] **5.2** `.ai-assistance/projects/eco-helpers-compat/MIGRATION_GUIDE.md` written.
+  Covers: one-line initialiser change, API compatibility table, filter review checklist,
+  patchVer requirement, known limitations (read-only field types, no pages.search,
+  ~3s/page performance), example diff, rollback instructions.
+  *Done 2026-06-08*

data/.ai-assistance/projects/ecoportal-api-v2-doublemodel-review/INTENT.md

@@ -0,0 +1,101 @@
+# Project: DoubleModel Review & Stabilisation (`ecoportal-api-v2`)
+
+**Created:** 2026-06-05
+**Status:** idea — not started
+**Primary repo:** `ecoportal-api-v2`
+**Affects:** `ecoportal-api-graphql` (consumers of `as_update` / `as_input` cascade)
+**Blocks:** `dynamic-model-generation` project
+
+---
+
+## Goal
+
+Review and stabilise the `DoubleModel` implementation in `ecoportal-api-v2`, with particular
+focus on:
+
+1. The `doc` / `original_doc` lookup chain through nested and Array-indexed models.
+2. The `root!` / `read_only!` memoisation flags and their interaction with the cascaded diff.
+3. Ensuring that memoised `@doc` cannot silently go out of sync with a parent's diff.
+
+The outcome must be a `DoubleModel` contract that is reliable enough to underpin
+`ecoportal-api-graphql`'s `as_update` / `as_input` pipeline and, eventually, auto-generated
+model classes.
+
+---
+
+## Background
+
+The `DoubleModel` stores the canonical document (`@doc`) only at the root object. All
+nested descendant objects resolve their own `doc` by walking up the ownership chain and
+extracting their slice of the root `@doc` by key path.
+
+This design is correct for Hash-keyed paths (keys are deterministic). It breaks down for
+Array-indexed paths (`CollectionModel` and similar), because Array indexes are positional —
+if order changes, a nested object's key path no longer resolves to the right element.
+
+The current workaround is to look up the element by its own key from the parent at access
+time, rather than by stored index. This lookup is performed every time `doc` or
+`original_doc` is called on a nested object inside an Array, making it operationally costly:
+
+- The lookup re-scans the parent array on each call.
+- Objects under a `CollectionModel` may be instantiated multiple times during a single render
+  as a side effect of these repeated resolutions.
+
+To mitigate this, `root!` and `read_only!` class-level flags were introduced. They allow
+a model class to memoise `@doc` locally (breaking the chain) when it is known to be stable.
+These flags are used extensively in `ecoportal-api-graphql` model and payload classes.
+
+### Known risk
+
+`root!` also signals to the cascaded diff (`DiffService`) that the object should be
+excluded from the parent's diff. This is correct for read-only lookup objects (e.g. a
+referenced Location node). But if `root!` is applied at a level where the object *is*
+expected to contribute changes to the parent diff, the memoised `@doc` will silently
+go out of sync — changes to that sub-model will not surface in `as_update`. This is
+a subtle correctness risk that needs to be audited across all uses of `root!` and
+`read_only!` in `ecoportal-api-graphql`.
+
+---
+
+## Scope
+
+- Audit all uses of `root!` and `read_only!` in `ecoportal-api-graphql` model and payload
+  classes: confirm each is correctly applied (genuinely read-only / excluded from diff).
+- Review the Array-indexed lookup in `CollectionModel` (and related): document the current
+  behaviour, identify cases where it causes multiple object instantiation.
+- Propose and implement a more efficient resolution strategy for Array-indexed nested models
+  that does not require rescanning on every `doc` / `original_doc` call.
+- Ensure `patch_ver` propagation through the chain is correct after any changes.
+- Confirm that the `initial_doc` / `original_doc` / `doc` three-state contract is
+  preserved correctly after any refactor.
+
+---
+
+## Spec-first requirement
+
+Specs related to any modification **must be written before the change is applied** to
+`ecoportal-api-v2`, to lock in current behaviour and guard backwards compatibility.
+Specs must also be maintained and extended after the change to prevent future regressions.
+
+This applies both to the `ecoportal-api-v2` spec suite and to any `ecoportal-api-graphql`
+specs that exercise the cascaded diff path.
+
+---
+
+## Open Questions
+
+- Is the Array-indexed lookup fixable with a simple cache keyed by object identity
+  (`object_id`) that is invalidated on `doc=` / `reset!` calls?
+- Are there cases in `ecoportal-api-graphql` where `root!` is applied incorrectly
+  (object should contribute to diff but doesn't)?
+- What is the right `read_only!` vs `root!` semantic split? (`read_only!` = never
+  accept changes; `root!` = store doc locally + exclude from parent diff — are these
+  always the same thing, or should they be separable?)
+
+---
+
+## Notes
+
+This project is primarily work in `ecoportal-api-v2`, but the review must happen with
+`ecoportal-api-graphql` open alongside it, since the usage patterns there drive what
+needs to be fixed.

data/.ai-assistance/projects/graphql-agent/GAP_ANALYSIS.md

@@ -0,0 +1,177 @@
+# GraphQL Agent Corpus — Gap Analysis
+
+*Analysed 2026-06-07 from staging corpus at `C:\claude\Projects\Claude AWS Platform\tmp\corpus\staging\success\graphql\`*
+*18 staging documents reviewed.*
+
+---
+
+## Critical — Breaks Agent Reliability
+
+| File | Issue | Fix |
+|------|-------|-----|
+| `2262499334_search-by-external-id.md` | Contains placeholders (`"graphqlwide760"`, `"jsonwide760"`) instead of actual query/variables | Replace with real contractor search examples |
+| `2262892608_registers-searches-and-templates.md` | Entirely empty after header — no content | Populate register structure, preset views, search config |
+| Agent instructions (absent) | No guidance that GraphQL queries are client-defined — agent will expect structural uniformity | Add "GraphQL is a Language" note (see below) |
+
+---
+
+## High — Agent Will Hallucinate Without Guidance
+
+### Error handling — completely missing
+No error taxonomy. No error codes. No recovery patterns. The agent will invent error names
+and suggest incorrect recovery steps.
+- **Add:** 20–30 common error codes with cause and recovery (e.g. `patchVer` conflict,
+  invalid field ID, permission denied, stale cursor)
+
+### State machines — completely missing
+No documented states for Page, Stage, Action, Task. No valid transitions. Agent will
+suggest invalid state changes.
+- **Add:** State diagrams or transition tables for each entity
+
+### Authorization — completely missing
+`canXXX` fields exist on every Page, Stage, Action. What they mean is never explained.
+- **Add:** `canXXX` field guide — when they return false, what the caller should do
+
+### Filter syntax — incomplete and inaccurate
+The search filter docs show `fieldName` in examples but production queries use `key`.
+Filter operation names are snake_case (silent failure if CamelCase is used — no error,
+no results). `filters` should always be an Array.
+- **Add:** Complete filter operation reference with snake_case requirement explicit.
+  See `.ai-assistance/code/search_filters.md` in `ecoportal-api-graphql`.
+
+### Field ID lifecycle — missing
+Docs warn that field IDs change between template and instance, but give no algorithm for
+resolving them (when to `buildFromTemplate` first, when to look up by type+label, etc.)
+- **Add:** "Field ID Resolution" section — the two-step workflow and when each applies
+
+### `updateMode` on actions — undocumented
+The UpdateAction mutation accepts `updateMode` but valid values are not documented.
+Agent will omit or guess (single / series / future / all).
+- **Add:** `updateMode` enum values with examples
+
+---
+
+## Medium — Gaps That Reduce Usefulness
+
+### Covered but incomplete
+
+**Pages technical guide (`2235662347`):**
+- Missing: how `showHiddenData` interacts with field visibility
+- Missing: page state vs. stage state distinction
+- Missing: what `templatesOnly` does (returns templates as pages, not instances)
+- Missing: partial update semantics (sparse fields vs. full replacement)
+
+**Authentication (`1959788614`):**
+- `scope` shown as `[]` with no explanation
+- Token expiry and refresh failure handling missing
+- Security best practices for token storage missing
+
+**Searching pages (`1933639695`):**
+- Only 3 filter examples — no matrix of all filterable fields
+- No field-value filters (search by a specific data field value)
+- `mould_counter` appears in example with no explanation (deprecated; use `uid`)
+
+**Load actions (`1933901853`):**
+- Uses both `edges { node { ... } }` and `nodes` inconsistently
+- `Search` input type not documented alongside its usage
+
+**Create/Update page mutations:**
+- No guidance on transaction semantics (is a partial dataFields update atomic?)
+- Missing: what happens if one field update fails — does the mutation continue or abort?
+
+### Not covered at all
+
+- Contractor entity lifecycle (create / approve / activate / archive)
+- Archive and unarchive page flows (compound mutation pattern)
+- File upload mechanics (separate from attach)
+- Bulk/batch operations
+- Visitor management integration
+- Page forces / risk management
+- Task workflow and status transitions
+- AI Summary field operations
+- Mailbox field operations
+- Cross-reference field deep guidance
+- People field — `cachedPeople` vs. `livePeople` distinction
+- Webhook / subscription patterns
+- Rate limiting and throttling
+- Cursor invalidation policy (how long cursors remain valid)
+- `deindex` and field visibility flags semantics
+
+---
+
+## Accuracy Concerns
+
+| File | Issue |
+|------|-------|
+| `1931575325_updatepage.md` | Example variables may reference `templateId` where `id` (page ID) is expected |
+| `1928855618_createaction.md` | Response structure example (`item: { ... }`) may not match actual wrapper |
+| `2235662347_graphql-pages-technical-guide.md` | Refers to `pageUnionCommonFragment` but fragment definition is in a separate doc with no cross-link |
+| Multiple | Date formats mixed (ISO8601 with Z vs. with +offset) — no guidance on when each is correct |
+| Multiple | Broken Confluence external links (opaque IDs, unresolvable outside Confluence) |
+
+---
+
+## Structural Issues
+
+1. **No agent preamble.** There is no document that tells the agent the most important
+   invariants: GraphQL variability, silent filter failures, two-step field ID resolution,
+   compound mutation pattern. These must be added as explicit agent instructions, not
+   buried in examples.
+
+2. **No cross-reference index.** `CommonPageUnion` is referenced in 6+ documents but
+   defined in only one. An agent cannot reliably find what it needs.
+
+3. **No versioning or timestamps.** The agent cannot tell if a doc reflects the current
+   schema or an old version. Schema changes may invalidate examples silently.
+
+4. **Inconsistent example depth.** Some mutations show full request + response; others
+   only show the query. Agent will fill in gaps incorrectly.
+
+5. **Fragment defined but not explained.** `CommonPageUnion` shows the full GraphQL but
+   nowhere explains what `$content`, `$only_content`, `$fields` actually control in
+   human terms (with examples of before/after).
+
+---
+
+## Recommended Agent Preamble (add to system prompt or corpus index)
+
+```
+You are assisting with the EcoPortal GraphQL API. Key invariants:
+
+1. GraphQL queries are client-defined. The same resource can be queried many ways.
+   Variability in examples is intentional. Multiple mutations in one request (executed
+   in order) is valid and used for stateless middleware clients.
+
+2. Filter operations are snake_case strings. CamelCase silently returns no results.
+   Always use: exact_filter, date_filter, and_filter, or_filter, register_filter.
+   The `filters` value should always be an Array.
+
+3. Page creation requires a 2-step sequence:
+   (a) buildFromTemplate → get field IDs from the built draft
+   (b) createFromTemplate → use those field IDs in dataFields.updates
+
+4. Page update requires:
+   (a) Fetch current page → get patchVer + current field IDs
+   (b) updatePage → include patchVer (required for concurrency control)
+
+5. The CommonPageUnion fragment ($fields/$content/$only_content variables) is the
+   standard pattern for fetching full page data. Use it for all page read operations.
+
+6. Register search (previewPages) is Elasticsearch — fast but no field IDs.
+   Org search (pages) is DB — slow (~3s/page) but complete data including field IDs.
+```
+
+---
+
+## Recommended Additions Priority
+
+1. Error taxonomy (codes, causes, recovery)
+2. State machines (Page, Stage, Action, Task)
+3. Field type matrix (all 20 types, validation, modifiers)
+4. Full contractor management (currently broken/empty)
+5. Authorization guide (`canXXX` meanings)
+6. Archive/unarchive patterns
+7. File upload guide
+8. Complete filter fieldName reference
+9. `updateMode` enum for actions
+10. Cursor invalidation policy