ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/code/ecoPortal_architecture/12_ai_documentation_sources_gaps.md

@@ -0,0 +1,236 @@
+# AI Documentation Sources, Gaps, and Improvement Opportunities
+
+---
+
+## Knowledge Sources for AI Agents
+
+### 1. GraphQL Schema (Live — Auto-Generated)
+
+**URL:** `https://live.ecoportal.com/api-docs/graphql` (requires login)
+**Corpus location:** `C:\claude\Projects\Claude AWS Platform\tmp\corpus\staging\success\graphql\schema_graphql-schema.md`
+**Type:** Auto-generated from GraphQL SDL on each deployment
+**Quality:** Authoritative — always reflects the current API
+**Limitations:** No explanations, no examples, field descriptions sparse
+
+### 2. Confluence APIDOCS Space
+
+**URL:** `https://ecoportal-projects.atlassian.net/wiki/spaces/APIDOCS`
+**Corpus location:** `C:\claude\Projects\Claude AWS Platform\tmp\corpus\staging\success\graphql\`
+**Type:** Team-maintained documentation, customer-facing guidance
+
+**Key pages:**
+- `2254077960_graphql-api-docs.md` — GraphQL API introduction
+- `2235662347_graphql-pages-technical-guide.md` — Pages technical guide
+- `2262892608_registers-searches-and-templates.md` — **EMPTY — critical gap**
+- `2262696008_pageunion-common-fragment-definition.md` — CommonPageUnion reference
+- `1933639695_searching-pages.md` — Search/filter guide
+- `1931542534_createpagefromtemplate.md` — Create workflow
+- `1931575325_updatepage.md` — Update workflow
+- `1959788614_authentication-flow.md` — Auth guide
+- `2261450758_schema-introspection.md` — Schema introspection
+- `2261614596_fetch-by-system-id.md` — Fetch by system ID
+- `2262499334_search-by-external-id.md` — **BROKEN — placeholder content**
+- `2289958954_list-all-templates.md`, `2290122761_list-register-templates.md`, `2290089995_list-registers.md`
+- `1928855618_createaction.md`, `1928921220_updateaction.md`, `1933901853_loadactions.md`
+
+### 3. Confluence Engineering Projects (High Level Requirements)
+
+**URL:** Engineering Confluence space (separate from APIDOCS)
+**Status:** EXISTS but not yet in the corpus
+**Contains:** HLRs for new features, architectural decisions, roadmap items
+**Gap:** Not yet available to AI agents. Would provide: planned features, architectural
+constraints, why certain decisions were made, what's coming next.
+
+**Recommended action:** Add Engineering HLR pages to the corpus. Particularly valuable:
+- Workflow Builder HLR and design docs
+- Field ID / System ID project spec
+- APIv3 page render spec
+- Template editing via GraphQL (when Engineering unblocks it)
+
+### 4. Confluence Knowledge Base (Customer-Facing Articles)
+
+**URL:** Separate Confluence space — customer-facing how-to articles
+**Status:** NOT YET in the corpus
+**Contains:** End-user instructions for using ecoPortal features (not API)
+**Value for AI:** Understanding what customers call things, common support tickets,
+feature explanations at a non-technical level
+
+**Gap:** An AI agent helping customers reference both KB articles and API docs would
+be much more effective.
+
+### 5. Production Insomnia Queries (Verified Examples)
+
+**Location:** `C:\claude\Projects\Claude AWS Platform\tmp\corpus\success\graphql\examples\Insomnia_2026-06-07.yaml`
+**Corpus extraction:** `C:\ruby_scripts\git\ecoportal-api-graphql\.ai-assistance\code\search_filters.md`
+**Contains:** 17+ production queries verified against live.ecoportal.com
+
+Key confirmed patterns:
+- Org search with register + date filters
+- Register search (`previewPages`)
+- Find by externalId (exact_filter)
+- OR filter for multiple externalIds
+- buildFromTemplate + createFromTemplate
+- updatePage with field values
+- archivePage compound mutation
+
+### 6. Front-End GraphQL Queries (React components)
+
+**Location:** `C:\docker\ecoPortal_master\` — `.graphql` files distributed throughout
+the React codebase
+**Status:** Not yet systematically catalogued
+**Contains:** Every query/mutation used in the React UI — ground truth for what's
+actually supported and used
+
+**Recommended action:** Run a grep for `*.graphql` files across the ecoPortal codebase,
+extract all query/mutation names, and add them to the corpus. The `graphql-schema-analysis`
+skill has guidance for this.
+
+### 7. eco-helpers Source Code
+
+**Location:** `C:\ruby_scripts\git\eco-helpers`
+**Contains:** All integration patterns used by the Integrations Team
+**Audited:** 2026-06-07 (see eco-helpers-compat INTENT.md)
+**Key files:** `ooze_base_case.rb`, `register_export_case.rb`, `register_update_case.rb`,
+`helpers/filters.rb`
+
+### 8. ecoportal-api-v2 Source Code
+
+**Location:** `C:\ruby_scripts\git\ecoportal-api-v2`
+**Contains:** REST API client, data models, diff/patch logic
+**Key:** `StringDigest` for Field ID formula, `HashDiffPatch` for diff algorithm
+
+### 9. APIv3 Page Render (Custom Exports)
+
+**Status:** In development. Not yet available for scripting.
+**Purpose:** Custom page rendering for PDF exports and other format-specific outputs.
+**Gap:** Not yet documented in any corpus. When deployed, this will be important for
+customers who need custom report generation.
+
+---
+
+## Critical Gaps in Current Documentation
+
+### Gaps That Break AI Agent Reliability
+
+| Gap | Impact | Recommended Fix |
+|-----|--------|-----------------|
+| `2262892608` (registers/search/templates) is EMPTY | Agent has NO guidance on register search | Write comprehensive page: register structure, previewPages, search, preset views |
+| `2262499334` (search by externalId) has placeholder content | Agent will make up contractor search syntax | Replace with real query + variables |
+| Error taxonomy completely missing | Agent invents error codes/names | Document 20+ error codes: patchVer conflict, invalid field ID, permission denied, stale cursor, etc. |
+| State machines not documented | Agent suggests invalid state changes | Add state diagrams: Page (active→archived→active), Stage (pending→inprogress→complete), Task |
+| `updateMode` on actions undocumented | Agent omits or guesses this param | Document enum: single/series/future/all |
+| Authorization (`canXXX` fields) unexplained | Agent doesn't know what to do on `canUpdate: false` | Document each `canXXX` field's meaning and correct response |
+| Filter `key` vs `fieldName` inconsistency | Agent uses wrong key name | Document that sorters use `key:`, filters use `key:` in params |
+
+### Gaps That Reduce Usefulness
+
+| Gap | Impact |
+|-----|--------|
+| No field type reference (all 20 types) | Agent doesn't know what fields are available or how to update them |
+| Pagination edge cases undocumented | Agent doesn't know cursor invalidation policy |
+| CommonPageUnion variables not explained in human terms | Agent can't tell customer what `$content`, `$fields`, `$only_content` do |
+| Archive/unarchive compound pattern not in corpus | Agent misses the externalId blanking step |
+| `previewPages` vs `pages` distinction not documented | Agent uses wrong query for register search |
+| No contractor CRUD guide | Agent makes up create/update/delete syntax |
+| File upload mechanics missing | Agent can't guide file/image field updates |
+
+---
+
+## Recommended Agent Instructions (System Prompt Additions)
+
+An AI agent deployed to assist ecoPortal customers or integrations should include:
+
+```
+Key invariants for the ecoPortal GraphQL API:
+
+1. GraphQL queries are client-defined. Variability in examples is intentional.
+   Multiple mutations in one request 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. Sorters use the key `key:` (not `fieldName:`) pointing to the Elasticsearch index
+   key (field ref), not the MongoDB field id.
+
+4. Page creation requires a 2-step sequence:
+   (a) buildFromTemplate → get server-assigned field IDs from the built draft
+   (b) createFromTemplate → use those field IDs in dataFields.updates
+
+5. Page update requires:
+   (a) Fetch current page → get patchVer + current field IDs and values
+   (b) updatePage → include patchVer (required for concurrency control)
+   Stale patchVer = mutation rejection.
+
+6. The CommonPageUnion fragment ($fields/$content/$only_content variables) is the
+   standard pattern for fetching full page data.
+
+7. Register search (`previewPages`) is Elasticsearch — fast but no field IDs.
+   Org search (`pages`) is DB — slow (~3s/page) but complete data including field IDs.
+   For pre-mutation fetch, always use org search.
+
+8. Stage-specific operations (submit, sign-off, people field permissions) require
+   `stageId` in UpdatePageInput. Without it, server-side workflow may not trigger.
+
+9. Engineering does NOT want templates updated via GraphQL. Read-only template access
+   is fine. Template mutations exist but are not approved for scripting.
+
+10. patchVer is mandatory on all updatePage calls. Scripts MUST fetch the page first.
+```
+
+---
+
+## Improvement Opportunities for AI-Assisted Integration
+
+### Near-Term (Within Corpus)
+
+1. **Fill the two broken/empty docs** (2262892608, 2262499334)
+2. **Write error taxonomy** — agents desperately need this
+3. **Write state machine docs** — Page, Stage, Action, Task states
+4. **Document all 20 field types** — types, what values they accept, DataFieldInput keys
+5. **Write CommonPageUnion explanation** — what `$content/$fields/$only_content` do with examples
+
+### Medium-Term (New Sources)
+
+6. **Add Engineering HLRs** to corpus — Workflow Builder, Field ID project, APIv3
+7. **Add customer-facing KB articles** — align technical + customer vocabulary
+8. **Catalogue front-end `.graphql` files** — ground truth for what's used in production
+9. **Add Insomnia collection systematically** — more coverage of edge cases
+
+### Long-Term (AI-Driven Features)
+
+10. **AI-assisted filter builder** — customer describes "find all active pages in region X
+    updated in the last 7 days" → AI generates `SearchConf` objects
+    (Foundation exists in `search-filter-builder/` project, see `TODO.md` Step 5)
+
+11. **AI-assisted query builder** — customer describes what they need, AI generates
+    the full GraphQL query + fragment combination
+
+12. **Automatic schema-corpus sync** — on each deployment, re-generate the corpus
+    from live schema introspection and flag what changed
+
+---
+
+## Things to Remind Oscar (Noted from Session 2026-06-07)
+
+- **Confluence Engineering Projects:** Get HLR pages added to corpus. Key projects:
+  Workflow Builder, Field ID / System ID, APIv3 page render, template editing unblock.
+
+- **Confluence Knowledge Base:** Customer-facing how-to articles — add to corpus to
+  bridge technical ↔ customer language gap.
+
+- **APIv3 page render:** New endpoint for custom exports. Not yet documented or stable.
+  Add to corpus when deployed.
+
+- **Front-end `.graphql` files:** Run a systematic sweep of `C:\docker\ecoPortal_master\`
+  for `.graphql` files. Add to corpus. These are the ground-truth queries the React UI uses.
+
+- **Genome signature:** Will come back to this. Currently broken on many instances.
+  Potentially the basis for the Field ID project. `Migrator` service in Rails (abandoned).
+
+- **Filter builder DSL:** Operator-based `Search[:field].eq('X') & Search.in_register('R')`
+  is the planned API. AI generation hook is step 5 in `search-filter-builder/TODO.md`.
+
+- **Comprehensive Confluence review:** The gap analysis (`graphql-agent/GAP_ANALYSIS.md`)
+  has the full list of 10+ items to fix before the GraphQL agent can be deployed to customers.
+  Two docs are critically broken (empty/placeholder). Fix these first.

data/.ai-assistance/code/ecoPortal_architecture/13_ai_infrastructure.md

@@ -0,0 +1,183 @@
+# 13 — AI Infrastructure
+
+*Extracted from backend source analysis of `C:\docker\ecoPortal_master` (2026-06-08).*
+*This is **customer-facing** infrastructure — not to be reused for internal tooling.*
+
+---
+
+## Overview
+
+EcoPortal's AI layer is built on AWS Bedrock (primary LLM and embeddings) + OpenSearch KNN
+(vector search) + AWS Bedrock AgentCore (natural language → filters). GCP Vertex AI provides
+a fallback for image analysis. All AI features are organisation-scoped and gated by feature flags.
+
+---
+
+## LLM Models (AWS Bedrock)
+
+| Model ID | Region | Use case |
+|---|---|---|
+| `anthropic.claude-3-5-sonnet-20241022-v2:0` | `ap-southeast-2` | AiSummary generation, Image OCR/metadata, SmartFill |
+| `anthropic.claude-3-sonnet-20240229-v1:0` | inferred | Legacy AiSummary |
+| `meta.llama3-3-70b-instruct-v1:0` | `us-east-2` | Alternative LLM |
+| `amazon.nova-micro-v1:0` | `us-east-1` | Lightweight inference (980 req/min rate limit) |
+
+**Guardrails (prompt injection protection):**
+- `us-east-2`: guardrail ID `7gsue70cel0j` v1 (`prompt_attack_only`)
+- `ap-southeast-2`: guardrail ID `5mg9t3aqm3ic` v1 (`prompt_attack_only`)
+
+Rate limiting: Redis-backed sorted sets. Claude 3: 90 req/min; Nova Micro: 980 req/min.
+
+---
+
+## Embedding Models (AWS Bedrock Cohere)
+
+| Model ID | Env var | Dimensions | Region | Use case |
+|---|---|---|---|---|
+| `cohere.embed-multilingual-v3` | `COHERE_EMBED_V3_MODEL_ID` | 1024 | `ap-southeast-2` | Universal embeddings |
+| `us.cohere.embed-v4:0` | `COHERE_EMBED_V4_MODEL_ID` | 1024 (default) | `us-east-1` | High-perf embeddings |
+
+Max batch: 96 texts/call. Used for: page text field vectors, template descriptions, semantic search.
+
+---
+
+## AI-Powered Features
+
+### 1. AiSummary Field (`NewEp::Pages::DataFields::AiSummary`)
+
+AI-generated text summary field on pages. Template-configured.
+
+**Gem type:** `Base::Page::DataField::AiSummary` (read-only in DataFieldInput)
+**Dedicated mutations:** `generateAiSummary`, `submitAiSummaryFeedback`
+
+Key fields:
+- `instructions` — custom prompt addition set on the template field (**reviewable by team**)
+- `trigger` — `submitted` | `approved` (when generation fires)
+- `triggerStageIds` — stages that trigger (empty = all)
+- `textFormat` — `simple_text` | `bullet_points` | `numbered_list` | `headings`
+- `aiSummary` — the generated text
+- `alreadyRated` — whether the user has given feedback
+
+Versioning: `NewEp::Pages::AiSummaryVersion` tracks prompt, token counts, status, ratings.
+
+### 2. SmartFill Field (`NewEp::Pages::DataFields::SmartFill`)
+
+AI-auto-populated data fields using template-defined prompts. Supports plain text, date,
+select, rich text, mailbox, actions list field types.
+
+**Gem type:** `Base::Page::DataField::SmartFill` (read-only in DataFieldInput)
+**Dedicated mutations:** `generateSmartFill`, `submitSmartFillFeedback`
+
+Key fields:
+- `instructions` — the AI prompt for this field (**reviewable by team**)
+- `trigger_type` — `manual` | `snapshot` | `live`
+- `status` — `pending` | `generating` | `success` | `failed`
+- `edit_enabled` — whether users can override the AI-generated value
+- `generated_at` — timestamp
+
+### 3. Template AI Description
+
+Templates can have an auto-generated AI description used for semantic search.
+
+- Field: `ai_description` on `Enzyme::Mould`
+- Embeddings: `ai_description_embeddings` (Cohere v4, 1024 dims)
+- Job: `NewEp::Pages::Templates::AiDescriptionEmbedJob`
+- Query log: `NewEp::Pages::Templates::AiQueryLog`
+
+### 4. Semantic Search (OpenSearch KNN)
+
+Vector-based page search on `text_field_vectors.embedding` (nested field).
+
+- Index: Enzyme::Ooze + NewEp::Page
+- Vector path: `text_field_vectors.embedding`
+- Dimensions: 1024 (Cohere v4)
+- Min score: 0.65, KNN k: 10
+- Gated by: `organization.pages_semantic_search_enabled?`
+- Service: `NewEp::Es::SemanticQs::Page`
+
+### 5. Smart Search — Natural Language → Filters
+
+Converts a user's natural-language query into structured register search filters.
+
+- Service: `NewEp::GeneratedFilters::PageFilters::Generate`
+- Backend: `AwsBedrock::AgentCore::InvokeAgentRuntime`
+- Agent ARN: `arn:aws:bedrock-agentcore:ap-southeast-2:697073004009:runtime/prod_master_page_filters_agent-P10hX5HEIG`
+- Auth: JWT tokens via `NewEp::AgentSessions::TokenService` (scope: `page_filters_agent`)
+- Dev endpoint: `http://host.docker.internal:8080/invocations` or `SMART_QUERY_AGENT_URL`
+
+This is the backend for the "build register filters on the go" customer feature.
+
+### 6. Image OCR / Metadata Extraction
+
+Extracts text, captions, descriptions, and sensitivity flags from uploaded images.
+
+**Primary:** AWS Bedrock Claude 3.5 Sonnet (`ap-southeast-2`)
+**Fallback:** GCP Vertex AI Gemini (`gemini-3.1-flash-lite`)
+
+Supported formats: PNG, JPG, JPEG, GIF, WebP, BMP
+Max size: 4.71 MB (Bedrock), 19 MB (GCP); Max resolution: 1568px / 1.15 MP
+
+Output: `description`, `caption`, `extracted_text`, `sensitive_content`, `overall_confidence`
+
+### 7. Inline Text AI Tools
+
+General text manipulation operations accessible from any text-capable field.
+
+**Model:** GCP Vertex AI Gemini (`gemini-3.1-flash-lite`)
+**Mutations:** `aiToolsSummarize`, `aiToolsFixSpellingGrammar`, `aiToolsMakeFormal`,
+`aiToolsRephrase`, `aiToolsTranslate`
+
+Context injection: field label, description, max char limit (via `AiTools::ContextInput`).
+Translation backend: Google Cloud Translate.
+
+---
+
+## Video Transcription
+
+Not implemented. The application uses vision models (image OCR) but no video
+transcription pipeline was found in the codebase. Status: not available.
+
+---
+
+## Async Job Queue
+
+| Job | Queue | Purpose |
+|---|---|---|
+| `NewEp::Pages::DataFields::AiSummaryGenerationJob` | `p3` | Generate AI summary (max 3 retries) |
+| `NewEp::Pages::DataFields::AiSummaryTriggerJob` | async | Trigger on page submit/approve |
+| `Kickstand::NewEp::Pages::AiSummaryCreateVersionJob` | Kickstand | Create version record on stage submission |
+| `NewEp::Pages::Templates::AiDescriptionEmbedJob` | `p3` | Embed template description (Cohere v4) |
+| `Kickstand::NewEp::Pages::GenerateFieldEmbeddingsJob` | Kickstand | Embed page text field content |
+
+---
+
+## AI Prompt Instructions — Team Review Note
+
+Both `AiSummary` and `SmartFill` fields store an `instructions` string that is appended
+to Bedrock's system prompt at generation time. These instructions are set by template
+builders (human, in-app) and directly influence output quality and safety.
+
+**Current situation:**
+- No workflow exists in the gem or backend for auditing/reviewing these prompts at scale.
+- Instructions are stored per-field-instance in the page document.
+- To review: query pages that have AiSummary/SmartFill fields and read the `instructions` field.
+
+**Future work needed:**
+- A review/approval workflow for template-level AI field instructions
+- Possibly surfacing instructions in the template admin UI for bulk review
+- Tracked in: `projects/TODO.md` — "AI prompt review workflow"
+
+---
+
+## Dependencies (Gemfile)
+
+```ruby
+gem 'aws-sdk-bedrockruntime', '~> 1.39'    # LLM invocation
+gem 'aws-sdk-bedrockagentcore', '~> 1.14'  # Agent (smart search)
+gem 'opensearch-ruby'                       # Vector search
+gem 'faraday_middleware-aws-sigv4'          # AWS SigV4 auth
+gem 'google-cloud-translate', '3.6.1'       # Translation for AI tools
+gem 'memo_wise'                             # Embedding memoisation
+gem 'image_processing', '~> 1.2'           # Image resizing
+gem 'ruby-vips', '~> 2'                    # Image processing backend
+```

data/.ai-assistance/code/ecoportal_schema_reference.md

@@ -0,0 +1,240 @@
+# EcoPortal GraphQL Schema — AI Agent Quick Reference
+
+**Source:** Live introspection `20260605T101224_live_ep_graphql_schema.graphql.json`
+**Use this doc to:** orient quickly on the schema without re-running extraction scripts.
+
+---
+
+## Architecture at a Glance
+
+```
+Query {
+  currentOrganization: Organization!   ← ALL org data lives here
+  checkInConfig(identifier:)           ← public kiosk endpoint (no auth)
+  publicPage / publicTemplate          ← anonymous access
+  user / users                         ← user management
+  kickstand*                           ← workflow automation
+}
+```
+
+**Everything important is nested under `currentOrganization`.**
+There are no top-level `page`, `action`, or `contractorEntity` query fields —
+you always go through `currentOrganization.page(id:)`, etc.
+
+---
+
+## Mutation Pattern — Consistent Across All Mutations
+
+**All 161 mutations use a single `input: SomeType!` wrapper.** No mutation has
+separate top-level arguments. This is consistent — build your gem input classes
+as `InputClass.from_model(model)` returning a hash that maps to the single `input:` arg.
+
+```graphql
+mutation UpdateSomething($input: UpdateSomethingInput!) {
+  updateSomething(input: $input) { item { ...fields } errors { ... } }
+}
+```
+
+---
+
+## Schema-Wide Shared Patterns
+
+### `patchVer: Int!` — Optimistic Concurrency Lock
+Present on: `BasePageInterface`, `CheckInConfig`
+- **Non-null on read** — every page/kiosk config response includes it.
+- **Optional on write** (mutation input) — but should always be passed.
+- **Pattern:** read `patchVer` from model → include in update input → server rejects if stale.
+- **Gem:** `BasePage` maps it as `passthrough :patchVer`. Not yet injected in mutation inputs.
+
+### `IdDiffInput` — Incremental Relationship Updates
+```graphql
+input IdDiffInput { additions: [ID!], removals: [ID!] }
+```
+Used for array relationships in **update** mutations (not create). Create mutations use `[ID!]` flat arrays.
+
+Always build separate `Create` and `Update` input classes for areas using `IdDiffInput`.
+
+### `OneToManyInput` — Nested Object Arrays
+```graphql
+input DataFieldOneToManyInput { additions: [DataFieldInput!], updates: [DataFieldInput!], deletions: [ID!] }
+```
+Pattern for complex nested array updates. Present for: `dataFields`, `visitorTypeConfigurations`,
+`requirements`, `legalAgreements`.
+
+### `DeltaResult` — Incremental Sync
+```graphql
+type DeltaResult { id: ID!, delta: DeltaEnum! }   # UPDATED | NOT_FOUND | NEW
+```
+Query fields: `pageDelta(ids:)`, `actionDelta(ids:)`, `contractorEntityDelta(ids:)`,
+`personMemberDelta(ids:)`, `templateDelta(ids:)` — all on `currentOrganization`.
+
+Pass a set of cached IDs → get back which ones changed, were deleted, or are new.
+
+### Mutation Payload Pattern
+Most mutations return: `{ item: TypeUnion, errors: ValidationErrors }` or
+`{ item: SomeType, nextTasks: [MinimalTaskInterface], errors }` (page/task mutations).
+
+---
+
+## Type Inventory by Area
+
+### Pages
+| Type | Kind | Purpose |
+|------|------|---------|
+| `BasePageInterface` | INTERFACE | 50 fields shared by all pages |
+| `BasicPage` | OBJECT | Non-staged page (implements BasePageInterface) |
+| `PhasedPage` | OBJECT | Multi-stage form/register (implements BasePageInterface) |
+| `PageUnion` | UNION | `BasicPage \| PhasedPage` — returned by queries |
+| `Stage` | OBJECT | Single stage of a PhasedPage |
+| `MinimalStage` | OBJECT | `id, name, ordering, state` — lightweight |
+| `UpdatePageInput` | INPUT | `id!, stageId, submit, dataFields, task, page, patchVer, publish` |
+| `PageInput` | INPUT | `locations, otherTags, timeZone, state, taskPriority, name, externalId` |
+| `DataFieldInput` | INPUT | Union-like — one of 20 field type sub-inputs |
+| `DataFieldOneToManyInput` | INPUT | `additions, updates, deletions` for dataFields |
+| `CreateFromTemplateInput` | INPUT | `templateId!, dataFields!, page, stageId, submit, attach` |
+
+**Queries:** `org.page(id:)`, `org.pages(searchConf:, after:, first:, ...)`, `org.myDraftPages`,
+`org.allPages`, `org.templates`, `org.fullTemplates`, `org.minimalTemplates`
+
+**Key mutations:** `updatePage`, `archivePage`, `unarchivePage`,
+`createPageFromTemplate`, `buildPageFromTemplate`, `createPageDraft`,
+`deleteDraftPage`, `publishDraftPage`, `approveReviewPageTask`, `rejectReviewPageTask`
+
+**`PageUnion` members:** Only `BasicPage` and `PhasedPage`. Always query `__typename` to
+dispatch to the right Ruby model class.
+
+### Actions
+| Type | Kind | Purpose |
+|------|------|---------|
+| `Action` | OBJECT | Action instance |
+| `Category` | OBJECT | Action category (name, value, archived, weight) |
+| `UpdateActionInput` | INPUT | `id!, name!, status!, updateMode, recurrence, closeDetail, ...` |
+| `CreateActionInput` | INPUT | `name!, status!, recurrence, linkedResource, draft, ...` |
+| `ActionRecurrenceInput` | INPUT | `daily, weekly, or monthly` sub-input |
+| `SeriesUpdateMode` | ENUM | `ALL \| FORWARD \| ONE` |
+
+**Gem gaps:** `recurrence`, `updateMode`, `tags`, `dueIn/reminderIn`, `linkedResources`
+
+### ContractorEntities
+| Type | Kind | Purpose |
+|------|------|---------|
+| `ContractorEntity` | OBJECT | Contractor org |
+| `UpdateContractorEntityInput` | INPUT | Uses `IdDiffInput` for `leadContractorIds`, `associatedPeopleIds` |
+| `CreateContractorEntityInput` | INPUT | Uses `[ID!]` (flat arrays) for same fields |
+
+### Location Structures
+| Type | Kind | Purpose |
+|------|------|---------|
+| `LocationNodeInterface` | INTERFACE | Shared by all location nodes |
+| `UpdateLocationStructureInput` | INPUT | `id!, name, visitorManagementEnabled, archived, published, weight` |
+
+No `patchVer` on location structures.
+
+### Visitor Management / CheckIn
+| Type | Kind | Purpose |
+|------|------|---------|
+| `CheckInConfig` | OBJECT | Kiosk configuration — has `patchVer: Int!` |
+| `VisitorType` | OBJECT | Visitor category with check-in fields |
+| `Visit` | OBJECT | Check-in record |
+| `UpdateCheckInConfigInput` | INPUT | `id!, locationIds: IdDiffInput, visitorTypeConfigurations:, requirements:, ...` |
+
+**Key for RS location fix:** `updateCheckInConfig(input: { id:, locationIds: { additions: [...], removals: [...] } })`
+
+**Queries on org:** `checkInConfig(id:)`, `checkInConfigs(...)`, `visitorTypes(...)`,
+`visits(...)`, `visitStatus(...)`, `identifyVisitor(...)`
+
+**Mutations:** `checkIn`, `checkOut`, `checkInOnBehalf`, `checkOutOnBehalf`,
+`createCheckInConfig`, `updateCheckInConfig`, `destroyCheckInConfig`,
+`createVisitorType`, `updateVisitorType`, `destroyVisitorType`
+
+### PersonMembers
+| Type | Kind | Purpose |
+|------|------|---------|
+| `PersonMember` | OBJECT | Person (user, contractor, employee) |
+| `PersonSchema` | OBJECT | Custom person schema (org-specific person data model) |
+
+No `PersonMemberInput` — person management is not exposed as mutation (read-only in this API).
+
+**Queries:** `personMember(id:)`, `personMembers(searchConf:)`, `attachablePersonMembers(searchConf:)`,
+`personMembersCreatedSince(date:)`, `personMemberDelta(ids:)`
+
+### Registers
+| Type | Kind | Purpose |
+|------|------|---------|
+| `Register` | OBJECT | Register (page collection/module) — dashboards, templates, pages, preset views |
+| `PresetView` | OBJECT | Saved column/sort config for `previewPages`; id used as `presetViewId` argument |
+
+**Queries:** `register(id:)`, `registers`, `minimalRegisters`, `register.presetViews`
+
+**Mutations:** `createRegister`, `updateRegister`, `destroyRegister`,
+`createPresetView`, `updatePresetView`, `permissionPresetView`, `destroyPresetView`
+
+**Gem coverage:** `Builder::Register` (create/update/destroy) + `Builder::Register::PresetView`
+(list/create/update/permission/destroy). `Query::RegisterPresetViews` to list views by register.
+`Base::Register`, `Model::Register`, `Base::PresetView`, `Model::PresetView` implemented.
+
+---
+
+## Enums Quick Reference
+
+| Enum | Values |
+|------|--------|
+| `StateEnum` | `INACTIVE` / `ACTIVE` / `COMPLETE` |
+| `ActionsStatusEnum` | `open` / `closed` |
+| `TaskPriorityEnum` | `low` / `medium` / `high` / `none` |
+| `SeriesUpdateMode` | `ALL` / `FORWARD` / `ONE` |
+| `DeltaEnum` | `UPDATED` / `NOT_FOUND` / `NEW` |
+| `StageStateEnum` | check schema — `active`, `completed`, `pending`, etc. |
+
+---
+
+## Gem Coverage Map
+
+| Area | Queries | Mutations | Gem status |
+|------|---------|-----------|------------|
+| Actions | ✓ action, actions, actionCategories | ✓ create, update, archive | Well covered. Gaps: recurrence, updateMode, tags |
+| ContractorEntities | ✓ contractorEntities, contractorEntity | ✓ create, update, destroy, manageRelationships | Well covered. Verify IdDiff on update |
+| LocationStructures | ✓ structure, structures, locationDraftById | ✓ draft mutations | Well covered |
+| **Pages** | **✓ fully covered** | **✓ fully covered** | **Phases A–E complete 2026-06-08** |
+| PersonMembers | ✗ | n/a | Gap |
+| Registers | ✓ register, registers, presetViews | ✓ create, update, destroy + preset view CRUD | Covered 2026-06-08 |
+| VisitorManagement | ✗ | ✗ | Gap (customer urgency) |
+| Dashboards/Charts | ✗ | ✗ | Future — see TODO |
+| Delta queries | ✓ pageDelta | n/a | Done |
+| AI tools | ✗ (AiSummary/SmartFill read-only) | ✗ (mutations pending) | See TODO — AI field mutations |
+
+---
+
+## Key Rules for Implementing New Areas
+
+1. **Always fetch before update.** If the output type has `patchVer`, you cannot update
+   without first querying the current value. Build this into the `from_model` input class.
+
+2. **Create vs Update input classes are different.** `IdDiffInput` in update, `[ID!]` in
+   create — always check both input types separately.
+
+3. **Spread `__typename` on union types.** `PageUnion`, `DataFieldUnion`, `SectionUnion`
+   all require `__typename` in the fragment to dispatch to the right Ruby model class.
+
+4. **Mutations always use `input:` wrapper.** No mutation has separate top-level args.
+
+5. **Check `nonNull` carefully.** `required: true` in a Ruby input class should match
+   `field: Type!` in the schema. Mismatches cause server validation errors.
+
+6. **OneToManyInput for nested array updates.** Where you see `*OneToManyInput`, that
+   area needs separate `additions`, `updates`, and `deletions` handling — not a flat replace.
+
+---
+
+## Files to Check Before Implementing Anything
+
+```
+.ai-assistance/code/schema_analysis.md       ← full schema survey
+.ai-assistance/code/diff_as_input.md         ← as_update/as_input pipeline spec
+.ai-assistance/code/ecoportal_schema_reference.md  ← this file
+.ai-assistance/projects/page-model/TODO.md   ← page project plan
+.ai-assistance/projects/api-v2-to-graphql-migration/DECISIONS.md  ← core arch decisions
+lib/ecoportal/api/common/graphql/model/as_input.rb  ← current AsInput (known issue: no patchVer injection)
+lib/ecoportal/api/graphql/logic/base_query.rb       ← query dispatch (recently updated)
+lib/ecoportal/api/graphql/interface/base_page.rb    ← BasePage partial mapping
+```