ecoportal-api-graphql 1.3.14 → 1.3.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cbeb13326afff8c35946fd492b9bd6cd050e28819497b643bb4ea6c4b41caca
-  data.tar.gz: ad4660f8fa032e08d0c5f09b199f280d8b42a4e234144ad2fab4041b154fe835
+  metadata.gz: 43397010b997d3427eda7b91683044467b679ad72fdea66e910ddf1f8eda6828
+  data.tar.gz: 2d1540686b0e07fbf06f56fb2ff922302fee08a35a9370b18794401c66ec50da
 SHA512:
-  metadata.gz: 7337308796e0a6800e9dd678d8b9317978d4cf13f6514b2ba95e5d6eaac95b9833be786ca573b7e59613660077aaa78c808a62c4bbef0c9e2f1a08e0c752e857
-  data.tar.gz: 602edaca4d582eeb876549bba42735fc17fc07d832de713fd3ba84234cc2a876aea876beb51c4fb54eef3faf5a334b889443d922d9c6debe196545389b2715e6
+  metadata.gz: 7623eede099dbce829d5b1bba47f775926c5dfdf5e56f1a407514bb68360af8b25c0a83375983b09e4767a52dec947a313859dc2c8cff61f27476a0d703af2ff
+  data.tar.gz: a42d2dfec504502bf95a3bbe614c39d3f64499f2996f242d8c48afb325554f542332b9ec4110fb58e61b07ce345a63d30e6193990980b0f68860bbe17baf8cf7

data/.ai-assistance/projects/TODO.md

@@ -1,118 +1,170 @@
-# Project TODO
-
-## Pending
-
-- [ ] **⏰ CI: query-validation step (DUE by 2026-07-17 — within 2 weeks of 2026-07-03)** — wire
-  `tests/validate_queries.rb` into CI so the whole class of GraphQL selection bugs fails *before*
-  release, not in a client runner. **Use a FRESHLY-introspected schema** (do NOT commit the 6.3MB
-  dump — it goes stale); fail the build only on the two structural classes ("field must have
-  selections" / "selections can't be made on scalars"). Motivated by the 2026-07-03 v1.3.10 hotfix
-  (LocationStructure `updatedAt`/`createdAt`) — those queries had no spec and first broke in prod.
-  Also: fix the 3 flagged union findings — **TRIAGED 2026-07-03: all THREE are REAL bugs** (verified
-  by rendering the assembled docs + re-validating fixes; not harness/dump artifacts). Each selects
-  fields directly on a union (invalid GraphQL) — wrap in the members' shared interface:
-    - `Query::PageWithForces` (page_with_forces.rb:33-35): bare `forces` on `PageUnion` →
-      `... on BasePageInterface { forces { ...ForceFields } }`. ALSO `fragment ForceFields`
-      (fragment/force.rb:15,20) selects `id` on `DataFieldBinding`/`SectionBinding` which have NO `id`
-      (only name/reference/referenceId) → drop `id` (or use `referenceId`).
-    - `Query::PagesWorkflowCommands` (pages_workflow_commands.rb:33-37): bare `workflow` on `PageUnion`
-      → `... on BasePageInterface { workflow { ... } }`. (The "unused variable" errors were an
-      artifact — a validator cascade from the union error; no action on the vars.)
-    - `Query::RegisterPresetViews` (register_preset_views.rb:71): bare `{id key name weight}` on
-      `FieldConfigurationUnion` → `... on FieldConfigurationInterface { id key name weight }`.
-  None of these 3 queries have specs — add render/validation specs alongside the fixes. These are
-  latent (not the users-sync incident); PageWithForces is WIP. Ship as a follow-up patch (1.3.11).
-
-- [x] **Builder::Register** — `createRegister`, `updateRegister`, `destroyRegister` mutations.
-  `Base::Register`, `Model::Register`, `Input::Register::Create/Update`, `Payload::Register`.
-  `Builder::Register` with `create`, `update`, `destroy`, and `preset_view` sub-builder.
-  `GraphQL#register` exposed (singular, distinct from `#registers` compat layer).
-  *Done 2026-06-08*
-
-- [ ] **Dashboards / Charts** — `Register.defaultDashboardId` and dashboard queries/mutations
-  are not yet wrapped. Backend has dashboard configuration tied to registers and organisations.
-  Scope: `Base::Dashboard` model, `Query::Dashboard(s)`, `Builder::Register#set_default_dashboard`.
-  Priority: medium — needed when scripts need to manage register dashboard configs.
-
-- [x] **AI field mutations** — `generateAiSummary`, `generateSmartFill`,
-  `submitAiSummaryFeedback`, `submitSmartFillFeedback` fully wrapped.
-  `Mutation::AiSummary::Generate/SubmitFeedback`, `Mutation::SmartFill::Generate/SubmitFeedback`,
-  `Payload::AiSummaryGenerate`, `Payload::OkPayload`, `Base::AiSummaryVersion`.
-  `Builder::Page` wired: `generate_ai_summary`, `submit_ai_summary_feedback`,
-  `generate_smart_fill`, `submit_smart_fill_feedback`.
-  *Done 2026-06-08*
-
-- [ ] **AI prompt review workflow** — AiSummary and SmartFill fields store an `instructions`
-  field (the AI prompt, template-configured by humans). No audit/review workflow exists.
-  The gem can read `field.instructions` on AiSummary/SmartFill instances already.
-  What's needed: a way to scan pages/templates for these instructions and surface them
-  for review. Possibly: `Query::PagesWithAiFields` + a review report script.
-  See `.ai-assistance/code/ecoPortal_architecture/13_ai_infrastructure.md` for context.
-  Priority: low/design — the need is real but the right interface is TBD.
-
-- [x] **eP Meta AI scaffolding project** — Standalone template repo at
-  `C:\ruby_scripts\git\ecoPortal_ai_standards`. Bridge protocol, all scripts
-  (lock-acquire, task-read, task-create, setup-mcps, etc.), all skills, conventions,
-  integrations, capabilities registry, CLAUDE.md template ({{PLACEHOLDER}} vars),
-  ONBOARDING.md (15-min setup guide), `init-project.ts` bootstrap script.
-  Push to GitLab to share: `git@gitlab.ecoportal.co.nz:oscar/ecoPortal_ai_standards.git`
-  *Done 2026-06-08*
-
-- [ ] **Commit unstaged changes** — Large set of modified files on `ai_dev_process` branch
-  not yet staged or committed. Review and commit once session is fully restored.
-
-## Bridge improvements (from Gemini review 2026-06-04)
-
-- [x] **Security: Code must prompt before executing bridge-requested shell commands** —
-  Rule added to `.ai-assistance/bridge/CLAUDE.md` "Running Code non-interactively" section.
-  Code must surface any shell command to the user before running it, even in
-  skip-permissions mode. User denial → mark task FAILED.
-  *Done 2026-06-08*
-
-- [x] **Atomic LOCK acquisition** — `scripts/lock-acquire.sh` implemented.
-  Uses temp-file + hard-link (atomic on POSIX/NTFS); falls back to bash `noclobber`.
-  Reports held-by agent/intent on contention. Auto-detects stale locks by mtime.
-  `bridge/CLAUDE.md` updated to reference it as the preferred acquisition method.
-  *Done 2026-06-08*
-
-- [x] **Stale IN_PROGRESS recovery** — `bridge-init.sh` updated: scans for IN_PROGRESS
-  tasks older than 1 hour (via `stat` mtime), reports them in `stale_tasks` + `stale`
-  count in STATUS JSON. `bridge/CLAUDE.md` updated with Code's required response:
-  report to user, ask to reset to PENDING or mark FAILED.
-  *Done 2026-06-08*
-
-- [x] **`task-read.ts` script** — `scripts/task-read.ts` implemented.
-  Parses all sections (title, status, created, from, to, context, request, expected,
-  result, notes) from inbox/outbox/archive files. Searches all bridge dirs automatically.
-  Output: structured JSON. Saves ~200 tokens per task read vs raw Markdown.
-  *Done 2026-06-08*
-
-- [x] **Archive pruning convention** — Documented in `bridge/CLAUDE.md` "Archive pruning"
-  section: keep last 90 days or last 50 task pairs; git history is the audit trail;
-  prune manually when folder gets unwieldy.
-  *Done 2026-06-08*
-
-## File upload
-
-- [ ] **File upload** — Support uploading files to attach to `File` and `ImageGallery`
-  data fields (and potentially Action file attachments at a later stage).
-  This is distinct from the `attach` operation (which links existing resources to
-  a target model). Upload requires direct multipart/form-data HTTP to a separate
-  endpoint before the GraphQL mutation references the resulting file ID.
-  Scope:
-  - Identify the upload endpoint and auth pattern (likely REST, not GraphQL)
-  - Create `HttpClient#upload(file_path:, ...)` or similar
-  - Create `Input::FileAttachment` to carry the resulting file container ID into mutations
-  - Wire into data field update inputs (Phase E concern for fields, sooner for Actions)
-  Priority: Medium — needed before data field updates can be fully functional.
-  Note: Actions file attachment may be needed sooner — track separately if it becomes urgent.
-
-## Completed
-
-- [x] **Gemini design review of bridge architecture** — Done 2026-06-04. Response in
-  `.ai-assistance/bridge/context/gemini-review-response.md`.
-- [x] **Regenerate GitLab PAT** — New token generated, April 2027 expiry, rotation enabled.
-  Updated in `.env` and documented in `integrations/gitlab-mcp.md`.
-- [x] **Rename `.claude/` to `.ai-assistance/`** — Done 2026-06-04. All references updated
-  across scripts, CLAUDE.md, gitignore, and capabilities docs.
-- [x] **MCP setup script** — `setup-mcps.ts` + tests written. Teammates run once per machine.
+# Project TODO
+
+## Pending
+
+- [x] **CI: query-validation step** (was ⏰ DUE 2026-07-17) — `tests/validate_queries.rb` is wired
+  into CI as the **blocking** `validate-queries` job. *Done 2026-07-29.*
+  - Fresh introspection at pipeline time via the new **`tests/dump_schema.rb`** (env-driven:
+    `SERVER` / `ORGANIZATION_ID` / `USER_EMAIL` / `USER_PASS`; `SERVER` is required on purpose —
+    the gem's default host is PROD). No dump is committed: they go stale, and a stale schema both
+    invents noise and hides real findings. `validate_queries.rb` with no argument now resolves the
+    newest dump in the (gitignored) `.ai-assistance/tmp/`.
+  - **Third failing class added: "can't be made directly on unions."** This is the gap that made the
+    original gate insufficient: the 3 union findings landed in the advisory OTHER bucket and needed
+    a human to spot them. Selecting on a union without a type condition is invalid under any schema,
+    so it is safe to fail on — unlike "field doesn't exist", which is staleness-shaped.
+  - **All 3 union findings now fixed** (`RegisterPresetViews` on 2026-07-26 via `dc8efc7`;
+    `PageWithForces` + `PagesWorkflowCommands` on 2026-07-29 via `... on BasePageInterface`), plus
+    the companion `fragment ForceFields` bug (`id` on a binding — `BindingInterface` has only
+    `name`/`referenceId`, verified in backend `types/forces/binding_interface.rb`).
+  - **Specs added** (render + semantic, offline, no creds): `page_with_forces_spec.rb`,
+    `pages_workflow_commands_spec.rb` (11 examples; verified they fail against the pre-fix code).
+    Each validates the rendered doc against a minimal SDL carrying the real union shape.
+  - ⚠ **Not yet run in CI:** the job is inert until the four `EP_CI_*` CI/CD variables are set
+    (service account with read access on a NON-production org — introspection needs no write
+    scope). `dump_schema.rb` has therefore never talked to a live endpoint. Its first real run is
+    the acceptance test for this item.
+
+- [ ] **Force binding read/write asymmetry (found 2026-07-29 while fixing `ForceFields`)** —
+  `WorkflowEditBindingInput` and `removeBinding` require a binding `id`, but the read side
+  (`Types::Forces::BindingInterface`) exposes only `name` / `referenceId` / `reference`. So
+  `Base::Force::Binding#id` (`passkey :id`) can never be populated, and
+  `Force::BindingCollection#delete!(binding_object)` sends `removeBinding: { id: nil }`.
+  Not fixable client-side — needs `id` on the binding types (backend), or the write commands need
+  to key on `referenceId` + `name`. Belongs with the shape-asymmetry review project. No regression
+  from the fragment fix: the query that would have fed it never succeeded.
+  Priority: medium — silently broken write path.
+
+- [x] **Builder::Register** — `createRegister`, `updateRegister`, `destroyRegister` mutations.
+  `Base::Register`, `Model::Register`, `Input::Register::Create/Update`, `Payload::Register`.
+  `Builder::Register` with `create`, `update`, `destroy`, and `preset_view` sub-builder.
+  `GraphQL#register` exposed (singular, distinct from `#registers` compat layer).
+  *Done 2026-06-08*
+
+- [ ] **Dashboards / Charts** — `Register.defaultDashboardId` and dashboard queries/mutations
+  are not yet wrapped. Backend has dashboard configuration tied to registers and organisations.
+  Scope: `Base::Dashboard` model, `Query::Dashboard(s)`, `Builder::Register#set_default_dashboard`.
+  Priority: medium — needed when scripts need to manage register dashboard configs.
+
+- [x] **AI field mutations** — `generateAiSummary`, `generateSmartFill`,
+  `submitAiSummaryFeedback`, `submitSmartFillFeedback` fully wrapped.
+  `Mutation::AiSummary::Generate/SubmitFeedback`, `Mutation::SmartFill::Generate/SubmitFeedback`,
+  `Payload::AiSummaryGenerate`, `Payload::OkPayload`, `Base::AiSummaryVersion`.
+  `Builder::Page` wired: `generate_ai_summary`, `submit_ai_summary_feedback`,
+  `generate_smart_fill`, `submit_smart_fill_feedback`.
+  *Done 2026-06-08*
+
+- [ ] **AI prompt review workflow** — AiSummary and SmartFill fields store an `instructions`
+  field (the AI prompt, template-configured by humans). No audit/review workflow exists.
+  The gem can read `field.instructions` on AiSummary/SmartFill instances already.
+  What's needed: a way to scan pages/templates for these instructions and surface them
+  for review. Possibly: `Query::PagesWithAiFields` + a review report script.
+  See `.ai-assistance/code/ecoPortal_architecture/13_ai_infrastructure.md` for context.
+  Priority: low/design — the need is real but the right interface is TBD.
+
+- [x] **eP Meta AI scaffolding project** — Standalone template repo at
+  `C:\ruby_scripts\git\ecoPortal_ai_standards`. Bridge protocol, all scripts
+  (lock-acquire, task-read, task-create, setup-mcps, etc.), all skills, conventions,
+  integrations, capabilities registry, CLAUDE.md template ({{PLACEHOLDER}} vars),
+  ONBOARDING.md (15-min setup guide), `init-project.ts` bootstrap script.
+  Push to GitLab to share: `git@gitlab.ecoportal.co.nz:oscar/ecoPortal_ai_standards.git`
+  *Done 2026-06-08*
+
+- [ ] **Commit unstaged changes** — Large set of modified files on `ai_dev_process` branch
+  not yet staged or committed. Review and commit once session is fully restored.
+
+## Bridge improvements (from Gemini review 2026-06-04)
+
+- [x] **Security: Code must prompt before executing bridge-requested shell commands** —
+  Rule added to `.ai-assistance/bridge/CLAUDE.md` "Running Code non-interactively" section.
+  Code must surface any shell command to the user before running it, even in
+  skip-permissions mode. User denial → mark task FAILED.
+  *Done 2026-06-08*
+
+- [x] **Atomic LOCK acquisition** — `scripts/lock-acquire.sh` implemented.
+  Uses temp-file + hard-link (atomic on POSIX/NTFS); falls back to bash `noclobber`.
+  Reports held-by agent/intent on contention. Auto-detects stale locks by mtime.
+  `bridge/CLAUDE.md` updated to reference it as the preferred acquisition method.
+  *Done 2026-06-08*
+
+- [x] **Stale IN_PROGRESS recovery** — `bridge-init.sh` updated: scans for IN_PROGRESS
+  tasks older than 1 hour (via `stat` mtime), reports them in `stale_tasks` + `stale`
+  count in STATUS JSON. `bridge/CLAUDE.md` updated with Code's required response:
+  report to user, ask to reset to PENDING or mark FAILED.
+  *Done 2026-06-08*
+
+- [x] **`task-read.ts` script** — `scripts/task-read.ts` implemented.
+  Parses all sections (title, status, created, from, to, context, request, expected,
+  result, notes) from inbox/outbox/archive files. Searches all bridge dirs automatically.
+  Output: structured JSON. Saves ~200 tokens per task read vs raw Markdown.
+  *Done 2026-06-08*
+
+- [x] **Archive pruning convention** — Documented in `bridge/CLAUDE.md` "Archive pruning"
+  section: keep last 90 days or last 50 task pairs; git history is the audit trail;
+  prune manually when folder gets unwieldy.
+  *Done 2026-06-08*
+
+## File upload
+
+- [x] **BUG — `FileUpload::Client` auth mechanism (confirmed live 2026-07-26, fixed same day).**
+  Implemented in commit `9f769cc` (2026-06-08) as a port of `ecoportal-api-v2`'s
+  `S3::Data`/`S3::Upload`/`S3::Files` — shipped in CHANGELOG but with **zero test coverage
+  ever** (no specs, no VCR, no manual test script). Live-verified via `training` repo →
+  `mini/automated-tests/tests/pages/file_upload_test.rb`: `Query::FileUploadSignature`
+  (step 1, GraphQL presign) succeeds, but the REST registration step
+  (`POST /api/v2/<org_id>/s3/files`, step 3) **404s**.
+  **Root cause:** `ecoportal-api-v2`'s REST S3 endpoints authenticate via
+  `X-ECOPORTAL-API-KEY` header (`Common::Content::Client#base_request`), but the ported
+  `FileUpload::Client` sends `Authorization: Bearer <oauth_token>` instead (the same token
+  used for GraphQL) — wrong auth mechanism for those specific REST endpoints.
+  **Fix (branch `fix/file-upload-api-key-auth`):** added `api_key:` to
+  `Ecoportal::API::GraphQL.new` (threaded to `HttpClient`, independent of the GraphQL
+  endpoint's own email/pass OAuth bearer token), exposed `HttpClient#api_key` publicly, and
+  changed `FileUpload::Client#upload_get`/`#upload_post` to send `X-ECOPORTAL-API-KEY`
+  instead of `Authorization: Bearer`, raising a clear error if no `api_key:` was configured.
+  18 new specs added (`graphql_spec.rb`, `http_client_spec.rb`, `file_upload_signature_spec.rb`,
+  `file_upload/client_spec.rb` — full 4-step `#upload` orchestration + auth-header assertions).
+  **Still NOT live-verified** — no credentials were available in the environment this was
+  fixed in; run `training/mini/automated-tests -only pages/file_upload` (with a real
+  `api_key:` wired into that harness's `graphql` session helper — check where it builds
+  `Ecoportal::API::GraphQL.new` and add `api_key:` there too) before trusting this in
+  production.
+  **Still open / NOT covered by this fix:**
+  - The S3 key path is built by string concatenation (`upload_prefix + filename`) vs v2's
+    slash-joined `"#{user_tmpdir}/#{file_basename}"`.
+  - The multipart POST hardcodes `x-amz-server-side-encryption: AES256` instead of reading
+    the value v2 gets from the presigned credentials response.
+  - The hand-rolled multipart builder should probably be replaced with `Net::HTTP#set_form`
+    (what v2 uses, more robust than hand-built boundaries).
+  - No mutation exists anywhere in this gem to set `FileContainer#tags` — confirm whether
+    that's even possible via GraphQL before promising it in any customer-facing demo.
+  - **Threading/multi-file:** `ecoportal-api-v2` has a real, previously-uncovered threaded
+    batch-upload path (`S3::Files::BatchUpload` + `Concerns::Threadable`, `threads:` param,
+    per-file error isolation) — now specced (`ecoportal-api-v2` branch, 3 new specs).
+    Assessment: do NOT port this to `FileUpload::Client` yet — it only handles one file per
+    call today, and Oscar has already explicitly deferred a bulk/multi-file DX shortcut here
+    in favor of a future backend async batch-upload feature (out of scope for this gem).
+    Revisit only once the auth fix is live-verified as a working single-file baseline AND
+    bulk latency is confirmed to actually matter in practice.
+  Priority: was **High** (blocked `ep-api-collections`' Files Upload group and any real
+  usage of `#file_upload`) — auth mechanism now fixed pending live verification; the Files
+  Upload collection group should stay un-built until that live verification passes.
+
+- [ ] **File upload — data field wiring (original scope, still valid once the bug above is fixed)**
+  Support uploading files to attach to `File` and `ImageGallery` data fields (and
+  potentially Action file attachments at a later stage). Distinct from `attach` (which
+  links existing resources). Scope:
+  - Create `Input::FileAttachment` to carry the resulting file container ID into mutations
+  - Wire into data field update inputs (Phase E concern for fields, sooner for Actions)
+  Priority: Medium — needed before data field updates can be fully functional.
+  Note: Actions file attachment may be needed sooner — track separately if it becomes urgent.
+
+## Completed
+
+- [x] **Gemini design review of bridge architecture** — Done 2026-06-04. Response in
+  `.ai-assistance/bridge/context/gemini-review-response.md`.
+- [x] **Regenerate GitLab PAT** — New token generated, April 2027 expiry, rotation enabled.
+  Updated in `.env` and documented in `integrations/gitlab-mcp.md`.
+- [x] **Rename `.claude/` to `.ai-assistance/`** — Done 2026-06-04. All references updated
+  across scripts, CLAUDE.md, gitignore, and capabilities docs.
+- [x] **MCP setup script** — `setup-mcps.ts` + tests written. Teammates run once per machine.

data/.ai-assistance/skills/ai-instructions/SKILL.md

@@ -1,48 +1,48 @@
-# SKILL: AI Instructions Generator, Reviewer & Updater
-
-**Purpose:** Keep CLAUDE.md, skill files, and conventions accurate, tidy, and placed correctly as the project evolves.
-
----
-
-## When to Use
-
-- A developer makes an observation that reveals a gap, mistake, or new convention.
-- A new pattern emerges in the code that future AI agents should know about.
-- A skill needs to be created, updated, or split.
-- CLAUDE.md needs to reflect a structural change to the repo.
-
----
-
-## Decision: Practice/Convention vs. CLAUDE.md Instruction vs. Skill
-
-When an observation is made, scope it:
-
-| Type | Where it goes |
-|------|--------------|
-| One-off note or context | Inline comment in the relevant `.ai-assistance/code/*.md` doc |
-| Convention (how we do things here) | `CLAUDE.md` → Conventions section |
-| Always-do behaviour for AI agents | `CLAUDE.md` → Before Starting Any Task, or a new section |
-| Reusable, invocable capability | New or updated `SKILL.md` in `.ai-assistance/skills/<skill-name>/` |
-
----
-
-## File Placement Rules
-
-- **CLAUDE.md** lives at repo root — one file, always.
-- **Skills** live at `.ai-assistance/skills/<skill-name>/SKILL.md`.
-  - Additional assets (scripts, prompts) live alongside the SKILL.md in the same folder.
-- **Code specs** live at `.ai-assistance/code/` (see `code-specs` skill).
-- **Project files** live at `.ai-assistance/projects/<project-name>/` (see `project-cycle` skill).
-- **Refactoring logs** live at `.ai-assistance/code/refactoring/` (see `refactor` skill).
-
-**Never scatter instruction files in code directories.** All AI tooling lives under `.ai-assistance/`.
-
----
-
-## Workflow
-
-1. Identify the type of observation (see table above).
-2. Locate the correct file. Create it if it doesn't exist.
-3. Make the minimal change — don't rewrite documents unnecessarily.
-4. Update the skill index table in CLAUDE.md if a new skill was added.
-5. Confirm with the developer if the change affects an existing convention that other developers rely on.
+# SKILL: AI Instructions Generator, Reviewer & Updater
+
+**Purpose:** Keep CLAUDE.md, skill files, and conventions accurate, tidy, and placed correctly as the project evolves.
+
+---
+
+## When to Use
+
+- A developer makes an observation that reveals a gap, mistake, or new convention.
+- A new pattern emerges in the code that future AI agents should know about.
+- A skill needs to be created, updated, or split.
+- CLAUDE.md needs to reflect a structural change to the repo.
+
+---
+
+## Decision: Practice/Convention vs. CLAUDE.md Instruction vs. Skill
+
+When an observation is made, scope it:
+
+| Type | Where it goes |
+|------|--------------|
+| One-off note or context | Inline comment in the relevant `.ai-assistance/code/*.md` doc |
+| Convention (how we do things here) | `CLAUDE.md` → Conventions section |
+| Always-do behaviour for AI agents | `CLAUDE.md` → Before Starting Any Task, or a new section |
+| Reusable, invocable capability | New or updated `SKILL.md` in `.ai-assistance/skills/<skill-name>/` |
+
+---
+
+## File Placement Rules
+
+- **CLAUDE.md** lives at repo root — one file, always.
+- **Skills** live at `.ai-assistance/skills/<skill-name>/SKILL.md`.
+  - Additional assets (scripts, prompts) live alongside the SKILL.md in the same folder.
+- **Code specs** live at `.ai-assistance/code/` (see `code-specs` skill).
+- **Project files** live at `.ai-assistance/projects/<project-name>/` (see `project-cycle` skill).
+- **Refactoring logs** live at `.ai-assistance/code/refactoring/` (see `refactor` skill).
+
+**Never scatter instruction files in code directories.** All AI tooling lives under `.ai-assistance/`.
+
+---
+
+## Workflow
+
+1. Identify the type of observation (see table above).
+2. Locate the correct file. Create it if it doesn't exist.
+3. Make the minimal change — don't rewrite documents unnecessarily.
+4. Update the skill index table in CLAUDE.md if a new skill was added.
+5. Confirm with the developer if the change affects an existing convention that other developers rely on.

data/.ai-assistance/skills/code-specs/SKILL.md

@@ -1,69 +1,69 @@
-# SKILL: Code Specs for AI
-
-**Purpose:** Maintain AI-readable markdown documentation in `.ai-assistance/code/` so that future AI agents don't need to re-analyse code from scratch. These docs are shortcuts, not replacements — when real analysis is needed, always update them.
-
----
-
-## When to Use
-
-- After analysing a new area of the codebase.
-- Before starting work in an area — check if a doc exists and whether it's stale.
-- After making changes that alter the understanding of an area.
-- Periodically (especially at project cycle-end) — use Gemini Assist to spot stale sections.
-
----
-
-## Document Structure
-
-Each code spec document (`.ai-assistance/code/<area>.md`) must include:
-
-```markdown
-# Code Spec: <Area Name>
-
-**Scope:** What this document covers. What it explicitly does NOT cover.
-**Last updated:** YYYY-MM-DD
-**Key files:** List of the most important files in this area.
-
----
-
-## Overview
-Brief description of what this area does and its role in the gem.
-
-## Key Classes / Modules
-For each significant class: one-line purpose, key public methods/interface.
-
-## Patterns & Conventions
-Design patterns, inheritance chains, naming conventions specific to this area.
-
-## Dependencies
-What this area depends on (internal and external). What depends on it.
-
-## Gotchas / Non-Obvious Behaviours
-Things that would cause confusion or bugs if not known upfront.
-
-## TODOs / Open Questions
-Pending items specific to this area. Link to project TODO if applicable.
-```
-
----
-
-## Naming & Placement
-
-Mirror the `lib/` structure:
-
-| Code area | Doc path |
-|-----------|---------|
-| `lib/ecoportal/api/graphql/model/` | `.ai-assistance/code/model.md` |
-| `lib/ecoportal/api/graphql/input/` | `.ai-assistance/code/input.md` |
-| `lib/ecoportal/api/graphql/logic/` | `.ai-assistance/code/logic.md` |
-| Whole gem overview | `.ai-assistance/code/OVERVIEW.md` |
-
-For deeply nested areas, use subdirectories: `.ai-assistance/code/model/location_structure.md`
-
----
-
-## Keeping Docs Fresh
-
-- When you read a file and find something the doc doesn't mention — add it.
-- When a refactor changes a class — update the corresponding doc.
-- Use the `gemini-assist` skill for batch reviews of multiple docs vs. current code.
+# SKILL: Code Specs for AI
+
+**Purpose:** Maintain AI-readable markdown documentation in `.ai-assistance/code/` so that future AI agents don't need to re-analyse code from scratch. These docs are shortcuts, not replacements — when real analysis is needed, always update them.
+
+---
+
+## When to Use
+
+- After analysing a new area of the codebase.
+- Before starting work in an area — check if a doc exists and whether it's stale.
+- After making changes that alter the understanding of an area.
+- Periodically (especially at project cycle-end) — use Gemini Assist to spot stale sections.
+
+---
+
+## Document Structure
+
+Each code spec document (`.ai-assistance/code/<area>.md`) must include:
+
+```markdown
+# Code Spec: <Area Name>
+
+**Scope:** What this document covers. What it explicitly does NOT cover.
+**Last updated:** YYYY-MM-DD
+**Key files:** List of the most important files in this area.
+
+---
+
+## Overview
+Brief description of what this area does and its role in the gem.
+
+## Key Classes / Modules
+For each significant class: one-line purpose, key public methods/interface.
+
+## Patterns & Conventions
+Design patterns, inheritance chains, naming conventions specific to this area.
+
+## Dependencies
+What this area depends on (internal and external). What depends on it.
+
+## Gotchas / Non-Obvious Behaviours
+Things that would cause confusion or bugs if not known upfront.
+
+## TODOs / Open Questions
+Pending items specific to this area. Link to project TODO if applicable.
+```
+
+---
+
+## Naming & Placement
+
+Mirror the `lib/` structure:
+
+| Code area | Doc path |
+|-----------|---------|
+| `lib/ecoportal/api/graphql/model/` | `.ai-assistance/code/model.md` |
+| `lib/ecoportal/api/graphql/input/` | `.ai-assistance/code/input.md` |
+| `lib/ecoportal/api/graphql/logic/` | `.ai-assistance/code/logic.md` |
+| Whole gem overview | `.ai-assistance/code/OVERVIEW.md` |
+
+For deeply nested areas, use subdirectories: `.ai-assistance/code/model/location_structure.md`
+
+---
+
+## Keeping Docs Fresh
+
+- When you read a file and find something the doc doesn't mention — add it.
+- When a refactor changes a class — update the corresponding doc.
+- Use the `gemini-assist` skill for batch reviews of multiple docs vs. current code.