ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/code/ecoPortal_architecture/10_forces_workflow_builder.md

@@ -1,132 +0,0 @@
-# EcoPortal Forces and Workflow Builder
-
----
-
-## Forces (Legacy Front-End Snippets — Being Replaced)
-
-### What They Are
-
-Forces are AngularJS embedded code snippets that are attached to pages and stages.
-They implement **conditional field behaviour** — things like:
-- Show/hide sections based on field values
-- Compute risk ratings (e.g. `likelihood × severity = risk_score`)
-- Fill gauge values based on select field selections
-- Conditional required field logic
-
-### How They Attach
-
-Forces have **bindings** — connections to specific fields and sections within a stage.
-A force appears in the front-end on a specific stage only if ALL its bindings are
-present in that stage (the bound fields and sections exist in that stage).
-
-### Technical Details
-
-- Backend: `Force` type in GraphQL (`id`, `name`, `script`, `bindings`, `globalBindings`)
-- Front-end: AngularJS components embedded in the stage view
-
-### Forces on GraphQL — CORRECTED (verified, Oscar + code, 2026-07-01)
-
-> ⚠️ An earlier version of this doc (2026-06-09) claimed forces were "not yet scriptable —
-> blocked until a dedicated legacy-forces GraphQL endpoint lands." **That was wrong**, and it
-> persisted because the fact below was only ever captured in machine-local memory. There is no
-> separate "forces endpoint" — forces are managed through the **WorkflowCommandInput command-bus**,
-> the same imperative mechanism used for all template/workflow edits. Full root-cause:
-> `.ai-assistance/projects/ooze-graphql-native-migration/analysis/2026-07-01-forces-via-workflow-commands-miss-rca.md`.
-
-**MUTATING forces — AVAILABLE NOW.** Done via `Workflow*` commands (`WorkflowAddForceInput`,
-`WorkflowEditForceInput`, `WorkflowRemoveForceInput`, `reorderForces`, `addBinding`/`editBinding`/
-`removeBinding`) submitted through `executeWorkflowCommands`. The gem already ships this:
-- Inputs: `lib/ecoportal/api/graphql/input/workflow_command/{add_force,edit_force,remove_force,reorder_forces,add_binding}.rb`
-- Wiring: `input/workflow_command.rb`; mutation `mutation/page/execute_workflow_commands.rb`
-- Model: `base/force.rb` queues `editForce` / `addBinding` commands
-- eco-helpers: `OozeRedirect::ForceCompat#save_force_changes!` already submits them via
-  `graphql.page.execute_force_commands` → `executeWorkflowCommands` (the "to-be-built" sketch was
-  already built).
-
-**READING forces on a page — the only WIP part.** `Query::PageWithForces` (used by
-`ForceCompat#with_each_entry`) currently fails client-side schema validation (PageUnion selections,
-`id` on binding types). This is the genuinely-blocked piece.
-
-**Why scripts still appear "blocked":** `OozeRedirect.force_support?` hard-returns `false`, gating
-read AND write together — so the broken READ disables the working WRITE as collateral. Correcting
-it means splitting the gate (enable writes; gate only the `PageWithForces` fetch) and/or fixing the
-read query. Until then the ~20 force-dependent ooze scripts stay off, but they are **not**
-fundamentally blocked — the write path exists.
-
-**Scripts interact with forces as in v2** (the compat API is real, not a sketch):
-`force.custom_script = new_script` (→ `editForce`), `force.bindings.add(...)` (→ `addBinding`),
-`force.bindings.delete!(...)` (→ `removeBinding`); commands accumulate and submit in one
-`executeWorkflowCommands` call after `process_ooze`.
-
-### Status
-
-**Forces are being replaced** by the Workflow Builder. New templates should use Workflow Builder
-instead of Forces. Existing templates with Forces continue to work and are now editable via the
-command-bus (above).
-
----
-
-## Workflow Builder (`PagesWorkflow`)
-
-### What It Is
-
-The Workflow Builder is the replacement for Forces. It provides server-side (and
-eventually client-side via React) automation configuration for pages.
-
-### Currently Deployed Features
-
-| Feature | Status |
-|---------|--------|
-| Automated notifications | ✅ Deployed |
-| Automated page creation | ✅ Deployed (from workflow triggers) |
-| Task assignments | ✅ Deployed (per workflow rules) |
-| Conditional field/section workflows | 🔄 In development |
-| Custom computed values (risk matrices) | 🔄 In development |
-
-### Conditional Field Workflows (Not Yet Deployed)
-
-This is the AngularJS Forces replacement. Will enable:
-- Show/hide sections based on field values
-- Computed gauge values from select + number field matrices
-- Conditional required fields
-- Section visibility rules
-
-**Why it matters for scripting:** Once deployed, the server may automatically
-update field values or show/hide sections when a page is updated. Scripts that
-update a field may trigger downstream Workflow Builder effects server-side.
-
-### Recent Status (2026-06-07)
-
-The Workflow Builder was recently refactored. New customers have it deployed for
-their templates. Engineering is doing quick fixes via CI/CD. The Workflow Builder
-API is **not stable enough for scripting against its internals** — use the standard
-`updatePage` mutation and let the server trigger workflow effects as side effects.
-
-### GraphQL Access
-
-The `PagesWorkflow` type is queryable, and its mutations **ARE covered in this gem** — via the
-`WorkflowCommandInput` command-bus (~80 command types under `input/workflow_command/`, applied by
-`executeWorkflowCommands`). This is the imperative mechanism for editing workflows, forces, stages,
-sections, fields, strategies, operations, recipients, etc. (NOT a diff-based update). Key types:
-
-- `PagesWorkflow` — the workflow configuration attached to a register
-- `PagesWorkflowCallbackType` — triggers and operations
-- `PagesWorkflowCommandInterface` — commands that were executed
-- `PagesWorkflowOperationsCreatePage` — auto-create operation
-- `PagesWorkflowOperationsAssignTo` — task assignment operation
-- `PagesWorkflowOperationsSendNotification` — notification operation
-
-The command-bus (`input/workflow_command/*.rb` + `mutation/page/execute_workflow_commands.rb`) is
-the same machinery the templates-maintenance project builds on. The API is volatile — design for
-change. (Earlier "not covered in this gem" was wrong — corrected 2026-07-01 alongside the forces fix.)
-
-### Task Side Effects of `updatePage`
-
-When submitting a stage (`submit: true` in `updatePage`), the server may:
-1. Create/assign a `ReviewPage` or `CompletePage` task for the next stage
-2. Create related pages (if workflow has auto-create configured)
-3. Send notifications to relevant users
-4. Trigger time-delay operations for future tasks
-
-Scripts should check mutation payloads for errors but should NOT attempt to manually
-manage workflow state — the server handles it.

data/.ai-assistance/code/ecoPortal_architecture/11_integration_gems.md

@@ -1,187 +0,0 @@
-# EcoPortal Integration Gem Stack
-
----
-
-## Dependency Chain
-
-```
-[graphql-ruby] [graphql-client] [graphlient (forked)] (upstream, external/forked)
-      ↓
-ecoportal-api  /  ecoportal-api-v2              (upstream, team-managed)
-      ↓
-ecoportal-api-graphql                           ← THIS REPO
-      ↓
-eco-helpers                                     (downstream, team-managed)
-```
-
----
-
-## graphlient (Forked)
-
-**Purpose:** GraphQL DSL for building and executing queries.
-**Fork:** `C:\ruby_scripts\git\graphlient` (Oscar's fork of `ashkan18/graphlient`)
-**Branch:** `feature/dsl-only-mode`
-
-**Custom additions to the fork:**
-- `Client#to_query_string(&block)` — builds a full query document from the DSL block
-  and returns a `String` WITHOUT touching Faraday/HTTP. Keystone for the schema-less
-  dispatch mode.
-- `Query#spread(name)` — DSL helper that emits `...FragmentName` in the query string.
-  Replaced the `___Ecoportal__API__GraphQL__Fragment__X` convention from graphql-client.
-
----
-
-## ecoportal-api (Upstream)
-
-**Purpose:** Core base models, auth, content model, base HTTP client.
-**Local path:** `C:\ruby_scripts\git\ecoportal-api`
-
-Provides:
-- `Ecoportal::API::Common::BaseModel` — base model with passthrough, passkey, etc.
-- `Ecoportal::API::Common::Content::DoubleModel` — dirty tracking base
-- `Ecoportal::API::Common::BaseClass` — class_resolver, resolve_class DSL
-- `Ecoportal::API::Common::GraphQL::AuthService` — OAuth authentication
-- `Ecoportal::API::Common::GraphQL::HashHelpers` — deep_dup, etc.
-
----
-
-## ecoportal-api-v2 (Upstream, Being Retired)
-
-**Purpose:** REST API v2 client gem (Page, Register, PersonMember, etc.)
-**Local path:** `C:\ruby_scripts\git\ecoportal-api-v2`
-
-Key things to look for in the source:
-- `Ecoportal::API::Common::Content::StringDigest` — Field ID / ref formula
-- `HashDiffPatch` — the diff algorithm the GraphQL gem adapted
-- `passthrough`, `passarray`, `passboolean`, `passdate` DSL macros
-- Page model with `.as_update` and dirty tracking
-
----
-
-## ecoportal-api-graphql (THIS GEM)
-
-**Local path:** `C:\ruby_scripts\git\ecoportal-api-graphql`
-**Branch:** `pages` (primary development branch)
-
-### Namespace Structure
-
-```
-Ecoportal::API::GraphQL::
-  Logic::         Base classes (BaseModel, BaseQuery, Query, Mutation, etc.)
-  Common::        Shared utilities (DiffService, HashHelpers, etc.)
-  Interface::     GraphQL interfaces (BasePage, LocationStructure)
-  Base::          Concrete base model classes (Page::Basic, Page::Phased, DataField::*)
-  Model::         Domain model classes (inherits from Base::, adds resolvers)
-  Fragment::      GraphQL fragment definitions
-  Fragment::Pages Sub-namespace for customer-facing fragments (CommonPageUnion)
-  Connection::    Connection classes for paginated results
-  Query::         Query classes (Page, Pages, Templates, RegisterPreviewPages, etc.)
-  Mutation::      Mutation classes (Page::Update, Page::Archive, etc.)
-  Payload::       Mutation payload classes
-  Input::         Input object classes (Page::Update, SearchConf, DeltaInput, etc.)
-  Builder::       Builder pattern (Page, Action, ContractorEntity, LocationStructure)
-  Compat::        v2 compatibility layer (Pages, Registers, StageView, StageCollection, etc.)
-  Concerns::      Shared modules (PageCompat, DataFieldAccess, SnakeCamelAccess, etc.)
-```
-
-### Key Conventions
-
-**passthrough vs passboolean vs passdate vs passarray:**
-All macros from ecoportal-api that create read/write accessors:
-- `passthrough :externalId` → `def externalId; doc['externalId']; end` + setter
-- `passboolean :archived` → same but returns `true/false` cast
-- `passdate :createdAt` → same but wraps in DateTime model
-- `passarray :stages` → returns Array from doc
-
-**SnakeCamelAccess concern:** Included in `Logic::BaseModel`. All GraphQL model objects
-respond to snake_case versions of camelCase methods via `method_missing`:
-- `page.external_id` → `page.externalId`
-- `page.patch_ver` → `page.patchVer`
-- `page.source_template_id` → `page.sourceTemplateId`
-- `page.time_zone = 'UTC'` → `page.timeZone = 'UTC'`
-
-**class_resolver pattern:** Used to lazily resolve class references (avoids circular
-requires):
-```ruby
-class_resolver :item_class, 'Ecoportal::API::GraphQL::Model::PageUnion'
-```
-`resolve_class` accepts String (const_get), Symbol (send), or Class.
-
-**Fragment assembly:** `BaseQuery#assemble_fragments` recursively scans query strings
-for `...FragmentName` spreads and appends all needed fragment definitions. Fragment
-sub-namespaces registered via `Fragment.register_namespace(klass)`.
-
-### eco-helpers Compat Layer
-
-```
-Compat::Pages         — graphql.pages (matches apiv2.pages interface)
-Compat::Registers     — graphql.registers (matches apiv2.registers interface)
-Compat::StageView     — page view filtered to one stage (matches v2 stage fetch)
-Compat::StageCollection — stages[name], get_by_name, ordered
-Compat::SearchResults — .total, .total_before_filtering
-Compat::PageReference — .page_id, .active_stage_id
-Compat::Response      — .success?, .status, .body
-```
-
-**Concerns included in Interface::BasePage (all page models):**
-- `PageCompat` — v2 method aliases (external_id, template_id, components, stages?, consolidate!, dirty?, validate)
-- `DataFieldAccess` — components, sections, field_collection, section_collection, data_fields_updates, data_fields_additions
-- `SnakeCamelAccess` — camelCase→snake_case method delegation
-
-**Data field types with full read/write:**
-PlainText, RichText, DateField, Number, Gauge, People, Select, Checklist, TagField, Geo
-
----
-
-## eco-helpers (Downstream)
-
-**Purpose:** Integration script framework for the ecoPortal Integrations Team.
-**Local path:** `C:\ruby_scripts\git\eco-helpers`
-
-Key patterns:
-- Script use case classes inherit from `OozeBase` or `RegisterUpdate`
-- `RegisterUpdate` manages a loop: search register → fetch page → modify → save
-- `RegisterUpdate` tracks changes: if `dirty?(page)`, triggers `pages.update(page)`
-- `RegisterUpdate` tracks stage changes: if stage changes, fetches new stage view
-
-**Stage iteration pattern:**
-```ruby
-# In RegisterUpdate
-apiv2.registers.search(register_id, search_options) do |page_result|
-  ooze = apiv2.pages.get(page_result.id)
-  stage = ooze.stages.get_by_name('Risk Assessment')
-  apiv2.pages.get(ooze.id, stage_id: stage.id).tap do |stage_view|
-    with_fields(stage_view, type: :plain_text) { |f| f.value = 'Updated' }
-    apiv2.pages.update(stage_view)
-  end
-end
-```
-
-With GraphQL compat, `apiv2` is replaced by `graphql` and the pattern works unchanged.
-
-### Filter helpers (eco-helpers)
-
-```ruby
-date_range_filter(from: Date.today - 7, to: Date.today, key: :updated_at)
-# → { type: "date_filter", key: "updated_at", lbound: "ISO8601", ubound: "ISO8601", time_zone: "..." }
-
-tags_filter(['Auckland', 'Wellington'], any: true)
-# → { type: "tag_filter", tags: [...], mode: "any", negate: false, key: "tags" }
-```
-
-The GraphQL compat layer translates `date_filter` lbound/ubound → gte/lte.
-Other filter types pass through to the ES backend unchanged.
-
----
-
-## Backend Source (ecoPortal Rails)
-
-**Local path:** `C:\docker\ecoPortal_master\`
-
-Key namespaces and files to look up:
-- `Enzyme::` — old Rails models (AngularJS era, being replaced)
-- `NewEp::` — current Rails models (React era)
-- `NewEp::DataField` — current data field model (was `Enzyme::Membrane`)
-- `Ecoportal::API::Common::Content::StringDigest` (actually in ecoportal-api-v2) — Field ID formula
-- Rails `services/` loadable path — Migrator and other background services
-- `.graphql` files — front-end React component GraphQL queries/fragments

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

@@ -1,236 +0,0 @@
-# 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.