ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/bridge/context/gemini-review-response.md

@@ -0,0 +1,104 @@
+Here's a detailed review of the bridge protocol design:
+
+## 1. Weaknesses and Failure Modes
+
+1.  **Race Condition / Partial Write during `IN_PROGRESS` Status Update:**
+    *   **Description:** The bridge protocol states, "Code picks it up, updates STATUS to IN_PROGRESS in the inbox file." If two Code instances (e.g., from the same user) concurrently pick up the same task, or if an agent crashes during this update, the `inbox` file could be partially written or overwritten, leading to a corrupted status or lost task. The `LOCK` file only applies to *working tree changes*, not bridge task processing.
+    *   **Likelihood:** Medium.
+    *   **Mitigation:** The status update (PENDING to IN_PROGRESS) should be made atomic. This could be achieved by modifying `task-complete.ts` to *also* handle the `IN_PROGRESS` status update (writing to a temp file and renaming), or by having Code *first* rename the task file to `inbox/[username]-[uuid7]-[slug].IN_PROGRESS.md` (atomic file system operation), then read its content, process, and finally call `task-complete.ts`.
+
+2.  **Stale `IN_PROGRESS` Tasks:**
+    *   **Description:** If Code updates a task to `IN_PROGRESS` but then crashes or gets interrupted before completing it and writing the `outbox` file, the task will remain stuck in `IN_PROGRESS` indefinitely, preventing it from being re-processed.
+    *   **Likelihood:** Medium.
+    *   **Mitigation:** Enhance `bridge-init.sh` or `bridge-status.sh` to detect `IN_PROGRESS` tasks whose `CREATED` or `LAST_MODIFIED` timestamp is older than a defined threshold (e.g., 1 hour). The script should flag these as `STALE_IN_PROGRESS` in its output, prompting the user to manually review, reset to `PENDING`, or fail the task.
+
+3.  **Non-atomic `LOCK` File Acquisition:**
+    *   **Description:** The `LOCK` file acquisition (`cat > .ai-assistance/bridge/LOCK`) is not atomic. If two agents attempt to acquire the lock simultaneously, they could both believe they've succeeded, or one could overwrite the other's lock with a partial or incorrect state.
+    *   **Likelihood:** Medium.
+    *   **Mitigation:** Use a more robust, atomic locking mechanism. On Linux/macOS, `flock -xn .ai-assistance/bridge/LOCK_FILE_LOCK_HELPER -c "cat > .ai-assistance/bridge/LOCK << EOF..."` could be used. This ensures only one process obtains the exclusive lock to write the `LOCK` file.
+
+4.  **Agent Misinterpretation of Git Diff for `wip:` Commit:**
+    *   **Description:** The `code-working-tree-protocol.md` instructs Code to derive a `wip:` commit message by summarizing `git diff` output. This summarization is an AI task prone to hallucinations or misinterpretation, potentially leading to a generic, incorrect, or misleading `wip:` commit message.
+    *   **Likelihood:** High.
+    *   **Mitigation:** Provide a simpler default for the `wip:` commit message (e.g., "wip: in-progress changes by CoWork before Code took over") or instruct Code to be highly verbose in these summaries to reduce the risk of critical information loss. Alternatively, a script could simply list affected files for the `wip:` commit rather than attempting summarization.
+
+5.  **Stale `bridge/STATUS` File:**
+    *   **Description:** Although `bridge-init.sh` runs on `SessionStart`, if a task is created or completed *between* `SessionStart` and Code's first action, the `bridge/STATUS` file might be slightly stale. Code's prompt mentions running `bridge-init.sh` manually *if missing*, but not if potentially stale.
+    *   **Likelihood:** Low, due to `SessionStart` hook.
+    *   **Mitigation:** Instruct Code to explicitly check the timestamp of `bridge/STATUS` after reading it. If it's older than a very short threshold (e.g., 1 minute), Code should re-run `bridge-init.sh` to ensure it has the freshest information before responding to the user about pending tasks.
+
+## 2. Token-Offloading Assessment
+
+The token-offloading strategy is largely **correct and effective**. The choice to offload deterministic, repetitive, and format-specific tasks to scripts (Bash/TypeScript) is well-justified and saves significant AI tokens.
+
+**Areas where scripts effectively offload tokens:**
+*   **UUID Generation and File Naming:** Completely eliminates AI overhead for unique identifiers and consistent file paths.
+*   **Boilerplate File Creation and Archiving:** `task-create.ts` and `task-complete.ts` ensure correct Markdown formatting, status updates, and file movement, preventing AI from generating or validating these structures.
+*   **Environment and User Detection:** `bridge-init.sh` handles dynamic environment variables and git config lookups, which would be tedious for an AI.
+*   **Status Counting and Last Activity:** `bridge-status.sh` uses efficient shell commands to quantify bridge state, avoiding AI parsing of file contents for simple counts.
+*   **Automated Capability Checks:** `capabilities-check.ts` leverages a cheaper Haiku model for periodic, low-stakes verification, which is an excellent token-saving measure for the main agent.
+*   **Date/Time Formatting:** Ensures consistent ISO 8601 timestamps without AI effort.
+
+**Gaps – Things still consuming unnecessary AI tokens:**
+
+1.  **Parsing Markdown Content for Context/Request/Result:** While scripts create the structured Markdown, when CoWork needs to read the `Result` from an `outbox` or Code needs to read the `Context` and `Request` from an `inbox`, the AI still has to parse and interpret the free-form Markdown sections. This requires significant reasoning tokens.
+    *   **Mitigation:** Create a new script, e.g., `task-read.ts`, which takes a task filename and outputs its sections (title, status, context, request, result, notes) in a structured format like JSON. Agents would then call this script and consume the JSON, reducing parsing and interpretation tokens.
+
+2.  **Interpreting `LOCK` file `INTENT` and `FILES`:** When an agent encounters an active `LOCK` file, it must parse the `INTENT` and `FILES` fields from the Markdown to understand what the other agent is doing.
+    *   **Mitigation:** A dedicated script, e.g., `lock-read.ts`, could parse the `LOCK` file and output its contents as JSON for easier consumption by the AI.
+
+3.  **Summarizing `git diff` for `wip:` Commits:** As noted in Q1, the AI is explicitly instructed to summarize `git diff` output to create `wip:` commit messages. This is a complex natural language generation task that directly consumes tokens.
+    *   **Mitigation:** A script could provide a more structured input to the AI (e.g., a list of changed files and line counts, rather than raw diff) or offer a fallback to a generic, less descriptive `wip:` message if summarization is too costly or complex.
+
+**Over-automation (Things better left to AI):**
+There are no apparent instances of over-automation. All scripted tasks are deterministic and non-creative, fitting well within the current offloading strategy.
+
+## 3. Simpler/More Robust Alternatives
+
+The current file-based approach is a **pragmatic balance** between simplicity, git-friendliness, and robustness for a two-agent system within a shared git repository. Significant changes would introduce new complexities or trade-offs.
+
+*   **Replacing file-based with git notes:**
+    *   **Trade-offs:** Would be *less simple* for agents to directly inspect (requiring `git notes show`), and `git notes` is not designed for complex, structured, and rapidly changing data like task queues. While potentially more robust regarding git's atomicity for data storage, concurrency management (e.g., multiple agents trying to modify the same note concurrently) would still be an issue. It would also likely *increase* AI token usage as agents would need to parse git command output.
+    *   **Conclusion:** Not recommended. The current file-based approach is more transparent and easier for agents to handle.
+
+*   **Using a single `TASKS.md` instead of individual files:**
+    *   **Trade-offs:** This would be **significantly less robust**. A single file would be a massive concurrency bottleneck, leading to constant git merge conflicts, race conditions, and corrupted data if multiple agents tried to update it simultaneously. Parsing a large, dynamically changing Markdown file to find and update specific task entries would be complex and token-intensive for the AI.
+    *   **Conclusion:** Strongly discouraged. Individual files are crucial for minimizing conflicts and simplifying task management.
+
+*   **Using a shared SQLite DB:**
+    *   **Trade-offs:**
+        *   **More Robust:** **Highly robust** for concurrent reads/writes and atomic updates at the database level. Solves many of the concurrency issues inherent in file-based systems.
+        *   **Less Simple (for integration):** Requires database access logic in scripts, and the `.db` file would either need to be `gitignored` (making it local-only, not shared across environments/machines) or committed to git. If committed, merging `.db` files in git is impractical, necessitating careful external tooling or a "last writer wins" approach which is generally unsafe for shared state.
+        *   **Conclusion:** While technically more robust for concurrency, it introduces significant friction for sharing the state via git. For a bridge that must exist *within* a git repository and be shareable across distinct environments/machines via git, the file-based approach is generally more suitable than a committed SQLite DB. If the bridge was purely local to a single Code instance, SQLite would be a strong contender.
+
+**Recommended Small Improvement:**
+
+*   **Enhance existing scripts for JSON output:** Instead of a wholesale replacement, invest in the `task-read.ts` (as suggested in Q2) and `lock-read.ts` scripts to provide structured (JSON) output of task and lock data. This improves AI efficiency without abandoning the git-friendly file-based approach.
+
+## 4. Blind Spots
+
+1.  **Git Workflows (Rebasing, Force-push, Stash, Bisect):**
+    *   **Severity:** High.
+    *   **Notes:** The `archive/` folder, containing the history of bridge interactions, is committed to git. Advanced git operations like `rebase`, `bisect`, `cherry-pick`, or `force-push` can rewrite or alter git history. This could lead to a non-linear, broken, or misleading audit trail of bridge tasks. `bisect` would jump to states where tasks might be incomplete or not yet created. `git stash` might hide bridge files from agents. There are no instructions on how agents should interact with these scenarios to maintain bridge history integrity.
+
+2.  **Long-running or Multi-step Tasks Spanning Multiple Sessions:**
+    *   **Severity:** Medium.
+    *   **Notes:** The current bridge task lifecycle (PENDING → IN_PROGRESS → DONE/FAILED) is atomic for single requests. However, it doesn't explicitly support a larger, multi-session, multi-step workflow for a complex feature or project. If a task requires multiple human interventions or distinct phases of execution (e.g., "Build X, get feedback, refine Y, deploy Z"), the agent would need to create multiple, disconnected bridge tasks, losing the overarching context. The 30-minute lock expiry also indicates short-lived operations.
+
+3.  **Multi-Agent Coordination Beyond Two Environments:**
+    *   **Severity:** Low (not in scope, but a future blind spot).
+    *   **Notes:** The design is tightly coupled to CoWork ↔ Code. Expanding to three or more distinct AI agents (e.g., a dedicated "Reviewer" agent, or an external specialized service) would require extending the `FROM`/`TO` fields, the `username` prefixing convention, and potentially the `LOCK` mechanism to handle more complex concurrency.
+
+4.  **Long-term Maintenance and Scalability of `archive/`:**
+    *   **Severity:** Medium.
+    *   **Notes:** The `archive/` folder is designed to grow indefinitely as an audit trail. Over time, it could become very large, increasing repository size, `git clone` times, and making it harder to search or parse the history effectively. There's no mechanism or convention for pruning old archived tasks.
+
+5.  **Security (Unrestricted Shell & Trust Model):**
+    *   **Severity:** High.
+    *   **Notes:** Code has "unrestricted shell" access, and `task-complete.ts` can run `--dangerously-skip-permissions`. This makes the `Request` field in an `inbox` task a critical security vulnerability. An attacker gaining write access to the git repository (or a compromised CoWork session) could submit a malicious task requesting arbitrary shell commands (e.g., `rm -rf /`, exfiltrate sensitive files, install malware). While the user is conceptually in the loop, an agent operating `--dangerously-skip-permissions` could bypass human review. The trust model assumes bridge tasks are always benign.
+
+## Overall Assessment
+
+This design is **sound and highly practical** for its stated purpose as a file-based, git-backed connector delegation service between Claude CoWork and Claude Code. It effectively leverages scripting to offload token-heavy, deterministic tasks and provides clear communication conventions.
+
+The single most important thing to fix is addressing the **security implications of Code's unrestricted shell access** in combination with potentially unverified bridge tasks. This necessitates explicit rules for Code to *always* prompt the user before executing any command requested via a bridge task, or to strictly whitelist command types. Concurrently, making the `IN_PROGRESS` status update and `LOCK` acquisition atomic would significantly improve robustness against internal failure modes.

data/.ai-assistance/bridge/context/project.md

@@ -0,0 +1,42 @@
+# Project Context
+
+Last updated: 2026-06-03
+Maintained by: both CoWork and Code — update when you learn something new
+
+---
+
+## Repositories
+
+| Repo | Location |
+|------|----------|
+| ecoportal-api-graphql | GitLab: `oscar/ecoportal-api-graphql` |
+
+---
+
+## Team
+
+| Username | Environment preference |
+|----------|----------------------|
+| oscar | CoWork for planning/docs, Code for git/GitLab |
+
+---
+
+## Tool boundaries
+
+| Task | Use |
+|------|-----|
+| GitLab MRs, branches, pipelines, issues | Code + GitLab plugin |
+| Git operations on local repo | Code |
+| Documents, spreadsheets, research, planning | CoWork |
+| Scheduling, file organisation, briefs | CoWork |
+| Anything requiring machine-level access | Code |
+
+---
+
+## Key architectural decisions
+
+- Bridge lives in `.claude/bridge/` — tracked in git, co-located with code
+- Task files are UUID + username prefixed — no merge conflicts on pull
+- Scripts handle file ops and env detection — agents consume structured output, not raw files
+- `capabilities/assumptions-log.md` tracks stale knowledge — review periodically
+- Archive is committed — it's the audit trail of AI-assisted work

data/.ai-assistance/bridge/outbox/request-for-standards-discovery.md

@@ -0,0 +1,48 @@
+# Request for ep-ai-standards: Cross-Repo Skill Discovery
+STATUS: DONE
+COMPLETED: 2026-06-11
+FROM: code (ep-ai-standards session)
+TO: cowork / ecoportal-api-graphql session
+
+## Result
+
+All three components implemented and pushed to ep-ai-standards main.
+
+### skills-library/discovery-manifest.yaml
+Machine-readable index mapping 6 repo types to relevant skills + conventions:
+- `org-integration` → ruby-scripting, code-specs, project-cycle + cross-platform + PII conventions
+- `ruby-gem` → ruby-scripting, code-specs, refactor, dep-graph
+- `ruby-scripts` → ruby-scripting, code-specs, project-cycle
+- `rails-app` → code-specs, refactor, spec-generation, dep-graph
+- `typescript-lib` → code-specs, refactor
+- `aws-cdk` → code-specs, refactor
+
+Detection signals Claude can evaluate: `file_exists`, `file_not_exists`, `file_any`,
+`gemfile_includes`, `directory_any`. eP_AI_Manager always proposed regardless of type.
+
+### templates/CLAUDE.thin-client.md.template
+Minimal stub CLAUDE.md. Fill in: repo name, ep-ai-standards path, type, description.
+The session-start instructions tell Claude to read the manifest, verify detection signals,
+and propose skills with one-line reasons — never auto-apply.
+
+### docs/guides/thin-client-repos.md
+Full setup guide covering:
+- Thin-client vs full scaffold decision table
+- 3-step setup (copy template, declare type, verify at first session)
+- multi_org_api worked example (type: org-integration)
+- Reference-over-sync model explained
+- Upgrade path to full scaffold via install.sh --mode retrofit
+
+## Next steps (in TODO.md)
+
+1. Deploy thin-client CLAUDE.md to `multi_org_api`
+   (C:/ruby_scripts/implementation/orgs/multi_org_api, type: org-integration)
+2. Deploy to `training/` as second test case
+3. Add thin-client detection to check-alignment.sh (avoids false MISSING for thin-client repos)
+
+## Notes
+
+The mechanism is entirely instruction-driven — the stub CLAUDE.md itself tells Claude what
+to do at session start. No new script or skill install needed for the initial discovery phase.
+The reference-over-sync model means multi_org_api will always see the latest skills as long
+as ep-ai-standards is at the declared path.

data/.ai-assistance/bridge/queue/.gitkeep

@@ -0,0 +1 @@
+

data/.ai-assistance/capabilities/CLAUDE.md

@@ -0,0 +1,27 @@
+# Capabilities
+
+These files describe what each environment can do natively.
+Before writing a bridge task, check your environment's file — if you can do it yourself, do it.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `cowork.md` | What Claude in CoWork can do natively |
+| `code.md` | What Claude Code can do natively |
+| `connectors.md` | Connector registry — which env, auth status, last verified |
+| `assumptions-log.md` | Dated log of assumptions and their verification status |
+
+## Keeping these current
+
+Capabilities change. The `capabilities-check.ts` script runs periodically and updates
+`assumptions-log.md` with verification results.
+
+If you notice a capability is wrong or stale during normal work:
+1. Note it in `assumptions-log.md` with today's date and STATUS: NEEDS_REVIEW
+2. Do not silently act on stale information
+
+## Last full review
+
+2026-06-04 — revised bridge scope (connector delegation only, not working tree changes);
+updated cowork.md, code.md, connectors.md with confirmed auth status for GitLab/Gemini/GitKraken

data/.ai-assistance/capabilities/assumptions-log.md

@@ -0,0 +1,80 @@
+# Assumptions Log
+
+Tracks assumptions baked into this setup and their verification status.
+Updated by `scripts/capabilities-check.ts` and manually by any agent.
+
+## Statuses
+
+- `CONFIRMED` — verified against a live source, date noted
+- `NEEDS_REVIEW` — time has passed or something seems off, check it
+- `RESOLVED` — was a limitation, now fixed (note how)
+- `INVALIDATED` — assumption was wrong, note what's actually true
+
+---
+
+## Log
+
+### 2026-06-03 — GitLab plugin is Code-only
+STATUS: CONFIRMED
+Last checked: 2026-06-03
+Source: claude.com/plugins/gitlab ("Install in Claude Code" label)
+Notes: Plugin page explicitly states Code-only. CoWork must bridge to Code for all GitLab operations.
+
+### 2026-06-03 — Model knowledge cutoff is May 2025
+STATUS: CONFIRMED
+Last checked: 2026-06-03
+Source: claude-sonnet-4-6 system context
+Notes: ~13 months behind current date (June 2026). Product features, connector availability,
+and plugin ecosystem may have changed significantly. Always verify product claims against
+live sources (claude.com/plugins, docs.claude.ai) rather than training data.
+ACTION: When current model names, API versions, or library releases are needed, ask Gemini
+via the gemini-assist skill or ask the user to run a live API check. Do NOT guess at current
+model IDs (e.g. Gemini model strings) from training data — they change frequently.
+
+### 2026-06-03 — CoWork sandbox has allowlisted (not open) network access
+STATUS: CONFIRMED — CAUSE IDENTIFIED, BEING RESOLVED
+Last checked: 2026-06-03
+Source: CoWork system prompt + Gemini research (2026-06-03)
+Notes: Sandbox restrictions are compounded by MSIX packaging (see entry below).
+After switching to winget install, standard sandbox behaviour should apply.
+GitLab API still not reachable without credentials regardless of install method.
+
+### 2026-06-03 — Claude Desktop installed as MSIX causes silently virtualised AppData paths
+STATUS: CONFIRMED — BEING RESOLVED
+Last checked: 2026-06-03
+Source: Gemini research citing github.com/anthropics/claude-code/issues/58421,
+        linkedin.com/pulse/windows-has-two-completely-different-install-claude-desktop-morrison
+Notes: Anthropic ships the Windows desktop app as an MSIX package. Windows silently
+redirects all AppData writes to a sandboxed container at:
+  AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\
+instead of the documented AppData\Roaming\Claude\. This causes:
+  - MCP config "Edit Config" button opening the wrong path (silently ignored)
+  - Claude Code sandbox running inside an extra layer of Windows MSIX isolation
+  - Plugin skills loaded from wrong paths (GitHub issue 10 Feb 2026)
+  - CoWork VM bundle (claudevm.bundle / rootfs.vhdx) stored under LocalCache
+FIX: Uninstall MSIX version, reinstall via winget (Anthropic.Claude) or standalone
+.exe with "Choose where to get apps" set to Anywhere in Windows settings.
+After fix, config lives at the documented path: AppData\Roaming\Claude\
+Session data migration: copy LocalCache\Roaming\Claude\ → AppData\Roaming\Claude\
+Resolution confirmed by user oscar@ecoportal.co.nz on 2026-06-03.
+
+### 2026-06-03 — CoWork and Code sessions share no automatic context
+STATUS: CONFIRMED
+Last checked: 2026-06-03
+Source: Architecture — separate processes, separate auth
+Notes: The bridge folder is the only reliable shared context mechanism.
+Account-level "Access your Claude Code sessions" permission scope not confirmed
+to provide cross-session history access.
+
+### 2026-06-03 — Gemini connector is available in Code (not CoWork)
+STATUS: NEEDS_REVIEW
+Last checked: 2026-06-03
+Source: Plugin search — not definitively confirmed
+Notes: Assumed based on Code's broader plugin ecosystem. Verify at claude.com/plugins.
+
+---
+
+## Review schedule
+
+Run `scripts/capabilities-check.ts` monthly, or whenever a task fails due to a
+capability assumption. The script flags entries older than 30 days as NEEDS_REVIEW.

data/.ai-assistance/capabilities/code.md

@@ -0,0 +1,47 @@
+# Code Native Capabilities
+
+Last verified: 2026-06-04
+Environment: Claude Code CLI (terminal / VS Code / desktop app Code mode)
+
+## Can do natively
+
+- Full local machine access (read/write any file, run any command)
+- Git operations (clone, pull, push, branch, merge, diff, log)
+- Install software and packages
+- Run scripts in any language (Ruby, TypeScript, Python, Bash, etc.)
+- Spawn parallel subagents (fan-out tasks)
+- Scheduled via /schedule, /loop, or Routines (run on Anthropic infra, laptop off)
+- Remote control via mobile app
+- Claude SDK (TypeScript) for programmatic agent creation
+
+## Connectors available in Code
+
+See `connectors.md` for the full registry.
+
+Confirmed available (2026-06-04):
+- GitLab (`gitlab-mr-mcp` via PAT — expiry April 2027, rotation enabled)
+- GitKraken (via `gk mcp` CLI — requires `gk auth login`)
+- Gemini (via `gemini-mcp-server.js` + `GEMINI_API_KEY` in `.env`)
+- GitHub (if installed)
+- Playwright (browser automation, if installed)
+
+## Cannot do
+
+- CoWork-specific artifacts (live HTML widgets persisted in CoWork UI)
+- CoWork scheduled tasks (require desktop app UI)
+- Access CoWork conversation history directly
+
+## Role in the bridge
+
+Code is the **bridge execution environment** — it receives connector delegation tasks
+from CoWork and calls the required external service. When Code picks up a bridge task:
+
+1. Check `connectors.md` — confirm the required connector is available and authenticated
+2. If connector is missing or needs-setup: write a FAILED outbox immediately, explain what's needed
+3. If connector is available: call it, write the result to outbox
+4. Do not make working tree changes as part of a bridge task unless the task explicitly requests it
+
+## When to bridge to CoWork
+
+Write a bridge task to CoWork only when the task requires CoWork-specific features
+(artifacts, scheduled tasks, CoWork-only connectors). This is rare — Code can do most things directly.

data/.ai-assistance/capabilities/connectors.md

@@ -0,0 +1,37 @@
+# Connector Registry
+
+Each row is a connector/plugin. Update `last-verified` when you confirm its status.
+Run `scripts/capabilities-check.ts` to automate verification.
+
+## Format
+
+| Connector | CoWork | Code | Auth status | Last verified |
+|-----------|--------|------|-------------|---------------|
+| name | ✓/✗ | ✓/✗ | ok / needs-setup / unknown | YYYY-MM-DD |
+
+---
+
+## Registry
+
+| Connector | CoWork | Code | Auth status | Notes | Last verified |
+|-----------|--------|------|-------------|-------|---------------|
+| GitLab | ✗ | ✓ | ok | PAT configured in `.env` + `claude_desktop_config.json`. Expiry April 2027, rotation enabled. Scopes: read_api, read_repository, create_runner, ai_features. CoWork ✗ confirmed — even with config entry, gitlab-mr-mcp does not connect in CoWork. Bridge to Code. | 2026-06-04 |
+| GitKraken | ✗ | ✓ | ok | `gk mcp` confirmed working in Code (branch lookup verified). Config written to `claude_desktop_config.json` but CoWork ✗ — MCP servers in Desktop config do not surface as CoWork connectors. Bridge to Code for git context. | 2026-06-04 |
+| Gemini | ✗ | ✓ | ok | `gemini-mcp-server.js` + `GEMINI_API_KEY` in `.env`. Model: gemini-2.5-flash. **Note:** `gemini_ask.rb` fails on Windows (SSL cert issue) — use PowerShell `Invoke-RestMethod` or the MCP server instead. MCP server path in global settings may point to `.ai-assistance/skills/` — verify if MCP tool becomes unavailable. | 2026-06-04 |
+| GitHub | ✗ | ✓ | unknown | Not tested in this project | 2026-06-03 |
+| Slack | ✓ | ✗ | unknown | Not authenticated in this project | 2026-06-03 |
+| Notion | ✓ | ✗ | unknown | Not authenticated in this project | 2026-06-03 |
+| Google Drive | ✓ | ✗ | unknown | Not authenticated in this project | 2026-06-03 |
+| Gmail | ✓ | ✗ | unknown | Not authenticated in this project | 2026-06-03 |
+| HubSpot | ✓ | ✗ | unknown | Not authenticated in this project | 2026-06-03 |
+| Asana | ✓ | ✗ | unknown | Not authenticated in this project | 2026-06-03 |
+| Linear | ✓ | ✓ | unknown | Not authenticated in this project | 2026-06-03 |
+
+## Notes
+
+- ✗ does not mean permanently unavailable — check claude.com/plugins for current availability
+- Auth status `unknown` = not tested in this project yet
+- Auth status `needs-setup` = connector present but credentials missing — write a bridge task to Code to complete setup (Code handles OAuth flows; CoWork cannot)
+- Auth status `ok` = confirmed working in at least one session
+- Bridge-eligible connectors (CoWork ✗, Code ✓) are the ones CoWork delegates to via the bridge
+- Source for CoWork vs Code availability: claude.com/plugins/[name] → "Install in" label

data/.ai-assistance/capabilities/cowork.md

@@ -0,0 +1,55 @@
+# CoWork Native Capabilities
+
+Last verified: 2026-06-04
+Environment: Claude desktop app — CoWork mode
+
+## Can do natively
+
+- Read, write, edit files in connected folders (including all of `.ai-assistance/`)
+- Web search and page fetch
+- Bash sandbox (Ubuntu 22, Python/Node preinstalled, allowlisted network)
+- Create documents: .docx, .pptx, .xlsx, .pdf, .md, .html
+- Render live HTML/React artifacts (persist across sessions)
+- Scheduled tasks (while desktop app is open)
+- Skills: docx, pptx, xlsx, pdf, and all installed plugin skills
+
+## Cannot do
+
+- Write or edit files under `.ai-assistance/` (application-layer guard on that path)
+- Direct git operations (clone, push, pull, branch, commit)
+- Install software on host machine
+- Run commands outside the bash sandbox
+- Access Code sessions or terminal history
+- Use MCP servers defined in `claude_desktop_config.json` — those do not surface as
+  CoWork connectors. CoWork connectors are installed via Settings → Plugins only.
+  Verified 2026-06-04: GitLab and GitKraken written to Desktop config, neither
+  appeared as available connectors in CoWork.
+
+## Connectors available in CoWork
+
+See `connectors.md` for the full registry. Install via Settings → Plugins.
+
+Confirmed available (2026-06-04):
+- Google Workspace (Drive, Gmail, Calendar) — if authenticated
+- Slack — if authenticated
+- Notion — if authenticated
+- HubSpot, Intercom, Asana, Linear, etc. — if plugin installed + authenticated
+
+## When to use the bridge
+
+The bridge is a **connector delegation service** — use it only when you need to call
+a service that CoWork cannot reach. Do not bridge for working tree edits, documentation,
+or anything in the "Can do natively" list above.
+
+Bridge to Code when you need:
+
+| Connector / service | Why Code has it |
+|---------------------|-----------------|
+| Gemini | Gemini MCP configured in Code |
+| GitLab (MRs, pipelines, issues) | GitLab MCP configured in Code |
+| GitKraken (git history, branches) | GitKraken MCP configured in Code |
+| Unrestricted shell (host-level) | Code runs outside the sandbox |
+
+Before writing a bridge task, check `connectors.md` to confirm the connector is
+available and authenticated in Code. If status is `unknown` or `needs-setup`, note
+that in the bridge task so Code can surface the issue.

data/.ai-assistance/code/OVERVIEW.md

@@ -0,0 +1,155 @@
+# Code Spec: ecoportal-api-graphql — Gem Overview
+
+**Scope:** High-level structure, entry points, key patterns, and namespace conventions for the whole gem. Does NOT cover per-area implementation detail — see area-specific docs in `.ai-assistance/code/` for those.
+**Last updated:** 2026-06-02
+**Key files:**
+- `lib/ecoportal/api-graphql.rb` — gem entry point (requires upstream, boots namespace)
+- `lib/ecoportal/api/graphql.rb` — main `Ecoportal::API::GraphQL` class
+- `lib/ecoportal/api/common/graphql/client.rb` — GraphQL HTTP client (wraps graphlient)
+- `ecoportal-api-graphql.gemspec` — gem spec and dependencies
+
+---
+
+## Overview
+
+`ecoportal-api-graphql` provides a Ruby client for EcoPortal's GraphQL API. It wraps `graphlient` (which wraps `graphql-client`) and builds a structured layer of models, queries, mutations, fragments, inputs, payloads, and builders on top of it.
+
+The gem is used primarily by `eco-helpers` (downstream). Backwards compatibility with `eco-helpers` must be preserved unless explicitly broken.
+
+---
+
+## Dependency Chain
+
+```
+graphql-ruby (rmosolgo)         — schema definition side (not directly used as a dep)
+graphql-client                  — low-level HTTP+parsing
+graphlient                      — friendlier wrapper around graphql-client (~> 0.8)
+ecoportal-api (~> 0.10)         — REST API base (auth, org context)
+ecoportal-api-v2 (~> 3.3)       — REST API v2 (required by entry point)
+        ↓
+ecoportal-api-graphql           ← THIS GEM
+        ↓
+eco-helpers                     — downstream consumer
+```
+
+---
+
+## Entry Point
+
+`require 'ecoportal/api-graphql'` loads:
+1. `ecoportal-api-v2` (and transitively `ecoportal-api`)
+2. `ecoportal/api/graphql_version`
+3. `ecoportal/api/common.graphql` — shared common GraphQL utilities
+4. `ecoportal/api/graphql` — the main class + all sub-requires
+
+Load order within `graphql.rb`:
+`helpers` → `concerns` → `logic/base_model` → `error` → `interface` → `base` → `model` → `logic` → `connection` → `payload` → `input` → `fragment` → `query` → `mutation` → `builder`
+
+---
+
+## Main Class: `Ecoportal::API::GraphQL`
+
+The public entry point. Instantiated with credentials:
+
+```ruby
+api = Ecoportal::API::GraphQL.new(email: "...", pass: "...", org_id: "...", host: "live.ecoportal.com")
+```
+
+Key public methods:
+- `#currentOrganization` / `#currentOrganizationClass` — returns `Model::Organization` with client set
+- `#contractorEntity` → `Builder::ContractorEntity`
+- `#locationStructure` → `Builder::LocationStructure`
+- `#action` → `Builder::Action`
+- `#createContractorEntity(input:)` — convenience shortcut (delegates to mutation)
+
+Includes `Common::GraphQL::ClassHelpers` for `class_resolver` — allows subclasses to override `client_class`.
+
+---
+
+## Namespace Convention
+
+**IMPORTANT:** The module is `Ecoportal::API::GraphQL` (capital Q, capital L) but Ruby casing — NOT `Ecoportal::API::GraphQl`. File paths use lowercase: `graphql/`.
+
+Class nesting mirrors folder structure exactly:
+
+| Folder | Module/Class |
+|--------|-------------|
+| `graphql/model/` | `GraphQL::Model::*` |
+| `graphql/input/` | `GraphQL::Input::*` |
+| `graphql/mutation/` | `GraphQL::Mutation::*` |
+| `graphql/query/` | `GraphQL::Query::*` |
+| `graphql/builder/` | `GraphQL::Builder::*` |
+| `graphql/fragment/` | `GraphQL::Fragment::*` |
+| `graphql/payload/` | `GraphQL::Payload::*` |
+| `graphql/connection/` | `GraphQL::Connection::*` |
+| `graphql/logic/` | `GraphQL::Logic::*` |
+| `graphql/base/` | `GraphQL::Base::*` |
+| `graphql/interface/` | `GraphQL::Interface::*` |
+| `graphql/error/` | `GraphQL::Error::*` |
+
+---
+
+## Architectural Layers
+
+```
+Builder           High-level façade — developer-facing API per domain
+    ↓
+Query / Mutation  GraphQL operation definitions
+    ↓
+Logic             Execution layer (base_query, base_model, query, mutation, payload, input, connection)
+    ↓
+Fragment          GraphQL fragment strings
+    ↓
+Model             Response data models (read side)
+Input / Payload   Mutation arguments (write side) and mutation responses
+    ↓
+Base              Shared base classes for models
+Interface         GraphQL interface type definitions
+    ↓
+Common::GraphQL::Client   HTTP layer (graphlient wrapper with auth)
+```
+
+---
+
+## Common::GraphQL Layer
+
+Lives in `lib/ecoportal/api/common/graphql/`. Key classes:
+
+- `Client` — extends `Graphlient::Client`. Handles auth (`AuthService`), org_id, timeouts (90s read/write). `no_schema: true` skips schema introspection.
+- `Model` — base model class for response parsing.
+- `ClassHelpers` — `class_resolver` macro for dependency injection of class references.
+- `HashHelpers` — hash utility methods.
+- `QueryIntegration` — mixin for query execution.
+- `Patches` — monkey-patches to upstream libs (review carefully before changing).
+
+---
+
+## Domain Objects
+
+The gem covers these EcoPortal GraphQL domains:
+
+| Domain | Builder | Key Model | Key Mutations |
+|--------|---------|-----------|--------------|
+| Location Structure | `Builder::LocationStructure` | `Model::LocationStructure` | draft create/delete/publish, apply_commands |
+| Contractor Entity | `Builder::ContractorEntity` | `Model::ContractorEntity` | create, update, destroy |
+| Action | `Builder::Action` | `Model::Action` | create, update, archive |
+| Organization | — (direct on GraphQL class) | `Model::Organization` | — |
+| Page | — | `Model::Page` | — |
+
+---
+
+## Gotchas / Non-Obvious Behaviours
+
+- `no_schema: true` is always passed — schema introspection is disabled. Queries are not validated against a schema at build time.
+- `GraphQL::Fragment` is instantiated at GraphQL init and passed around — it's a container for fragment string definitions.
+- `Builder` classes take a `client` directly, not a `GraphQL` instance.
+- `Logic::BaseModel` inherits from `Common::GraphQL::Model` and adds a class-level `client` accessor. Most model/query classes inherit from this.
+- `class_resolver` (from `ClassHelpers`) allows subclasses to override which concrete class is used — important for testing and extension.
+
+---
+
+## TODOs / Open Questions
+
+- [ ] Per-area code spec docs need to be created as analysis progresses.
+- [ ] `Common::GraphQL::Patches` contents not yet reviewed — may contain important behavioural notes.
+- [ ] Spec coverage is minimal — `spec/ecoportal/api_spec.rb` exists but subdirectory coverage is sparse.