ecoportal-api-graphql 1.3.13 → 1.3.16

data/.rubocop.yml

@@ -1,121 +0,0 @@
-AllCops:
-  TargetRubyVersion: 3.2
-  Exclude:
-    - 'config/routes.rb'
-  NewCops: enable
-
-Metrics/ClassLength:
-  Max: 350
-Metrics/ModuleLength:
-  Max: 400
-Metrics/MethodLength:
-  Max: 100
-Metrics/BlockLength:
-  CountAsOne: ['array', 'heredoc', 'method_call']
-  Max: 50
-Metrics/AbcSize:
-  Max: 30
-Metrics/ParameterLists:
-  Max: 5
-  CountKeywordArgs: false
-Metrics/CyclomaticComplexity:
-  Max: 30
-Metrics/PerceivedComplexity:
-  Max: 30
-
-Layout/HashAlignment:
-  EnforcedColonStyle: table
-  EnforcedHashRocketStyle: table
-
-Style/BlockDelimiters:
-  BracesRequiredMethods: ['log']
-  AllowedMethods: ['proc', 'new']
-  Enabled: false
-Style/HashSyntax:
-  EnforcedShorthandSyntax: either
-  EnforcedStyle: no_mixed_keys
-Style/ArgumentsForwarding:
-  UseAnonymousForwarding: false
-Style/ClassAndModuleChildren:
-  Enabled: false
-Style/FrozenStringLiteralComment:
-  Enabled: false
-Style/StringLiterals:
-  Enabled: false
-Style/Documentation:
-  Enabled: false
-Style/CommentedKeyword:
-  Enabled: false
-Layout/LeadingCommentSpace:
-  Enabled: false
-  AllowGemfileRubyComment: true
-Style/MultilineBlockChain:
-  Enabled: false
-Style/StringLiteralsInInterpolation:
-  Enabled: false
-Style/AndOr:
-  Enabled: false
-Style/Alias:
-  EnforcedStyle: prefer_alias_method
-Style/FetchEnvVar:
-  Enabled: false
-Style/RegexpLiteral:
-  EnforcedStyle: mixed
-  AllowInnerSlashes: true
-
-Layout/LineLength:
-  Enabled: false
-Layout/SpaceInsideHashLiteralBraces:
-  Enabled: false
-Layout/SpaceInsideBlockBraces:
-  Enabled: false
-Layout/SpaceAroundOperators:
-  Enabled: false
-Layout/ExtraSpacing:
-  AllowForAlignment: true
-Layout/AccessModifierIndentation:
-  EnforcedStyle: indent
-Layout/DotPosition:
-  EnforcedStyle: trailing
-Layout/MultilineMethodCallIndentation:
-  EnforcedStyle: indented
-Layout/FirstHashElementIndentation:
-  Enabled: false
-Layout/EmptyLineAfterGuardClause:
-  Enabled: false
-Layout/EndOfLine:
-  Enabled: false
-
-Naming/VariableNumber:
-  EnforcedStyle: snake_case
-  CheckSymbols: false
-Naming/MethodParameterName:
-  # id/ids are standard entity identifiers; clientMutationId is the canonical
-  # GraphQL/Relay mutation field name (camelCase by design — see Naming/MethodName).
-  AllowedNames: ['x', 'y', 'i', 'j', 'id', 'ids', 'clientMutationId']
-Naming/VariableName:
-  # clientMutationId mirrors the GraphQL schema field name verbatim.
-  AllowedIdentifiers: ['clientMutationId']
-Naming/RescuedExceptionsVariableName:
-  Enabled: false
-Naming/MethodName:
-  Enabled: false
-Naming/BlockForwarding:
-  Enabled: false
-
-# fragment.rb intentionally defines a top-level `Fragment` namespace (for client
-# scripts) alongside the gem's `Ecoportal::API::GraphQL::Fragment`.
-Style/OneClassPerFile:
-  Exclude:
-    - 'lib/ecoportal/api/graphql/fragment.rb'
-
-# Gem entry point mirrors the hyphenated gem name `ecoportal-api-graphql`.
-Naming/FileName:
-  Exclude:
-    - 'lib/ecoportal/api-graphql.rb'
-
-# QueryArray#each intentionally re-enters the enumerator with connection_block,
-# not the verbatim method arguments.
-Lint/ToEnumArguments:
-  Exclude:
-    - 'lib/ecoportal/api/graphql/logic/query_array.rb'

data/.ruby-version

@@ -1 +0,0 @@
-3.2.2

data/.yardopts

@@ -1,10 +0,0 @@
---readme README.md
---charset utf-8
---markup-provider=redcarpet
---markup=markdown
---no-private
---output-dir ./doc
-'lib/**/*.rb'
--
-CHANGELOG.md
-LICENSE

data/CLAUDE.md

@@ -1,243 +0,0 @@
-# CLAUDE.md — ecoportal-api-graphql
-
-AI agent instructions for working in this repository. Read this before touching any code.
-
----
-
-## Read these first — every session
-
-```
-docs/worklog.md                          ← current state, blockers, open questions
-.ai-assistance/projects/<slug>/TODO.md   ← active project task list
-.ai-assistance/local/paths.json          ← local paths to sibling repos (gitignored — machine-specific)
-.ai-assistance/bridge/CLAUDE.md          ← bridge protocol: format, lifecycle, cross-repo requests
-.ai-assistance/bridge/inbox/             <- unread cross-project bridge messages (PENDING = unread); surfaced at session start by .ai-assistance/scripts/bridge-inbox-check.sh
-.ai-assistance/code/ecoPortal_architecture/  ← VERIFIED PLATFORM KNOWLEDGE — how the platform behaves
-                                            (data model, API layers, page/stage workflows, fields, search).
-                                            Read 00_overview_and_index first, then the area file for the
-                                            task at hand, BEFORE implementing platform logic. See ADR-012.
-```
-
-> Platform behaviour is documented in `ecoPortal_architecture/` for a reason: do not infer a
-> stage/workflow/field rule from code alone when a verified note exists. If you confirm a new
-> platform fact, add it to the relevant doc with its evidence (`file:line` or "confirmed by
-> &lt;user&gt; on &lt;date&gt;") in the same session -- that tree is the durable, shared home.
-
----
-
-## Repository Role
-
-`ecoportal-api-graphql` is a **Ruby gem** that provides a GraphQL client layer on top of EcoPortal's REST API infrastructure. It sits between the upstream API gems and downstream consumer code.
-
-**Dependency chain:**
-
-```
-[graphql-ruby]  [graphql-client]  [graphlient]  (upstream, external/forked)
-      ↓
-ecoportal-api  /  ecoportal-api-v2              (upstream, team-managed)
-      ↓
-ecoportal-api-graphql                           ← THIS REPO
-      ↓
-eco-helpers                                     (downstream, team-managed)
-```
-
-Backwards compatibility with `eco-helpers` must be preserved unless explicitly broken by the developer.
-
-**For full dependency details — local paths, remotes, fork relationships, and access notes — see `.ai-assistance/code/dependencies.md`.**
-
----
-
-## Key Folder Layout
-
-```
-lib/ecoportal/api/graphql/       Main gem code
-  base/                          Base model classes (data structures)
-  builder/                       Builder pattern classes
-  concerns/                      Shared modules (mixins)
-  connection/                    GraphQL connection types
-  error/                         Error classes
-  fragment/                      GraphQL fragment definitions
-  helpers/                       Utility helpers
-  input/                         Mutation input objects
-  interface/                     GraphQL interface types
-  logic/                         Query/mutation execution logic
-  model/                         Domain model classes
-  mutation/                      Mutation definitions
-  payload/                       Mutation response payloads
-  query/                         Query definitions
-
-lib/ecoportal/api/common/graphql/ Shared/common GraphQL utilities
-
-spec/ecoportal/                  RSpec specs (mirrors lib/ structure)
-tests/                           Manual integration test scripts
-.ai-assistance/                         AI agent resources (see below)
-```
-
----
-
-## .ai-assistance/ Resources
-
-All AI agent tooling lives under `.ai-assistance/`. **Read relevant docs before analysing code.**
-
-| Path | Purpose |
-|------|---------|
-| `.ai-assistance/skills/` | Skill definitions — see each `SKILL.md` |
-| `.ai-assistance/code/` | Code specs for AI (per-area markdown docs) |
-| `.ai-assistance/code/dependencies.md` | Full dependency map with local paths and remote URLs |
-| `.ai-assistance/code/refactoring/` | Refactoring opportunity log |
-| `.ai-assistance/projects/` | Project intent, TODOs, and decision logs |
-| `.ai-assistance/integrations/` | Optional dev tool integrations (GitLab MCP, GitKraken MCP, local git) |
-
-### Commit authorship
-
-**Default: developer only.** Do not add `Co-Authored-By: Claude ...` to commits unless
-the developer explicitly requests it for a specific commit.
-
-### Available Skills
-
-| Skill | SKILL.md | Purpose |
-|-------|----------|---------|
-| `ep-ai-manager` | `.ai-assistance/skills/ep-ai-manager/SKILL.md` | Check alignment with ep-ai-standards |
-| `ruby-scripting` | `.ai-assistance/skills/ruby-scripting/SKILL.md` | Guidelines for scripts using ecoportal gem stack |
-| `gemini-assist` | `.ai-assistance/skills/gemini-assist/SKILL.md` | Offload large-context tasks to Gemini |
-| `ai-instructions` | `.ai-assistance/skills/ai-instructions/SKILL.md` | Manage CLAUDE.md and skill files |
-| `code-specs` | `.ai-assistance/skills/code-specs/SKILL.md` | Write/update AI-readable code documentation |
-| `spec-generation` | `.ai-assistance/skills/spec-generation/SKILL.md` | Generate RSpec specs for backwards-compat |
-| `refactor` | `.ai-assistance/skills/refactor/SKILL.md` | Identify and log refactoring opportunities |
-| `project-cycle` | `.ai-assistance/skills/project-cycle/SKILL.md` | Project planning, TODOs, decisions |
-| `procedural-memory` | `.ai-assistance/skills/procedural-memory/SKILL.md` | Distill recurring work routines and surface likely next steps |
-
----
-
-## Permissions & Autonomy
-
-Read `.ai-assistance/conventions/permission-guidance.md` to understand:
-- Which operations require confirmation vs. proceed autonomously (autonomy zones)
-- When and how to suggest new allowlist entries to the developer
-- Project vs. global scope for `settings.json` rules
-- How to handle compound `cd path && cmd` patterns in sibling repos
-
----
-
-## Running Tests
-
-```bash
-# Full suite
-bundle exec rspec
-
-# Single file
-bundle exec rspec spec/ecoportal/api/graphql/input/search_conf_spec.rb
-
-# Live AI tests (requires ANTHROPIC_API_KEY — loaded automatically from .env)
-bundle exec rspec spec/ecoportal/api/graphql/input/search_conf/ai_generator_spec.rb --tag live
-```
-
-**Live tests:** `.env` is loaded via `dotenv` in `spec_helper.rb`. Add `ANTHROPIC_API_KEY=sk-ant-...` to `.env` (gitignored) — no need to export to shell.
-
----
-
-## Conventions
-
-- **Namespace:** `Ecoportal::API::GraphQL` — capital G, Q, L, matching the `class GraphQL` declaration in `lib/ecoportal/api/graphql.rb`
-- **File/class mirroring:** File path mirrors the class namespace exactly.
-- **Spec mirroring:** Spec files mirror `lib/` structure under `spec/`.
-- **Code spec docs:** For every area analysed, a corresponding `.ai-assistance/code/<area>.md` should exist or be created/updated.
-- **No silent breaking changes:** Any change that affects the public interface of this gem must be noted in the active project's DECISIONS log and confirmed with the developer.
-- **Gemini responses must be verified** before applying — Gemini hallucinates details. Always cross-check against actual code.
-- **Rubocop:** All generated Ruby code must comply with `.rubocop.yml`. Run `bundle exec rubocop <file>` to verify.
-
----
-
-## First Session on a New Machine
-
-If `.ai-assistance/local_paths.md` does not exist, run the collaborator setup flow from the `project-cycle` skill **before** any other work. In short:
-
-- Ask which upstream/downstream repos the developer has cloned locally.
-- In Cowork: offer to connect each folder. In Claude Code: ask for the path or locate it via shell.
-- Create `.ai-assistance/local_paths.md` from `.ai-assistance/local_paths.example.md` with their confirmed paths.
-- If a repo isn't available locally, offer to fetch what's needed from the remote URL instead.
-
----
-
-## Before Starting Any Task
-
-1. Check `.ai-assistance/local_paths.md` — if missing, run First Session setup above before proceeding.
-2. Check `.ai-assistance/projects/` for an active project file.
-3. Check `.ai-assistance/code/` for an existing spec doc covering the area you'll work in.
-4. Check `.ai-assistance/code/dependencies.md` if the task touches upstream or downstream gems.
-5. Check `.ai-assistance/code/refactoring/` for logged opportunities relevant to the area.
-6. If none of the above exist for your area — create them as you go (see `code-specs` skill).
-
-## Before Making Working Tree Changes (Claude Code only)
-
-If you are about to modify files outside `bridge/inbox/` or `bridge/outbox/`, follow the
-working tree safety protocol **before touching anything**:
-
-Full protocol: `.ai-assistance/conventions/code-working-tree-protocol.md`
-
-Summary:
-1. Check for `.ai-assistance/bridge/LOCK` — stop and inform user if actively locked
-2. Acquire lock (watermark: agent, user, timestamp, expiry, intent, files)
-3. Check for unstaged changes that overlap with your planned files — if overlap, commit them first as `wip: <description>`; if no overlap, proceed without touching them
-4. Apply your changes
-5. Commit with a descriptive message
-6. Release lock (`rm .ai-assistance/bridge/LOCK`)
-
----
-
-## Bridge: CoWork ↔ Claude Code
-
-A file-based channel for delegating tasks between CoWork and Code.
-Full protocol: `.ai-assistance/bridge/CLAUDE.md`
-
-### On every Code session startup
-
-**Before responding to the user, read the bridge status file:**
-
-```bash
-cat .ai-assistance/bridge/STATUS 2>/dev/null || echo "no status yet"
-```
-
-The `SessionStart` hook runs `bridge-init.sh` automatically and writes its output to
-`bridge/STATUS`. Reading this file tells you immediately whether there are pending tasks.
-
-If `pending > 0`: tell the user "I have N pending bridge task(s): [list]" and ask whether
-to process them now before starting other work.
-
-If the STATUS file is missing (first session or hook didn't run): run manually:
-```bash
-bash .ai-assistance/scripts/bridge-init.sh
-```
-
-### Why Code doesn't report pending tasks automatically on startup
-
-Claude Code is passive — it waits for a user prompt before doing anything, regardless
-of what hooks run or what this file says. The `SessionStart` hook runs `bridge-init.sh`
-and writes `bridge/STATUS`, but Code will not speak unprompted.
-
-**The intended workflow:** at the start of each session, ask:
-> "Any pending tasks?"
-
-Code will read `bridge/STATUS` (already written by the hook) and report immediately.
-This is one short question — the right tradeoff for an interactive tool.
-
-Hook stdout is also not injected into Code's context — only the STATUS file is readable.
-Do not attempt to use hook output as a message source; write to a file instead.
-
-### Before writing a bridge task
-
-Check `.ai-assistance/capabilities/[your-env].md` — only bridge what you genuinely cannot do yourself.
-
-### Key paths
-
-| Path | Purpose |
-|------|---------|
-| `.ai-assistance/bridge/inbox/` | Tasks waiting to be processed |
-| `.ai-assistance/bridge/outbox/` | Completed results |
-| `.ai-assistance/bridge/archive/` | Completed pairs (audit trail) |
-| `.ai-assistance/bridge/STATUS` | Bridge status file written by bridge-init.sh on session start |
-| `.ai-assistance/bridge/LOCK` | Working tree lock file (never commit; gitignored) |
-| `.ai-assistance/capabilities/` | Per-environment capability registry |
-| `.ai-assistance/capabilities/assumptions-log.md` | Dated assumptions + verification status |
-| `.ai-assistance/conventions/` | Instruction file structure rules |
-| `.ai-assistance/scripts/` | Token-offload scripts (see `scripts/CLAUDE.md`) |

data/Gemfile

@@ -1,30 +0,0 @@
-source "https://rubygems.org"
-
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
-
-# Specify your gem's dependencies in ecoportal-api.gemspec
-gemspec
-
-# Pin graphlient to our fork's FROZEN release branch `pre-v0.0.9` (a snapshot of the fork's
-# master, which carries the DSL/directive work — #115 to_query_string/spread, #116 directives
-# DSL / on(:Type) / fragment(:Name); lib/ is byte-identical to feature/directives-dsl-support).
-# Frozen so the gem (and downstream repos) pin a stable ref, not a moving feature branch.
-# Revisit when the fork cuts a real gem release (>= 0.8.x with these features published).
-# Frozen: 2026-07-02.
-gem 'graphlient', git:    'https://github.com/rellampec/graphlient.git',
-                  branch: 'pre-v0.0.9'
-
-# NOTE: no graphql-client override. It is a TRANSITIVE dependency of graphlient and
-# resolves to the published 0.26.0 — this gem does not use graphql-client directly
-# (queries go through the graphlient DSL; the Group-3 refactor removed `client.parse`),
-# so the fork's revival MRs (#79–#82, still unattended upstream) are not required here.
-# FUTURE: we plan to retake the graphql-client fork revival and land more graphlient +
-# ecoportal-api-graphql features (and downstream) — re-introduce a pin at that point.
-# See memory: project-fork-revival-strategy / project-graphql-client-redesign.
-
-# Optional — only needed for SearchConf::AIGenerator live tests.
-# Not added to gemspec; callers must install it themselves.
-# Uses http source to bypass local SSL inspection (e.g. Norton Antivirus).
-source 'http://rubygems.org' do
-  gem 'anthropic'
-end

data/Rakefile

@@ -1,90 +0,0 @@
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require 'rubocop/rake_task'
-require 'yard'
-require 'redcarpet'
-
-desc 'run the specs'
-RSpec::Core::RakeTask.new(:spec)
-
-desc 'run rspec showing backtrace'
-RSpec::Core::RakeTask.new(:spec_trace) do |task|
-  task.rspec_opts = ['--backtrace']
-end
-task :rspec_trace => :spec_trace
-
-desc 'run rspec stopping on first fail, and show backtrace'
-RSpec::Core::RakeTask.new(:spec_fast) do |task|
-  task.rspec_opts = ['--fail-fast', '--backtrace']
-end
-task :rspec_fast  => :spec_fast
-
-desc 'run rubocop diaplying cop names'
-RuboCop::RakeTask.new(:rubocop) do |t|
-  t.options = ['--display-cop-names']
-end
-
-# default task name is yard
-desc 'Yard: generate all the documentation'
-YARD::Rake::YardocTask.new(:doc) do |t|
-  #t.files = ['lib/**/*.rb']
-end
-
-desc 'Generate JSON dependency/structure map -> .ai-assistance/code/dep-graph.json'
-task :dep_graph do
-  load '.ai-assistance/scripts/dep_graph.rb'
-  output = '.ai-assistance/code/dep-graph.json'
-  DepGraph.run(lib_dir: 'lib', output_path: output)
-  puts "Written -> #{output}"
-end
-
-desc 'Detect workflow-space schema drift: COMMAND_MAP vs stored introspection + SCHEMA_VERSION currency'
-task :schema_drift do
-  require 'json'
-
-  schema_glob  = '.ai-assistance/tmp/*_live_ep_graphql_schema.graphql.json'
-  schema_files = Dir[schema_glob]
-  abort "No schema file at #{schema_glob} — re-run introspection first" if schema_files.empty?
-
-  schema_path = schema_files.last
-  puts "Schema: #{schema_path}"
-  schema_date = File.basename(schema_path)[/\d{8}/]
-
-  schema = JSON.parse(File.read(schema_path))
-  types  = schema.dig('data', '__schema', 'types').to_h { |t| [t['name'], t] }
-  wci    = types['WorkflowCommandInput'] or abort('WorkflowCommandInput not found in schema')
-
-  schema_keys = Set.new(wci['inputFields'].map { |f| f['name'] })
-
-  cmd_src  = File.read('lib/ecoportal/api/graphql/input/workflow_command.rb')
-  gem_keys = Set.new(cmd_src.scan(/^\s+(\w+):\s+'Ecoportal/).flatten)
-
-  added   = (schema_keys - gem_keys).sort
-  removed = (gem_keys - schema_keys).sort
-
-  puts "\n=== WorkflowCommandInput (#{schema_keys.size} schema / #{gem_keys.size} gem) ==="
-  if added.empty? && removed.empty?
-    puts "In sync — no drift"
-  else
-    added.each   { |k| puts "  + #{k}  (in schema, missing from COMMAND_MAP)" }
-    removed.each { |k| puts "  - #{k}  (in COMMAND_MAP, absent from schema)" }
-  end
-
-  puts "\n=== SCHEMA_VERSION constants (expected #{schema_date}) ==="
-  mismatches = []
-  Dir['lib/**/*.rb'].each do |f|
-    File.read(f).scan(/SCHEMA_VERSION\s*=\s*'(\d+)'\.freeze/).each do |m|
-      mismatches << "  #{f}: '#{m[0]}'" if m[0] != schema_date
-    end
-  end
-  mismatches.empty? ? puts("All match #{schema_date}") : mismatches.each { |m| puts m }
-
-  abort "\nDrift detected — update gem files before bumping schema date" unless added.empty? && removed.empty?
-end
-
-desc 'default task: runs rubocop and rspec'
-task :default do
-  Rake::Task[:rubocop].invoke
-ensure
-  Rake::Task[:spec].invoke
-end

data/bin/console

@@ -1,14 +0,0 @@
-#!/usr/bin/env ruby
-
-require "bundler/setup"
-require "ecoportal/api-graphql"
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "pry"
-Pry.start(__FILE__)

data/bin/setup

@@ -1,8 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here

data/bin/setup.ps1

@@ -1,6 +0,0 @@
-
-<# For mor information on Strict-Mode, visit:
- https://devblogs.microsoft.com/scripting/enforce-better-script-practices-by-using-set-strictmode/ #>
-Set-StrictMode -Version 1.0
-
-bundle install

data/docs/self-docs/ARCHITECTURE.md

@@ -1,88 +0,0 @@
----
-schema_version: "1.1"
-repo: "ecoportal-api-graphql"
-doc: architecture
-last_generated: "2026-07-09"
-source_head: "3f7b877"
-review_status: draft
----
-
-# Architecture -- ecoportal-api-graphql
-
-**Scope:** High-level structure only. Deep per-area detail lives in `.ai-assistance/code/`
-(`code-specs`); link to it rather than duplicating.
-
-## Top-level structure
-
-| Directory | Role |
-|---|---|
-| `lib/` | The gem source. `lib/ecoportal/api/graphql/` holds the layered client; `lib/ecoportal/api/common/graphql/` holds shared utilities (HTTP client, base model, helpers, patches). |
-| `spec/` | RSpec specs, mirroring the `lib/` structure. |
-| `tests/` | Manual integration test scripts (live-API characterization, not the RSpec suite). |
-| `bin/` | Development console / helper executables. |
-| `scripts/` | Token-offload and tooling scripts (see `scripts/CLAUDE.md`). |
-| `docs/` | Human docs, worklog, and this self-docs set. |
-| `.ai-assistance/` | AI agent resources: code-specs, project intent/TODOs, skills, bridge, conventions. |
-| `.claude/` | Claude Code settings and hooks for this repo. |
-
-## Key components
-
-Reused from `.ai-assistance/code/OVERVIEW.md` and `.ai-assistance/code/ecoPortal_architecture/`;
-not re-analysed here.
-
-- **Main class `Ecoportal::API::GraphQL`** (`lib/ecoportal/api/graphql.rb`) -- the public entry
-  point, instantiated with credentials (email, pass, org_id, host). Exposes builders and
-  convenience shortcuts per domain.
-- **`Common::GraphQL::Client`** (`lib/ecoportal/api/common/graphql/client.rb`) -- the HTTP layer,
-  extending `Graphlient::Client`. Handles auth (`AuthService`), org context, and timeouts;
-  `no_schema: true` is always passed, so schema introspection is disabled and queries are not
-  validated against a schema at build time.
-- **Layered namespace** under `Ecoportal::API::GraphQL::` (folder mirrors module exactly):
-  `Builder` (developer-facing facade per domain) -> `Query` / `Mutation` (operation definitions)
-  -> `Logic` (execution: base_query, base_model, payload, input, connection) -> `Fragment`
-  (fragment strings) -> `Model` (read-side response models), `Input` / `Payload` (write side) ->
-  `Base` (shared base classes), `Interface` (GraphQL interface types) -> `Common::GraphQL::Client`.
-- **`Compat::` layer** -- v2 compatibility shims (`Pages`, `Registers`, `StageView`,
-  `StageCollection`, etc.) that let `eco-helpers` treat `graphql` as a drop-in for the older `apiv2`
-  interface.
-- **`Diff::` and `Builder::TemplateBuilder`** -- the template build-and-maintenance engine
-  (self-version and cross-object diff, pairing engine + ledger, `Change`-to-`WorkflowCommand`
-  synthesis, unified BUILD emitter). This is where current development is concentrated.
-
-## How they fit
-
-A consumer instantiates `Ecoportal::API::GraphQL` with credentials, then calls a `Builder` for the
-domain it wants (page, template, action, contractor entity, location structure). The builder
-composes `Query`/`Mutation` operations, which the `Logic` layer executes through
-`Common::GraphQL::Client` over HTTP. Fragments are assembled at query build time
-(`BaseQuery#assemble_fragments` scans query strings for `...FragmentName` spreads). Responses parse
-into `Model` objects (read side); mutations take `Input` objects and return `Payload` objects
-(write side). The `Compat` layer re-exposes this so downstream `eco-helpers` scripts keep working
-unchanged.
-
-## Entry points
-
-- `require 'ecoportal/api-graphql'` loads `ecoportal-api-v2` (and transitively `ecoportal-api`),
-  the version file, `ecoportal/api/common.graphql`, then `ecoportal/api/graphql`.
-- Runtime entry is `Ecoportal::API::GraphQL.new(email:, pass:, org_id:, host:)`.
-
-## Build / test tooling
-
-- Build: RubyGems / Bundler. Gem spec: `ecoportal-api-graphql.gemspec`. Version constant:
-  `Ecoportal::API::GRAPQL_VERSION`.
-- Tests: RSpec (`bundle exec rspec`). Live AI tests are `--tag live` and require `ANTHROPIC_API_KEY`
-  loaded from `.env` via `dotenv`.
-- CI: no CI config file was detected at the repo root by the scanner (`ci_files: []`).
-  <!-- TODO(human): confirm whether CI runs elsewhere (e.g. GitLab CI defined outside root) or is absent. -->
-
-## Links to detailed docs
-
-- `.ai-assistance/code/OVERVIEW.md` -- gem overview, entry points, namespace convention.
-- `.ai-assistance/code/ecoPortal_architecture/00_overview_and_index.md` -- verified platform
-  knowledge index (data model, API layers, page/stage workflows, fields, search).
-- `.ai-assistance/code/ecoPortal_architecture/11_integration_gems.md` -- the integration gem stack.
-- `.ai-assistance/code/dependencies.md` -- full dependency map (remotes, fork relationships).
-- `.ai-assistance/code/diff_pairing_engine.md`, `.ai-assistance/code/diff_service_deep_dive.md`,
-  `.ai-assistance/code/template_diff_pairing_domain.md` -- the template diff/build engine.
-- `.ai-assistance/code/data_fields.md`, `.ai-assistance/code/graphql_domain_knowledge.md`,
-  `.ai-assistance/code/schema_analysis.md` -- data-field and schema detail.

data/docs/self-docs/CHANGES.jsonl

@@ -1,12 +0,0 @@
-{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/OVERVIEW.md", "change": "created", "from_hash": null, "to_hash": "a43c976a85ebfad6"}
-{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/ARCHITECTURE.md", "change": "created", "from_hash": null, "to_hash": "b0989977a912aab1"}
-{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/CONVENTIONS.md", "change": "created", "from_hash": null, "to_hash": "1649159eb799a7b8"}
-{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/INTEGRATIONS.md", "change": "created", "from_hash": null, "to_hash": "bae9f91748e33af1"}
-{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/STATUS.md", "change": "created", "from_hash": null, "to_hash": "08841d1d45eea2d6"}
-{"ts": "2026-07-06T11:15:00Z", "file": "docs/self-docs/OVERVIEW.md", "change": "updated", "from_hash": "a43c976a85ebfad6", "to_hash": "391055c9a6a687b9"}
-{"ts": "2026-07-06T11:15:00Z", "file": "docs/self-docs/ARCHITECTURE.md", "change": "updated", "from_hash": "b0989977a912aab1", "to_hash": "ad05f25b95b49c00"}
-{"ts": "2026-07-09T07:08:00Z", "file": "docs/self-docs/OVERVIEW.md", "change": "updated", "from_hash": "391055c9a6a687b9", "to_hash": "c403012498ab9247"}
-{"ts": "2026-07-09T07:08:00Z", "file": "docs/self-docs/INTEGRATIONS.md", "change": "updated", "from_hash": "bae9f91748e33af1", "to_hash": "d271ac76361e4638"}
-{"ts": "2026-07-09T07:08:00Z", "file": "docs/self-docs/STATUS.md", "change": "updated", "from_hash": "08841d1d45eea2d6", "to_hash": "1acf51a3e7822dfb"}
-{"ts": "2026-07-09T07:08:00Z", "file": "docs/self-docs/COMPLIANCE.md", "change": "created", "from_hash": null, "to_hash": "1e72c2356b4e3579"}
-{"ts": "2026-07-09T07:08:00Z", "file": "docs/self-docs/OPERATIONS.md", "change": "created", "from_hash": null, "to_hash": "878b50d02339acb7"}