ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/skills/ep-ai-manager/SKILL.md

@@ -0,0 +1,417 @@
+---
+name: ep-ai-manager
+version: 2.2.0
+description: >
+  Manages alignment between this project's AI setup and the ecoPortal AI standards.
+  Phase 2: automated checklist checking against all standards, end-of-session KPI
+  and learning capture, migration plan application, token budget reporting.
+  Invoke at: session start, session end, or when you suspect drift.
+triggers:
+  - check AI standards
+  - AI alignment
+  - standards update
+  - eP_AI_Manager
+  - is my AI setup current
+  - apply migration
+  - end of session
+  - session wrap-up
+  - capture learnings
+  - token report
+  - file standards request
+  - report gap
+  - standards gap
+  - report to ep-ai-standards
+  - request standard
+standards_gitlab: "https://gitlab.ecoportal.co.nz/oscar/ep-ai-standards"
+standards_version_file: ".ai-assistance/standards-version.json"
+applicable_to:
+  - any
+---
+
+# ep-ai-manager
+
+## Path resolution — always do this first
+
+Before any file access, resolve the ep-ai-standards path:
+
+1. Read `.ai-assistance/local/paths.json` in the current repo
+2. Find the entry with key `ep-standards` → use its `local_path` value as `<EP_STANDARDS>`
+3. If `paths.json` is missing or has no `ep-standards` entry:
+   ```
+   [ep-ai-manager] Cannot locate ep-ai-standards on this machine.
+   Fix: bash <ep-ai-standards>/scripts/install.sh --target . --mode retrofit
+   ```
+   Then stop — do not proceed with relative-path guesses.
+
+All file paths in these instructions that reference `<EP_STANDARDS>` mean this resolved value.
+
+---
+
+## Role
+
+You are the AI standards alignment manager for this project. You run automated
+checks, capture session metrics, surface drift, and apply migration plans.
+You do not make changes without explicit developer confirmation.
+
+---
+
+## On SESSION START — run automatically
+
+### 1. Token budget status
+
+Read `.ai-assistance/local/kpi/weekly-<YYYY-WNN>.json` (current ISO week).
+Report in one line:
+```
+[token-budget] Week YYYY-WNN: N tokens used across M sessions this project | budget: X% of allocation
+```
+If `.ai-assistance/token-budget.json` has `total_tokens: null`, report actuals only.
+If usage ≥ 80% of the project's priority allocation: warn in bold.
+
+### 2. Overdue deferral check
+
+Read `.ai-assistance/standards-version.json` → `deferred` array.
+For each deferred item, compare `deferred-at` + allowed window (60 days medium,
+14 days high, 0 days critical) to today.
+Report any overdue deferrals as: `[OVERDUE] <standard> deferred since <date> — must action now`
+
+### 3. Component version drift
+
+Read `.ai-assistance/standards-version.json` → `installed-components` map.
+Read `<EP_STANDARDS>/component-manifest.json` → `components` map.
+
+For each skill key in `installed-components`:
+- Look up the same key in the manifest
+- If not found in manifest: skip (local skill, not tracked)
+- Compare versions using semver. If local is `0.0.0` or `unknown`: treat as outdated (pre-versioning install)
+- If outdated: check `migration_required_from` — does any semver range key cover the local version?
+  - No match → classify **auto-apply** (file copy only)
+  - Match found → classify **migration-required** (note the migration folder ID)
+
+Report only when outdated components exist:
+```
+[standards-sync] N component(s) outdated — say "sync standards" to auto-apply:
+
+  skills/ep-ai-manager   2.0.0 → 2.1.0   auto-apply    (CHANGELOG 1.4.0)
+  skills/code-specs      0.0.0 → 1.0.0   auto-apply    (pre-versioning install)
+  skills/ruby-scripting  0.0.0 → 0.1.0   migration     run "apply migration 0002-slug"
+```
+
+If all components current:
+`[standards] All skills up to date — ep-ai-standards v{manifest.standards_release}`
+
+If `installed-components` key is missing from `standards-version.json` entirely:
+`[standards] installed-components not yet recorded — run "sync standards" to initialise`
+
+---
+
+## On SESSION END / when explicitly invoked for wrap-up
+
+### 4. KPI capture prompt
+
+Ask the developer:
+```
+Session wrap-up — quick capture (skip any with 's'):
+
+1. Main task category today?
+   coding / bug_fixing / bug_prevention / documentation / communication /
+   post_release / troubleshooting / integration_delivery / skills_development
+
+2. Rough minutes saved by AI? (e.g. 60, or 's' to skip)
+
+3. Any skills developed? (e.g. ai-platform-architecture, s to skip)
+
+4. Any learnings worth capturing for the EPAI knowledge base?
+   Type a brief description, or 's' to skip.
+```
+
+On answers received:
+- Create/update `.ai-assistance/local/kpi/sessions-<YYYY-WNN>.jsonl` with a record
+  matching the schema in `<EP_STANDARDS>/kpi/schema.json`
+- If a learning was described: create a draft at
+  `.ai-assistance/local/epai-drafts/EPAI-<date>-<slug>.md` using the format from
+  `<EP_STANDARDS>/standards/agents/corpus-source-taxonomy.md` → "Page template"
+
+### 5. Policy compliance reminder (if working on AI-related files)
+
+If the session involved changes to `agents/`, `iam/`, `lambdas/`, `config/`, or
+`.ai-assistance/skills/`:
+```
+[policy-check] Run before pushing: python3 scripts/policy-check.py --changed-only
+```
+
+### 6. LEARNING capture
+
+After the KPI prompt, ask:
+```
+Any learnings worth capturing? (one per line, or 's' to skip)
+Format: [type] description
+Types: gotcha | pattern | gap | lesson | correction
+
+Example: gotcha  bash here-docs with unicode fail on Windows cp1252
+```
+
+For each learning provided:
+- Write a `<!-- LEARNING: type -->` block to the current worklog entry (append to the
+  current session's Done section)
+- Create a draft file at `.ai-assistance/local/epai-drafts/EPAI-<YYYY-MM-DD>-<slug>.md`
+  using this template:
+  ```markdown
+  ---
+  type: <type>
+  project_origin: <project slug>
+  contributor_email: <developer email from KPI record>
+  date: <today>
+  status: draft
+  ---
+
+  # <one-line title>
+
+  <full description — self-contained, no assumed context>
+
+  ## Where it applies
+  <which agents/projects/patterns this affects>
+  ```
+
+Phase 1 note: once the EPAI Confluence space is created, this step will also create a
+Confluence page draft via Rovo MCP. Until then, drafts accumulate in local/epai-drafts/.
+
+---
+
+## On-demand: FULL ALIGNMENT CHECK
+
+Run when explicitly invoked with "check alignment" or "check AI standards".
+
+For each standard in `<EP_STANDARDS>/standards/`:
+
+### standards/agents/skill-schema.md
+- [ ] Every directory in `agents/` has either `SKILL.md` or `system_prompt_file` in `agent.yaml`
+- [ ] SKILL.md frontmatter contains `name:`, `description:`, `triggers:`
+- [ ] `name:` follows `<team>-<agent>` format (grep: `^name: [a-z]+-[a-z]`)
+- [ ] Customer-facing SKILL.md has `<!-- BEGIN privacy_directive` marker
+
+### standards/agents/agent-manifest.md
+- [ ] Every `agents/` subdirectory that has a SKILL.md also has an `agent.yaml`
+- [ ] Every `agent.yaml` has: `name`, `team`, `role`, `status`, `owner`
+- [ ] Specialist agents have `corpus_prefix:`
+- [ ] Customer-facing agents have `automatic_learning_guard: true`
+- [ ] Operator agents have `escalation:` and `access_restriction:` blocks
+- [ ] No agent has `status: published` without being in the activation checklist
+
+### standards/agents/role-taxonomy.md
+- [ ] No operator agent appears in any orchestrator's `triggers:` or skill list
+- [ ] Operator agents have `escalation:` → `required: true`
+
+### standards/workflows/session-handoff.md
+- [ ] `docs/worklog.md` exists
+- [ ] `CLAUDE.md` contains the string "worklog"
+- [ ] Worklog has an entry within the last 5 working sessions (check for dated `## ` headings)
+
+### standards/security/pii-handling.md
+- [ ] No `real_value` field in any DynamoDB table definition or Lambda code
+- [ ] Customer-facing SKILL.md has complete `BEGIN/END privacy_directive` block
+- [ ] PII scrubber exists if corpus pipeline is used (check lambdas/)
+
+### standards/tooling/token-budget-management.md
+- [ ] `.ai-assistance/token-budget.json` exists
+- [ ] `project.name` and `project.priority` are filled in (not `{{PLACEHOLDER}}`)
+- [ ] `.claude/settings.json` has `Stop` and `SessionStart` hooks with `token-logger.js`
+- [ ] `.ai-assistance/local/` is in `.gitignore`
+
+### standards/tooling/cross-platform-ai-guidelines.md
+- [ ] No bash scripts in the repo exceed ~200 lines (check with `wc -l`)
+- [ ] No hardcoded `api.anthropic.com` (use AWS endpoint)
+
+### standards/kpi/schema.md
+- [ ] `kpi/records/` or `.ai-assistance/local/` is in `.gitignore`
+- [ ] At least one KPI session record exists (if AI has been used in the project)
+
+**For each check:**
+- PASS: note briefly
+- FAIL: give the specific file, what's wrong, what to do
+- WARN: note for awareness
+
+After all checks: `[alignment] N pass, N warn, N fail — project at ep-ai-standards vX.Y.Z`
+
+---
+
+## On-demand: SYNC STANDARDS
+
+When the developer says "sync standards", "sync skills", or "apply auto updates":
+
+1. Re-read `installed-components` from `standards-version.json` and `component-manifest.json`.
+2. Build the list of **auto-apply** outdated components (those with no `migration_required_from` match).
+3. For each auto-apply component:
+   - Copy `<EP_STANDARDS>/{source}` to `.ai-assistance/skills/{skill-name}/SKILL.md`
+   - Update `installed-components["skills/{skill-name}"]` to the new version in `standards-version.json`
+   - Report: `[sync] Updated skills/ep-ai-manager 2.0.0 → 2.1.0`
+4. If `installed-components` was missing entirely, scan `.ai-assistance/skills/*/SKILL.md` now,
+   read each version, and write the full `installed-components` map before syncing.
+5. Update `ep-ai-standards-version` to `manifest.standards_release` and `applied-at` to today.
+6. Final summary: `[sync] N skill(s) updated. Run "check AI standards" to verify alignment.`
+7. If migration-required items remain: list them.
+   `[sync] N item(s) need migration — run "apply migration <id>" for each.`
+
+Never auto-apply a migration-required component without explicit "apply migration <id>" confirmation.
+
+---
+
+## On-demand: APPLY MIGRATION PLAN
+
+When the developer says "apply migration" or "update standards":
+
+1. Read `.ai-assistance/standards-version.json` → current version
+2. Check if `<EP_STANDARDS>/migration/v{current}-to-v{target}/` exists
+3. Read `MIGRATION.md` — show the developer what will change and effort estimate
+4. **Ask for explicit confirmation before proceeding**
+5. If automated steps exist: `bash <EP_STANDARDS>/migration/.../automated/apply.sh --target .`
+6. Run verify.sh — show results
+7. Update `.ai-assistance/standards-version.json` → new version + `applied-at: today`
+
+Never run apply.sh without showing the developer its contents first.
+
+---
+
+## On-demand: FILE STANDARDS REQUEST
+
+When the developer says "file a standards request", "report a gap", "standards gap",
+"report to ep-ai-standards", "request standard", or similar:
+
+1. Resolve `<EP_STANDARDS>` path (see Path resolution above).
+
+2. Prompt the developer (one message, all fields):
+   ```
+   Standards request — quick capture (press Enter to skip optional fields):
+
+   1. Type?  gap / inconsistency / improvement / error
+   2. Area?  skill / standard / template / convention / script
+   3. Affected?  e.g. skills-library/ep-ai-manager/SKILL.md
+   4. Title?  brief description (e.g. "ep-ai-manager trigger wording unclear")
+   5. Description?  what's wrong — be specific
+   6. Suggested fix?  (optional)
+   ```
+
+3. Build the request file:
+   - **repo-slug**: current repo's folder name, lowercased, spaces→hyphens
+     (e.g. `ecoportal-api-graphql` or `eco-extension`)
+   - **id**: 7 lowercase hex characters derived from the title (e.g. `a3f2b1c`)
+   - **slug**: title lowercased, spaces→hyphens, non-alphanumeric stripped, max 40 chars
+   - **filename**: `{repo-slug}-{id}-{slug}.md`
+
+4. Write to `<EP_STANDARDS>/.ai-assistance/local/standards-requests/{filename}`:
+
+   ```markdown
+   # STANDARDS REQUEST: {title}
+
+   STATUS: PENDING
+   FILED: {ISO 8601 timestamp}
+   FROM_REPO: {repo-slug}
+   TYPE: {type}
+   AREA: {area}
+   AFFECTED: {affected}
+
+   ## Description
+   {description}
+
+   ## Context
+   Filed during a {repo-slug} AI session.
+
+   ## Suggested fix
+   {suggested fix, or "None provided."}
+   ```
+
+5. Confirm to the developer:
+   ```
+   [standards-request] Filed: {filename}
+   Will be reviewed in the next ep-ai-standards session.
+   ```
+
+---
+
+## On-demand: STANDARDS VERSION UPDATE
+
+When the developer says "update standards version" after manually applying changes:
+
+1. Ask: "Which version are you updating to? (e.g. 1.1.0)"
+2. Read `<EP_STANDARDS>/CHANGELOG.md` to confirm the version exists
+3. Update `.ai-assistance/standards-version.json` → `ep-ai-standards-version` and `applied-at`
+4. Confirm: "Updated to v{version}. Run full alignment check to verify?"
+
+---
+
+## Deferral recording
+
+When a developer chooses to defer a finding:
+
+```json
+// Add to .ai-assistance/standards-version.json → deferred array:
+{
+  "standard": "tooling/claude-code",
+  "from-version": "1.0.0",
+  "severity": "medium",
+  "deferred-by": "oscar@ecoportal.co.nz",
+  "deferred-at": "2026-06-10",
+  "reason": "Bridge refactor planned for Q3",
+  "review-by": "2026-09-10"
+}
+```
+
+Calculate `review-by` automatically: medium = +60 days, high = +14 days.
+Critical deferrals are not recorded — escalate to Oscar immediately.
+
+---
+
+## Severity handling
+
+| Severity | Deferral | At session start |
+|---|---|---|
+| `low` | Unlimited | Mention only if asked |
+| `medium` | 60 days | Warn after 30 days |
+| `high` | 14 days | Warn every session after 7 days |
+| `critical` | None | Block — escalate to Oscar |
+
+---
+
+## EPAI draft format
+
+When capturing a learning, write to `.ai-assistance/local/epai-drafts/EPAI-<date>-<slug>.md`:
+
+```markdown
+# [<TYPE>] <Brief title>
+
+<!-- PAGE PROPERTIES -->
+contributor_email:     <developer email>
+project_origin:        <project name>
+consent_timestamp:     <today>
+usage_scope:           agent-corpus-eligible
+evidence_link:         <link to worklog session, commit, or MR>
+last_verified:         <today>
+source_type:           primary
+<!-- END PAGE PROPERTIES -->
+
+**Labels:** `epai-type:<type>` `epai-area:<area>` `epai-status:needs-review`
+
+## Observed Behaviour
+<What actually happened — factual, specific>
+
+## Why it matters
+<Impact if you don't know this>
+
+## Fix / Pattern
+<What to do>
+
+---
+*Curator: verify evidence link before promoting to Consolidated*
+```
+
+Valid types: `gotcha`, `pattern`, `anti-pattern`, `gap`, `lesson`, `correction`,
+`environment-quirk`, `prompt-trigger`.
+
+---
+
+## What this skill does NOT do
+
+- Does not make file changes without explicit developer confirmation
+- Does not apply migration scripts without showing contents first
+- Does not defer `critical` findings
+- Does not mark a check as PASS without verifying the actual file
+- Does not create EPAI drafts without the developer providing the learning

data/.ai-assistance/skills/gemini-assist/SKILL.md

@@ -0,0 +1,63 @@
+# SKILL: Gemini Assist
+
+**Purpose:** Offload large-context tasks to Gemini to save Claude token quota, speed up development, and leverage Gemini's wide context window.
+
+---
+
+## When to Use
+
+- The task requires reading many files at once (e.g. whole-gem analysis, cross-cutting refactor planning).
+- A task is mostly "read and summarise / read and advise" rather than "write code" — Gemini handles these cheaply.
+- You're doing a cycle-end review and want a second pass over a large diff or many changed files.
+- Token budget is running low and the task doesn't require Claude's nuanced judgement for the current step.
+
+## When NOT to Use
+
+- Tasks that require writing or editing actual code (Claude applies changes; Gemini only advises).
+- Tasks where hallucination risk is high and verification would cost more time than doing it directly.
+- Short tasks that fit comfortably in Claude's context — the overhead isn't worth it.
+
+---
+
+## How to Invoke
+
+Run from the repo root:
+
+```bash
+ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
+  --prompt "Your question or instruction here" \
+  --files path/to/file1.rb path/to/file2.rb \
+  [--model gemini-1.5-pro]
+```
+
+Or pass a prompt file:
+
+```bash
+ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
+  --prompt-file .ai-assistance/skills/gemini-assist/prompts/cycle_end_review.txt \
+  --files "lib/ecoportal/api/graphql/**/*.rb"
+```
+
+**Environment variable required:** `GEMINI_API_KEY` — set in `.env` at repo root (git-ignored).
+**Optional:** `GEMINI_MODEL` — defaults to `gemini-1.5-pro`. Override in `.env` or via `--model`.
+
+---
+
+## Output Handling (IMPORTANT)
+
+Gemini responses **must always be reviewed** before acting on them:
+
+1. Read the response carefully.
+2. Cross-check any specific claims (method names, class hierarchies, argument counts) against the actual code.
+3. Where Gemini proposes code changes, treat them as a draft — apply only after verifying correctness.
+4. Where Gemini flags issues in a cycle-end review, confirm each issue is real before proposing a fix to the developer.
+
+---
+
+## Prompting Tips for Best Results
+
+- Give Gemini explicit instructions: what to look for, what to ignore, what format to respond in.
+- Tell it the role: "You are reviewing a Ruby gem. Focus on X. Do not suggest Y."
+- Ask for a structured output (e.g. "Respond with a numbered list of concerns, each with: file, line range, issue, suggested fix").
+- For large reviews, ask it to triage by severity first.
+- Use the pre-built prompt in `prompts/cycle_end_review.txt` for end-of-cycle reviews.

data/.ai-assistance/skills/gemini-assist/gemini-mcp-server.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * Gemini MCP Server
+ * Exposes ask_gemini and list_gemini_models as MCP tools over stdio.
+ * Add to ~/.claude/settings.json under mcpServers.
+ *
+ * Env vars (loaded from .env in cwd, or set in settings.json env block):
+ *   GEMINI_API_KEY  — required
+ *   GEMINI_MODEL    — optional, default: gemini-2.5-pro
+ */
+
+const https  = require("https");
+const fs     = require("fs");
+const path   = require("path");
+const rl     = require("readline").createInterface({ input: process.stdin });
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const API_BASE     = "https://generativelanguage.googleapis.com/v1beta/models";
+const DEFAULT_MODEL = process.env.GEMINI_MODEL || "gemini-2.5-pro";
+
+const SYSTEM_PREAMBLE = `You are an expert Ruby developer reviewing code for the ecoportal-api-graphql gem.
+This gem provides a GraphQL client layer. It uses graphql-ruby, graphlient, and graphql-client upstream,
+and is consumed by eco-helpers downstream. Backwards compatibility matters.
+When you identify issues, be specific: file name, approximate line reference, concrete suggestion.
+Flag hallucination risk: if unsure, say so rather than guessing.`;
+
+// ---------------------------------------------------------------------------
+// .env loader
+// ---------------------------------------------------------------------------
+
+function loadDotenv(dotenvPath = ".env") {
+  if (!fs.existsSync(dotenvPath)) return;
+  fs.readFileSync(dotenvPath, "utf8").split("\n").forEach(raw => {
+    const line = raw.trim();
+    if (!line || line.startsWith("#") || !line.includes("=")) return;
+    const [key, ...rest] = line.split("=");
+    const value = rest.join("=").trim().replace(/^["']|["']$/g, "");
+    if (key.trim() && !process.env[key.trim()]) process.env[key.trim()] = value;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Gemini API helpers
+// ---------------------------------------------------------------------------
+
+function geminiPost(model, payload) {
+  const apiKey = process.env.GEMINI_API_KEY;
+  if (!apiKey) throw new Error("GEMINI_API_KEY is not set");
+
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify(payload);
+    const url  = new URL(`${API_BASE}/${model}:generateContent?key=${apiKey}`);
+    const req  = https.request({
+      hostname: url.hostname, path: url.pathname + url.search,
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
+    }, res => {
+      let data = "";
+      res.on("data", c => data += c);
+      res.on("end", () => {
+        if (res.statusCode !== 200) return reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+        resolve(JSON.parse(data));
+      });
+    });
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+function geminiGet(path_) {
+  const apiKey = process.env.GEMINI_API_KEY;
+  return new Promise((resolve, reject) => {
+    const url = new URL(`https://generativelanguage.googleapis.com/v1beta/${path_}?key=${apiKey}&pageSize=50`);
+    https.get(url.toString(), res => {
+      let data = "";
+      res.on("data", c => data += c);
+      res.on("end", () => resolve(JSON.parse(data)));
+    }).on("error", reject);
+  });
+}
+
+async function askGemini({ prompt, model, files = [] }) {
+  const usedModel = model || DEFAULT_MODEL;
+
+  const fileParts = files.map(f => {
+    try {
+      const text = fs.readFileSync(f, "utf8");
+      return `### FILE: ${f}\n\`\`\`ruby\n${text}\n\`\`\``;
+    } catch {
+      return `### FILE: ${f}\n(could not read file)`;
+    }
+  });
+
+  const parts = [SYSTEM_PREAMBLE, ""];
+  if (fileParts.length) { parts.push("## Files provided for context\n"); parts.push(...fileParts, ""); }
+  parts.push("## Task\n", prompt.trim());
+  const fullPrompt = parts.join("\n");
+
+  const result = await geminiPost(usedModel, {
+    contents: [{ parts: [{ text: fullPrompt }] }],
+    generationConfig: { temperature: 0.2, maxOutputTokens: 8192 }
+  });
+
+  const text = result?.candidates?.[0]?.content?.parts?.[0]?.text;
+  if (!text) throw new Error(`Unexpected response: ${JSON.stringify(result)}`);
+  return `${text}\n\n---\n*Model: ${usedModel} | Files: ${files.length}*\n⚠️ Always verify Gemini's claims against actual code.`;
+}
+
+async function listModels() {
+  const result = await geminiGet("models");
+  const models = (result.models || [])
+    .filter(m => m.name?.includes("gemini") && m.supportedGenerationMethods?.includes("generateContent"))
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(m => `• ${m.name.replace("models/", "").padEnd(42)} ${m.displayName || ""}`)
+    .join("\n");
+  return `Available Gemini models:\n\n${models}`;
+}
+
+// ---------------------------------------------------------------------------
+// MCP protocol (JSON-RPC 2.0 over stdio)
+// ---------------------------------------------------------------------------
+
+const TOOLS = [
+  {
+    name: "ask_gemini",
+    description: "Send a prompt (optionally with file context) to Gemini and get a response. Use for large-context analysis, code review, refactoring advice, and cycle-end reviews.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "The question or instruction for Gemini" },
+        files:  { type: "array", items: { type: "string" }, description: "Optional file paths to include as context" },
+        model:  { type: "string", description: `Gemini model to use (default: ${DEFAULT_MODEL})` }
+      },
+      required: ["prompt"]
+    }
+  },
+  {
+    name: "list_gemini_models",
+    description: "List all Gemini models available for your API key.",
+    inputSchema: { type: "object", properties: {} }
+  }
+];
+
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+
+function respond(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+
+function respondError(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+async function handle(msg) {
+  const { id, method, params } = msg;
+
+  if (method === "initialize") {
+    return respond(id, {
+      protocolVersion: "2024-11-05",
+      serverInfo: { name: "gemini-mcp", version: "1.0.0" },
+      capabilities: { tools: {} }
+    });
+  }
+
+  if (method === "tools/list") {
+    return respond(id, { tools: TOOLS });
+  }
+
+  if (method === "tools/call") {
+    const { name, arguments: args = {} } = params;
+    try {
+      let text;
+      if (name === "ask_gemini")        text = await askGemini(args);
+      else if (name === "list_gemini_models") text = await listModels();
+      else return respondError(id, -32601, `Unknown tool: ${name}`);
+      respond(id, { content: [{ type: "text", text }] });
+    } catch (err) {
+      respondError(id, -32000, err.message);
+    }
+    return;
+  }
+
+  if (method === "notifications/initialized") return; // no response needed
+  if (id != null) respondError(id, -32601, `Method not found: ${method}`);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+loadDotenv(path.join(process.cwd(), ".env"));
+
+rl.on("line", line => {
+  if (!line.trim()) return;
+  try { handle(JSON.parse(line)); }
+  catch { /* ignore parse errors */ }
+});
+
+process.stderr.write(`[gemini-mcp] ready (model: ${DEFAULT_MODEL})\n`);

data/.ai-assistance/skills/gemini-assist/gemini_ask.py

@@ -0,0 +1 @@
+# Superseded by gemini_ask.rb — please use that instead.