ecoportal-api-graphql 1.3.12 → 1.3.13

data/.claude/settings.json

@@ -1,146 +1,150 @@
-{
-  "permissions": {
-    "defaultMode": "auto",
-    "allowedTools": [
-      "Read"
-    ],
-    "permissionRules": [
-      {
-        "tool": "Write",
-        "pattern": "/**",
-        "action": "allow"
-      },
-      {
-        "tool": "StrReplace",
-        "pattern": "/**",
-        "action": "allow"
-      }
-    ],
-    "allow": [
-      "WebFetch(domain:anthropic.com)",
-      "WebFetch(domain:npmjs.com)",
-      "Write(.glaudeignore)",
-      "Update(.glaudeignore)",
-      "Bash(rm .ai-assistance/bridge/LOCK)",
-      "Read(.git/**)",
-      "Read(**/rubygems/**)",
-      "Write(*.md)",
-      "Edit(.ai-assistance/**)",
-      "Update(.ai-assistance/**)",
-      "Write(.ai-assistance/**)",
-      "Write(lib/**)",
-      "Write(spec/**)",
-      "Bash(git status)",
-      "Bash(git diff *)",
-      "Bash(git log *)",
-      "Bash(git add *)",
-      "Bash(git commit *)",
-      "PowerShell(git status)",
-      "PowerShell(git diff *)",
-      "PowerShell(git log *)",
-      "PowerShell(git add *)",
-      "PowerShell(git commit *)",
-      "Bash(npm test)",
-      "Bash(npm run lint)",
-      "Bash(npm run build)",
-      "Bash(vitest *)",
-      "Bash(jest *)",
-      "PowerShell(npm test)",
-      "PowerShell(npm run lint)",
-      "PowerShell(npm run build)",
-      "Bash(black .)",
-      "Bash(pytest)",
-      "Bash(python -m unittest)",
-      "Bash(ruff check *)",
-      "Bash(bundle exec rspec *)",
-      "Bash(bundle exec rubocop *)",
-      "PowerShell(pytest)",
-      "PowerShell(python -m unittest)",
-      "PowerShell(ruff check *)",
-      "PowerShell(bundle exec rspec *)",
-      "PowerShell(bundle exec rubocop *)",
-      "Bash(node .ai-assistance/scripts/token-logger.js)",
-      "Bash(node .ai-assistance/scripts/token-session-start.js)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git status*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git log*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git diff*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git show*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git branch*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git fetch*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git checkout*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git switch*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git add*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git commit*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git rev-parse*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git merge-base*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git ls-remote*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git stash*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rspec*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rake test*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rubocop*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && bundle install*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git status*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git log*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git diff*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git show*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git branch*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git fetch*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git checkout*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git switch*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git add*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git commit*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git rev-parse*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git merge-base*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git ls-remote*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git stash*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle exec rake test*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle exec rubocop*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle install*)"
-    ],
-    "deny": [
-      "Read(*.env)",
-      "Read(./.env*)",
-      "Read(./secrets/**)",
-      "Bash(*cat *.env*)",
-      "Bash(*grep *.env*)",
-      "Bash(printenv*)",
-      "Bash(env)",
-      "Write(.git/*)",
-      "Edit(.git/*)",
-      "Bash(git push *)",
-      "Bash(rm -rf *)"
-    ]
-  },
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash .ai-assistance/scripts/bridge-init.sh 2>/dev/null || true"
-          },
-          {
-            "type": "command",
-            "command": "node .ai-assistance/scripts/token-session-start.js 2>/dev/null || true"
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node .ai-assistance/scripts/token-logger.js 2>/dev/null || true"
-          },
-          {
-            "type": "command",
-            "command": "bash scripts/auto-worker-scheduler.sh 2>/dev/null || true"
-          }
-        ]
-      }
-    ]
-  }
-}
+{
+  "permissions": {
+    "defaultMode": "auto",
+    "allowedTools": [
+      "Read"
+    ],
+    "permissionRules": [
+      {
+        "tool": "Write",
+        "pattern": "/**",
+        "action": "allow"
+      },
+      {
+        "tool": "StrReplace",
+        "pattern": "/**",
+        "action": "allow"
+      }
+    ],
+    "allow": [
+      "WebFetch(domain:anthropic.com)",
+      "WebFetch(domain:npmjs.com)",
+      "Write(.glaudeignore)",
+      "Update(.glaudeignore)",
+      "Bash(rm .ai-assistance/bridge/LOCK)",
+      "Read(.git/**)",
+      "Read(**/rubygems/**)",
+      "Write(*.md)",
+      "Edit(.ai-assistance/**)",
+      "Update(.ai-assistance/**)",
+      "Write(.ai-assistance/**)",
+      "Write(lib/**)",
+      "Write(spec/**)",
+      "Bash(git status)",
+      "Bash(git diff *)",
+      "Bash(git log *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "PowerShell(git status)",
+      "PowerShell(git diff *)",
+      "PowerShell(git log *)",
+      "PowerShell(git add *)",
+      "PowerShell(git commit *)",
+      "Bash(npm test)",
+      "Bash(npm run lint)",
+      "Bash(npm run build)",
+      "Bash(vitest *)",
+      "Bash(jest *)",
+      "PowerShell(npm test)",
+      "PowerShell(npm run lint)",
+      "PowerShell(npm run build)",
+      "Bash(black .)",
+      "Bash(pytest)",
+      "Bash(python -m unittest)",
+      "Bash(ruff check *)",
+      "Bash(bundle exec rspec *)",
+      "Bash(bundle exec rubocop *)",
+      "PowerShell(pytest)",
+      "PowerShell(python -m unittest)",
+      "PowerShell(ruff check *)",
+      "PowerShell(bundle exec rspec *)",
+      "PowerShell(bundle exec rubocop *)",
+      "Bash(node .ai-assistance/scripts/token-logger.js)",
+      "Bash(node .ai-assistance/scripts/token-session-start.js)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git status*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git log*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git diff*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git show*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git branch*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git fetch*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git checkout*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git switch*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git add*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git commit*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git rev-parse*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git merge-base*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git ls-remote*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git stash*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rspec*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rake test*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rubocop*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && bundle install*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git status*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git log*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git diff*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git show*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git branch*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git fetch*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git checkout*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git switch*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git add*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git commit*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git rev-parse*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git merge-base*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git ls-remote*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git stash*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle exec rake test*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle exec rubocop*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle install*)"
+    ],
+    "deny": [
+      "Read(*.env)",
+      "Read(./.env*)",
+      "Read(./secrets/**)",
+      "Bash(*cat *.env*)",
+      "Bash(*grep *.env*)",
+      "Bash(printenv*)",
+      "Bash(env)",
+      "Write(.git/*)",
+      "Edit(.git/*)",
+      "Bash(git push *)",
+      "Bash(rm -rf *)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .ai-assistance/scripts/bridge-init.sh 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "command": "node .ai-assistance/scripts/token-session-start.js 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "command": "bash .ai-assistance/scripts/bridge-inbox-check.sh 2>/dev/null || true"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .ai-assistance/scripts/token-logger.js 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "command": "bash scripts/auto-worker-scheduler.sh 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
+  }
+}

data/.gitlab-ci.yml

@@ -0,0 +1,45 @@
+# CI pipeline for ecoportal-api-graphql
+#
+# First automated check on merge requests. Runs the RSpec suite NON-BLOCKING
+# (allow_failure: true) — it reports pass/fail status without gating merges.
+# Rationale (2026-07-10): add visibility now; tighten to a blocking gate later
+# once the suite is reliably green on a clean runner.
+#
+# Live/AI specs (tagged :live) are excluded: they need ANTHROPIC_API_KEY + network.
+# They already self-skip when the key is absent, but ~live keeps the runner off
+# that path entirely.
+#
+# NOTE: graphlient resolves from a git fork (see Gemfile); ecoportal-api / -v2 come
+# from rubygems. If a required floor (e.g. ecoportal-api-v2 >= 3.3.3) is not yet
+# published, `bundle install` may fail on the runner — because this job is
+# allow_failure, that surfaces as a warning rather than blocking the MR.
+
+workflow:
+  rules:
+    # Merge-request pipelines.
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    # Avoid a duplicate branch pipeline when an MR is already open for the branch.
+    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
+      when: never
+    # Branch pipelines (incl. main/master pushes and feature branches without an MR).
+    - if: '$CI_COMMIT_BRANCH'
+
+stages:
+  - test
+
+rspec:
+  stage: test
+  image: ruby:3.2.2
+  allow_failure: true          # non-blocking: surface failures, do not gate merges
+  variables:
+    BUNDLE_PATH: vendor/bundle  # cache installed gems between pipelines
+  cache:
+    key: "ruby-322-bundle"
+    paths:
+      - vendor/bundle
+  before_script:
+    - ruby -v
+    - gem install bundler
+    - bundle install --jobs "$(nproc)" --retry 3
+  script:
+    - bundle exec rspec --tag ~live --format progress

data/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.13] - 2026-07-12
+
+Reliability: the GraphQL `HttpClient` now inherits the **same request-resilience
+contingencies as the REST clients** instead of a bespoke, divergent request path.
+**Backwards-compatible** — `execute` returns the same parsed body and raises the same
+error classes; only the transport path changed.
+
+### Fixed
+
+- **`Common::GraphQL::HttpClient#execute` no longer bypasses the inherited
+  `Common::Client` pipeline.** It previously issued the POST raw
+  (`base_request.post`) and handled the response itself, so GraphQL requests got
+  **none** of the resilience baked into `ecoportal-api`'s client over the years —
+  a single **HTTP 429** (Cloudflare edge rate-limit, error `1015`) aborted the whole
+  run. `execute` now routes through `instrument` → `with_retry { rate_throttling }`,
+  gaining for free:
+  - **rate-limit backoff** via `rate_throttle_client` (default
+    `ExponentialIncreaseProportionalDecrease`) — 429s are throttled + retried, not fatal.
+  - **retry on 5xx / connection errors** (`WithRetry`, 5 attempts) + empty-body guard.
+  - timeouts, and (deep-)logging / APM instrumentation.
+  - `handle_http_response` now consumes the wrapped `Common::Response` (single body
+    read — also removes a latent double-read hazard). The GraphQL-errors-in-a-200-body
+    path (`ResponseError`) is unchanged.
+  This is convergence on the shared base, so any future contingency added to
+  `Common::Client` now applies to GraphQL automatically.
+
 ## [1.3.12] - 2026-07-09
 
 Compat-layer correctness for register **field filters** + the native `SearchConf` field-filter DSL.

data/CLAUDE.md

@@ -11,6 +11,7 @@ docs/worklog.md                          ← current state, blockers, open quest
 .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

data/docs/self-docs/ARCHITECTURE.md

@@ -1,9 +1,9 @@
 ---
-schema_version: "1.0"
+schema_version: "1.1"
 repo: "ecoportal-api-graphql"
 doc: architecture
-last_generated: "2026-07-06"
-source_head: "2abd6fc"
+last_generated: "2026-07-09"
+source_head: "3f7b877"
 review_status: draft
 ---
 

data/docs/self-docs/CHANGES.jsonl

@@ -5,3 +5,8 @@
 {"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"}

data/docs/self-docs/COMPLIANCE.md

@@ -0,0 +1,79 @@
+---
+schema_version: "1.1"
+repo: "ecoportal-api-graphql"
+doc: compliance
+last_generated: "2026-07-09"
+source_head: "3f7b877"
+review_status: draft   # audit answers MUST come from 'reviewed' docs only -- a human sets this
+---
+
+# Compliance -- ecoportal-api-graphql
+
+**Purpose:** the audit / privacy / ISO-27001 surface for this project. It lets ROVO (over the EP Projects
+Register) answer compliance questions across the fleet. **Trust rule:** everything here separates
+EVIDENCE (a fact or link) from INTENT (planned); a reviewer must set `review_status: reviewed` before an
+answer built on this doc is used for audit or re-certification -- a confident answer on unreviewed content
+would mislead an auditor.
+
+> This document is DRAFT and was composed from the repo's own context (CLAUDE.md, the
+> `.ai-assistance/code/` specs, and the active project INTENT). Fields marked PLANNED or "human to
+> confirm" MUST be verified by the repo owner before any audit use.
+
+## ISO 27001
+
+This is a Ruby client library (a gem), not a hosted service; it holds no infrastructure of its own and
+introduces no independent ISO-27001 control surface. Its compliance posture is inherited from (a) the
+ecoPortal platform it authenticates against and (b) the consuming project's runtime environment. The
+control this repo DOES own is access-scoping of the automation that uses it.
+
+| Control area | Status (evidence / planned) | Evidence link |
+|---|---|---|
+| Access control / least privilege (A.9) | EVIDENCE: the template-automation work is required to run under a per-org SERVICE ACCOUNT scoped to templates/org-config only, with page records structurally out of scope by credential grant (ep-ai-standards `security/ai-service-account-scope`). | `.ai-assistance/projects/template-automatic-build-maintenance/INTENT.md`; `security/ai-service-account-scope` standard |
+| Change control (A.12.1) | EVIDENCE: no silent breaking changes -- public-interface changes are recorded in the active project's DECISIONS log and confirmed with the developer; semver + CHANGELOG. | `CLAUDE.md`; `CHANGELOG.md` |
+| Input validation (A.14.2) | EVIDENCE: `no_schema: true` disables build-time schema validation; the compensating control is a query validator now covering mutations. | `.ai-assistance/code/` (query validator); `ARCHITECTURE.md` |
+| Auditability of automated changes | PLANNED / human to confirm: template BUILD/diff emits an ordered `WorkflowCommand` batch and a pairing ledger; whether that stream is retained as an audit trail for re-certification needs owner confirmation. | `.ai-assistance/code/diff_pairing_engine.md` |
+
+## Data handled
+
+The gem can read and write live ecoPortal domain objects through the API. Data classification is by
+CAPABILITY (what the client can touch), then narrowed by the credential scope in use at runtime.
+
+| Data class (none/team/customer/PII) | What / where | Treatment + retention | Exposed? (how) |
+|---|---|---|---|
+| Customer data + PII | Page records read/written via the GraphQL API (can contain personal data). | In-memory only during a client session; the gem persists nothing itself. Retention lives in the ecoPortal platform, not here. | Not exposed by the gem beyond the authenticated API call. Read/write capability is gated by the runtime credential; template-automation deliberately excludes page records by service-account scope. |
+| Customer/org config (non-PII) | Templates, location structures, org configuration. | In-memory during a session; changes applied via `WorkflowCommand` batches. Retention in the platform. | Only via the authenticated API; this is the scope the template-automation service account is limited to. |
+| Team-only | `.env` credentials for live tests (`ANTHROPIC_API_KEY`, ecoPortal creds via dotenv). | Local `.env`, gitignored; loaded only for `--tag live` specs. | Not committed; not exposed. |
+
+## Third-party vendors in the data path
+
+| Vendor | What data | Disclosed to end users? | Notes |
+|---|---|---|---|
+| Anthropic (Claude) | Only for `--tag live` AI tests, gated by `ANTHROPIC_API_KEY`. No customer page data is sent as part of normal gem operation. | N/A -- development-time only, not a production data path. | Live AI tests are opt-in; the gem's runtime API client does not call any LLM. Human to confirm no PII appears in live-test fixtures. |
+
+No customer/PII data leaves the ecoPortal boundary through this gem in normal operation: it is a client
+for ecoPortal's own API, not a bridge to an external SaaS.
+
+## PII / data-leak controls
+
+- **Credential scope (primary control):** the template-automation service account is scoped to
+  templates/org-config only, so page records (customer data + PII) are out of reach by GRANT, not by
+  instruction (ep-ai-standards `security/ai-service-account-scope`). This is the load-bearing leak
+  control.
+- **`org_id` scoping:** every client session is bound to a single org context; cross-org reads require
+  distinct credentials.
+- **No local persistence:** the gem holds data in memory for the session and writes nothing to disk;
+  there is no cache or log of customer records to leak.
+- **`.env` gitignored:** credentials for live tests never enter version control.
+- **Query validator:** compensates for `no_schema: true` by catching malformed queries/mutations before
+  they hit the live API.
+
+## AI-generated content
+
+- Externally-exposed AI content: **no.** The gem produces no customer-facing or publicly-exposed AI
+  content. AI assistance is confined to development (code generation, template-automation planning) and
+  `--tag live` AI tests; its output is reviewed code and internal artefacts, not exposed to end users.
+- Marked as AI-generated: **N/A** for external content. Internally, AI-assisted commits follow the
+  developer-only authorship convention (no `Co-Authored-By` unless requested), and Gemini responses must
+  be verified against actual code before applying.
+- Review process: standard MR review; public-interface changes additionally logged in the active
+  project's DECISIONS log and confirmed with the developer.

data/docs/self-docs/CONVENTIONS.md

@@ -1,9 +1,9 @@
 ---
-schema_version: "1.0"
+schema_version: "1.1"
 repo: "ecoportal-api-graphql"
 doc: conventions
-last_generated: "2026-07-06"
-source_head: "2abd6fc"
+last_generated: "2026-07-09"
+source_head: "3f7b877"
 review_status: draft
 ---
 

data/docs/self-docs/INTEGRATIONS.md

@@ -1,33 +1,35 @@
 ---
-schema_version: "1.0"
+schema_version: "1.1"
 repo: "ecoportal-api-graphql"
 doc: integrations
-last_generated: "2026-07-06"
-source_head: "2abd6fc"
+last_generated: "2026-07-09"
+source_head: "3f7b877"
 review_status: draft
 ---
 
 # Integrations -- ecoportal-api-graphql
 
 **Purpose:** the ties this project has to other systems and repos. This is the section the central
-hub uses to trace inter-project dependencies and surface reuse (ADR-015 Section 5).
+hub uses to trace inter-project dependencies and surface reuse (ADR-015 Section 5). It records, per
+tie, the DATA that flows and the PERMISSIONS required -- feeding the compliance (vendor/PII) and the
+cross-project-permissions questions. Detailed data-handling lives in `COMPLIANCE.md`.
 
 ## External services
 
-| Service | Purpose | Notes |
-|---|---|---|
-| ecoPortal GraphQL API | The API this gem is a client for -- reads/writes pages, templates, location structures, contractor entities, actions, organizations. | Auth via `Common::GraphQL::AuthService` (OAuth), scoped by `org_id`; hosted per environment (e.g. live.ecoportal.com). `no_schema: true` -- no introspection. |
-| ecoPortal REST API (v2) | Underlying REST infrastructure the GraphQL layer builds on and stays compatible with via the `Compat` layer. | Provided by the upstream `ecoportal-api-v2` gem. |
+| Service | Purpose | Data sent (class + PII?) | Auth / permissions (scopes) |
+|---|---|---|---|
+| ecoPortal GraphQL API | The API this gem is a client for -- reads/writes pages, templates, location structures, contractor entities, actions, organizations. | Customer data + PII: page records can contain personal data. Also template/org-config data (non-PII). The gem is a full-access client by capability; the active template-automation work restricts itself to templates/org-config only by SERVICE-ACCOUNT grant. | OAuth via `Common::GraphQL::AuthService`, scoped by `org_id`; per-environment host (e.g. live.ecoportal.com). `no_schema: true` (no introspection). Credential scope is the load-bearing control -- see COMPLIANCE.md. |
+| ecoPortal REST API (v2) | Underlying REST infrastructure the GraphQL layer builds on and stays compatible with via the `Compat` layer. | Same classes as above (indirect, via `ecoportal-api-v2`). | Same OAuth / org-scoped runtime credentials; provided through the upstream `ecoportal-api-v2` gem. |
 
 ## Upstream dependencies (repos we depend on)
 
-| Repo / package | What we use it for |
-|---|---|
-| `ecoportal-api` | REST API base: auth, org context, base models, and the `Ecoportal::API::Common` namespace this gem extends. Team-managed. |
-| `ecoportal-api-v2` | REST API v2 layer (Page, Register, etc.); required by the entry point. Team-managed. Being retired over time. |
-| `graphlient` | Friendly GraphQL DSL/client wrapper; `Common::GraphQL::Client` inherits from `Graphlient::Client`. Active fork owned by the team (upstream: `ashkan18/graphlient`). |
-| `graphql-client` | Low-level GraphQL HTTP + parsing, pulled in transitively via graphlient. Fork for upstream contribution only (upstream: `github-community-projects/graphql-client`); not team-maintained. |
-| `graphql` (graphql-ruby) | Schema definition/execution engine (`rmosolgo/graphql-ruby`); external, read-only reference. Used server-side by ecoPortal; client-side usage here is indirect. |
+| Repo / package | What we use it for | Permission/scope required (if any) |
+|---|---|---|
+| `ecoportal-api` | REST API base: auth, org context, base models, and the `Ecoportal::API::Common` namespace this gem extends. Team-managed. | None beyond the runtime ecoPortal API credentials (email/pass/org_id/host) passed at instantiation. |
+| `ecoportal-api-v2` | REST API v2 layer (Page, Register, etc.); required by the entry point. Team-managed. Being retired over time. | Same runtime ecoPortal API credentials. |
+| `graphlient` | Friendly GraphQL DSL/client wrapper; `Common::GraphQL::Client` inherits from `Graphlient::Client`. Active fork owned by the team (upstream: `ashkan18/graphlient`). | None (library dependency). |
+| `graphql-client` | Low-level GraphQL HTTP + parsing, pulled in transitively via graphlient. Fork for upstream contribution only (upstream: `github-community-projects/graphql-client`); not team-maintained. | None (library dependency). |
+| `graphql` (graphql-ruby) | Schema definition/execution engine (`rmosolgo/graphql-ruby`); external, read-only reference. Used server-side by ecoPortal; client-side usage here is indirect. | None (library dependency). |
 
 ## Downstream consumers (who depends on us)
 

data/docs/self-docs/OPERATIONS.md

@@ -0,0 +1,76 @@
+---
+schema_version: "1.1"
+repo: "ecoportal-api-graphql"
+doc: operations
+last_generated: "2026-07-09"
+source_head: "3f7b877"
+review_status: draft
+---
+
+# Operations -- ecoportal-api-graphql
+
+**Purpose:** the infrastructure / exposure / value surface for DevOps and Engineering. It lets ROVO answer
+"what infrastructure is involved, is it behind Cloudflare, what governs its flows, and is it worth it?"
+Same trust rule as COMPLIANCE.md: separate EVIDENCE from INTENT; audit answers use `reviewed` docs only.
+
+> This document is DRAFT and composed from the repo's own context. It is a client LIBRARY (a gem): it has
+> no infrastructure or public exposure of its own. Value/KPI figures below are unmeasured placeholders for
+> the repo owner to fill; do not cite them as measured until reviewed.
+
+## Infrastructure inventory
+
+This project is a Ruby gem distributed as source/package -- it runs INSIDE whatever process requires it
+(e.g. an `eco-helpers` integration script). It owns no compute, storage, or queue of its own.
+
+| Component | Type (compute/store/queue/...) | Where hosted | Notes |
+|---|---|---|---|
+| The gem itself | library (no runtime infra) | Consumer's process / developer machine / CI | No servers, no data stores; loaded via Bundler into a host process. |
+| ecoPortal GraphQL API | external service (dependency) | ecoPortal platform, per-environment host (e.g. live.ecoportal.com) | The gem is a CLIENT of this; the API's infrastructure is owned by the platform, not this repo. |
+| RubyGems / Bundler | package distribution | RubyGems (or team gem source) | Distribution channel for the gem. |
+
+## Public exposure
+
+**Nothing in this repo is publicly exposed.** It is a client library with no listening endpoint, no
+domain, and no inbound surface. It makes OUTBOUND authenticated calls to the ecoPortal GraphQL API; the
+public-exposure and Cloudflare/WAF posture of that API belongs to the ecoPortal platform's own OPERATIONS
+doc, not to this gem.
+
+| Public domain / endpoint | Behind Cloudflare? | Security rules governing the flow |
+|---|---|---|
+| (none -- library, no inbound surface) | N/A | Outbound only: OAuth-authenticated, `org_id`-scoped calls to the ecoPortal GraphQL API over HTTPS. |
+
+## DevOps audit runbook
+
+How to check/verify this project autonomously:
+
+- **Build / install:** `bundle install`; gem spec is `ecoportal-api-graphql.gemspec`; version constant
+  `Ecoportal::API::GRAPQL_VERSION`.
+- **Tests:** `bundle exec rspec` for the unit suite; `bundle exec rspec --tag live` for live-API/AI tests
+  (requires `.env` with `ANTHROPIC_API_KEY` and ecoPortal credentials, loaded via dotenv).
+- **Lint:** `bundle exec rubocop <file>` -- rubocop compliance is required for all generated Ruby
+  (config in `.rubocop.yml`).
+- **CI:** no CI config file was detected at the repo root by the scanner (`ci_files: []`). Human to
+  confirm whether CI runs elsewhere (e.g. a GitLab CI defined outside the root) or is absent.
+- **Version / release check:** `CHANGELOG.md` is authoritative; releases follow
+  `chore(release): vX.Y.Z`. Recent releases raised the `ecoportal-api-v2` floor to fix version-drift
+  crashes -- verify the dependency floors in the gemspec match the CHANGELOG.
+- **Deeper docs:** `.ai-assistance/code/` (code-specs, dependency map, diff/build engine, schema
+  analysis) is the detailed runbook for engineers; `.ai-assistance/code/ecoPortal_architecture/` is the
+  verified platform knowledge base.
+
+## Value & KPIs
+
+No usage KPIs are instrumented in this repo today. The value narrative below is qualitative /
+estimated; the repo owner should replace estimates with measured figures (or a dashboard link) before
+these are treated as evidence.
+
+| Metric | Value (measured/estimated) | Source / dashboard |
+|---|---|---|
+| Templates targeted for programmatic build/maintenance | ~300+ (estimated, project scope) | `.ai-assistance/projects/template-automatic-build-maintenance/INTENT.md` |
+| Hours saved / delivery-speed gain | Not measured | -- (owner to instrument) |
+| Active monitoring | None in-repo; staleness of these self-docs is detectable via `source_head` vs git head | `self-docs-index.json` |
+| Cost-vs-return | Not measured | -- (owner to instrument) |
+
+**Coverage-on-neglect:** these self-docs carry a `source_head` and a per-doc `content_hash` in
+`self-docs-index.json`, so the hub and `project-review` can flag them stale rather than silently trusting
+them.