ecoportal-api-graphql 1.3.12 → 1.3.14

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/.gitignore

@@ -1,37 +1,37 @@
-# it's a gem, ignore the lockfile
-Gemfile.lock
-
-.env
-.ai-assistance/local_paths.md
-# build artifacts
-*.gem
-/.bundle/
-/vendor/bundle
-/spec/reports/
-/tmp/
-/pkg/
-
-# docs
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-
-# rspec failure tracking
-.rspec_status
-scratch.rb
-tests/.byebug_history
-
-.solargraph.yml
-
-# AI assistance — local-only files
-.ai-assistance/code/dep-graph.json
-.ai-assistance/tmp/
-.ai-assistance/local/
-.ai-assistance/bridge/inbox/*.draft.md
-.ai-assistance/bridge/inbox/*.local.md
-.ai-assistance/bridge/LOCK
-.ai-assistance/bridge/STATUS
-.ai-assistance/capabilities/.env
-.ai-assistance/scripts/*.env
-.ai-assistance/scripts/node_modules/
+# it's a gem, ignore the lockfile
+Gemfile.lock
+
+.env
+.ai-assistance/local_paths.md
+# build artifacts
+*.gem
+/.bundle/
+/vendor/bundle
+/spec/reports/
+/tmp/
+/pkg/
+
+# docs
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+
+# rspec failure tracking
+.rspec_status
+scratch.rb
+tests/.byebug_history
+
+.solargraph.yml
+
+# AI assistance — local-only files
+.ai-assistance/code/dep-graph.json
+.ai-assistance/tmp/
+.ai-assistance/local/
+.ai-assistance/bridge/inbox/*.draft.md
+.ai-assistance/bridge/inbox/*.local.md
+.ai-assistance/bridge/LOCK
+.ai-assistance/bridge/STATUS
+.ai-assistance/capabilities/.env
+.ai-assistance/scripts/*.env
+.ai-assistance/scripts/node_modules/

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,49 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.14] - 2026-07-16
+
+Re-issue of the **1.3.13 HttpClient resilience fix** under a fresh version. The `1.3.13`
+artifact published to the gem server (2026-07-11) could not be relied upon to contain the
+fix below — RubyGems versions are immutable and cannot be re-pushed, so the fix ships here
+as `1.3.14`. Functionally identical to the *intended* `1.3.13` (this is `1.3.12` + the
+resilience fix, nothing else). **Backwards-compatible.**
+
+Consumers that need the 429/1015 resilience (e.g. bulk `cans-upsert` live runs) must floor
+`ecoportal-api-graphql >= 1.3.14` — a `>= 1.3.13` floor is not sufficient.
+
+### Fixed
+
+- Same fix as documented under `[1.3.13]` below: `Common::GraphQL::HttpClient#execute` routes
+  through the inherited `instrument → with_retry { rate_throttling }` pipeline, so a single
+  HTTP 429 (Cloudflare edge rate-limit `1015`) no longer aborts the run.
+
+## [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
 ---