ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/scripts/token-logger.js

@@ -1,220 +0,0 @@
-#!/usr/bin/env node
-/**
- * token-logger.js
- *
- * Claude Code Stop hook — fires after every AI response turn.
- * Reads the session transcript, extracts token usage, accumulates weekly totals,
- * and warns when approaching the project's budget allocation.
- *
- * Wired in .claude/settings.json:
- *   "Stop": [{ "type": "command", "command": "node .ai-assistance/scripts/token-logger.js" }]
- *
- * Reads:  stdin (Stop event JSON with session_id, transcript_path, cwd)
- *         .ai-assistance/token-budget.json
- *         .ai-assistance/local/kpi/session-<id>.json  (running session state)
- *         .ai-assistance/local/kpi/weekly-<YYYY-WNN>.json  (weekly totals)
- *
- * Writes: .ai-assistance/local/kpi/session-<id>.json  (updated state)
- *         .ai-assistance/local/kpi/weekly-<YYYY-WNN>.json  (updated totals)
- *         .ai-assistance/local/kpi/sessions-<YYYY-WNN>.jsonl  (completed turns)
- */
-
-const fs   = require("fs");
-const path = require("path");
-const os   = require("os");
-
-// ── Helpers ────────────────────────────────────────────────────────────────
-
-function isoWeek(d) {
-  const jan4 = new Date(d.getFullYear(), 0, 4);
-  const startOfWeek = new Date(jan4);
-  startOfWeek.setDate(jan4.getDate() - ((jan4.getDay() + 6) % 7));
-  const weekNum = Math.ceil(((d - startOfWeek) / 86400000 + 1) / 7);
-  return `${d.getFullYear()}-W${String(weekNum).padStart(2, "0")}`;
-}
-
-function loadJson(p, fallback) {
-  try { return JSON.parse(fs.readFileSync(p, "utf8")); }
-  catch { return fallback; }
-}
-
-function saveJson(p, data) {
-  fs.mkdirSync(path.dirname(p), { recursive: true });
-  fs.writeFileSync(p, JSON.stringify(data, null, 2) + "\n", "utf8");
-}
-
-function appendJsonl(p, obj) {
-  fs.mkdirSync(path.dirname(p), { recursive: true });
-  fs.appendFileSync(p, JSON.stringify(obj) + "\n", "utf8");
-}
-
-// ── Extract token usage from transcript JSONL ──────────────────────────────
-
-function extractUsageFromTranscript(transcriptPath) {
-  if (!transcriptPath || !fs.existsSync(transcriptPath)) return null;
-
-  let inputTokens = 0, outputTokens = 0, cacheReadTokens = 0, cacheCreateTokens = 0;
-  let toolCalls = 0, turns = 0, found = false;
-
-  try {
-    const lines = fs.readFileSync(transcriptPath, "utf8").split("\n").filter(Boolean);
-    for (const line of lines) {
-      try {
-        const entry = JSON.parse(line);
-        // Extract usage from any entry that has it
-        const usage = entry.usage || entry.message?.usage;
-        if (usage) {
-          inputTokens      += usage.input_tokens              || 0;
-          outputTokens     += usage.output_tokens             || 0;
-          cacheReadTokens  += usage.cache_read_input_tokens   || 0;
-          cacheCreateTokens+= usage.cache_creation_input_tokens|| 0;
-          found = true;
-        }
-        // Count tool uses
-        if (entry.type === "tool_use" || entry.tool_name) toolCalls++;
-        // Count assistant turns
-        if (entry.role === "assistant" || entry.type === "assistant") turns++;
-      } catch { /* skip malformed lines */ }
-    }
-  } catch { return null; }
-
-  if (!found) return null;
-  return { inputTokens, outputTokens, cacheReadTokens, cacheCreateTokens, toolCalls, turns };
-}
-
-// ── Estimate tokens when transcript doesn't have usage data ───────────────
-
-function estimateFromTranscript(transcriptPath) {
-  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
-    return { inputTokens: 0, outputTokens: 0, toolCalls: 0, turns: 0, estimated: true };
-  }
-  let inputChars = 0, outputChars = 0, toolCalls = 0, turns = 0;
-  try {
-    const lines = fs.readFileSync(transcriptPath, "utf8").split("\n").filter(Boolean);
-    for (const line of lines) {
-      try {
-        const entry = JSON.parse(line);
-        const content = JSON.stringify(entry.content || entry.text || "");
-        if (entry.role === "user" || entry.type === "user")           { inputChars += content.length; }
-        if (entry.role === "assistant" || entry.type === "assistant") { outputChars += content.length; turns++; }
-        if (entry.type === "tool_use" || entry.tool_name)             { toolCalls++; inputChars += 500 * 4; }
-      } catch { /* skip */ }
-    }
-  } catch {}
-  return {
-    inputTokens:  Math.round(inputChars / 4),
-    outputTokens: Math.round(outputChars / 4),
-    cacheReadTokens: 0, cacheCreateTokens: 0,
-    toolCalls, turns, estimated: true
-  };
-}
-
-// ── Main ───────────────────────────────────────────────────────────────────
-
-async function main() {
-  let event = {};
-  try {
-    const raw = fs.readFileSync("/dev/stdin", "utf8");
-    event = JSON.parse(raw);
-  } catch { /* no stdin or parse error — use empty event */ }
-
-  const cwd            = event.cwd || process.cwd();
-  const sessionId      = event.session_id || `unknown-${Date.now()}`;
-  const transcriptPath = event.transcript_path;
-
-  const budgetFile  = path.join(cwd, ".ai-assistance", "token-budget.json");
-  const kpiDir      = path.join(cwd, ".ai-assistance", "local", "kpi");
-  const weekId      = isoWeek(new Date());
-  const sessionFile = path.join(kpiDir, `session-${sessionId}.json`);
-  const weeklyFile  = path.join(kpiDir, `weekly-${weekId}.json`);
-  const turnLogFile = path.join(kpiDir, `sessions-${weekId}.jsonl`);
-
-  const budget  = loadJson(budgetFile, {});
-  const project = (budget.project?.name || path.basename(cwd));
-  const priority= (budget.project?.priority || "medium");
-  const targetPct = (budget.weekly_quota?.target_utilization_pct || 75) / 100;
-  const warnAt    = (budget.session_logging?.warn_at_pct || 80) / 100;
-
-  // Extract usage from transcript
-  const transcriptUsage = extractUsageFromTranscript(transcriptPath)
-    || estimateFromTranscript(transcriptPath);
-
-  // Load previous session state (accumulate across turns in a session)
-  const prevSession = loadJson(sessionFile, {
-    session_id: sessionId, project, priority,
-    started_at: new Date().toISOString(),
-    week_id: weekId,
-    input_tokens: 0, output_tokens: 0,
-    cache_read_tokens: 0, cache_create_tokens: 0,
-    tool_calls: 0, turns: 0, estimated: false,
-  });
-
-  // Use transcript totals (they accumulate naturally) not deltas
-  const sessionNow = {
-    ...prevSession,
-    input_tokens:       transcriptUsage.inputTokens,
-    output_tokens:      transcriptUsage.outputTokens,
-    cache_read_tokens:  transcriptUsage.cacheReadTokens  || 0,
-    cache_create_tokens:transcriptUsage.cacheCreateTokens || 0,
-    tool_calls:         transcriptUsage.toolCalls,
-    turns:              transcriptUsage.turns,
-    estimated:          transcriptUsage.estimated || false,
-    last_updated_at:    new Date().toISOString(),
-  };
-
-  saveJson(sessionFile, sessionNow);
-
-  // Update weekly totals — replace session contribution (re-compute from sessions)
-  const weekly = loadJson(weeklyFile, { week_id: weekId, projects: {}, total_tokens: 0 });
-  const sessionTotal = sessionNow.input_tokens + sessionNow.output_tokens;
-  const prevContrib  = (weekly.projects[sessionId]?.tokens || 0);
-  weekly.projects[sessionId] = {
-    project, priority, tokens: sessionTotal,
-    tool_calls: sessionNow.tool_calls, turns: sessionNow.turns,
-    updated_at: new Date().toISOString()
-  };
-  weekly.total_tokens = Object.values(weekly.projects).reduce((s, p) => s + p.tokens, 0);
-  saveJson(weeklyFile, weekly);
-
-  // Log the turn to the weekly JSONL (for cross-session analysis)
-  appendJsonl(turnLogFile, {
-    ts: new Date().toISOString(), session_id: sessionId, project, priority, week_id: weekId,
-    turn_tokens: sessionTotal - prevContrib,
-    session_total_tokens: sessionTotal,
-    tool_calls: sessionNow.tool_calls,
-    estimated: sessionNow.estimated,
-  });
-
-  // ── Budget warnings ────────────────────────────────────────────────────
-
-  const totalTokens = budget.weekly_quota?.total_tokens;
-  if (totalTokens) {
-    const usedPct = weekly.total_tokens / totalTokens;
-    const targetTokens = totalTokens * targetPct;
-
-    // Priority-based soft allocation
-    const weights  = budget.project_allocation?.priority_weights || { high: 50, medium: 30, low: 20 };
-    const myWeight = (weights[priority] || 30) / 100;
-    const myBudget = totalTokens * targetPct * myWeight;
-    const myUsed   = Object.values(weekly.projects)
-      .filter(p => p.project === project)
-      .reduce((s, p) => s + p.tokens, 0);
-    const myPct = myBudget > 0 ? myUsed / myBudget : 0;
-
-    if (usedPct >= warnAt) {
-      process.stderr.write(
-        `\n[token-budget] ⚠  Week ${weekId}: ${Math.round(usedPct * 100)}% of quota used` +
-        ` (${weekly.total_tokens.toLocaleString()}/${totalTokens.toLocaleString()} tokens)` +
-        ` — target was ${Math.round(targetPct * 100)}%\n`
-      );
-    }
-    if (myPct >= warnAt) {
-      process.stderr.write(
-        `[token-budget] ⚠  Project "${project}" (${priority}): ${Math.round(myPct * 100)}% of allocation` +
-        ` (${myUsed.toLocaleString()}/${Math.round(myBudget).toLocaleString()} tokens)\n`
-      );
-    }
-  }
-}
-
-main().catch(() => { /* never crash the hook */ });

data/.ai-assistance/scripts/token-report.ts

@@ -1,158 +0,0 @@
-/**
- * token-report.ts
- *
- * Cross-project token usage report. Reads weekly session logs from all aligned
- * projects (via local/paths.md) and produces a management-ready summary.
- *
- * Usage:
- *   npx ts-node .ai-assistance/scripts/token-report.ts
- *   npx ts-node .ai-assistance/scripts/token-report.ts --week 2026-W24
- *   npx ts-node .ai-assistance/scripts/token-report.ts --format json
- *
- * Output: Markdown table (default) or JSON (--format json)
- * The report is printed to stdout — redirect to a file or pipe to your reporting tool.
- */
-
-import * as fs   from "fs";
-import * as path from "path";
-
-const SCRIPTS_DIR = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1"));
-const AI_DIR      = path.join(SCRIPTS_DIR, "..");
-const CWD         = path.join(AI_DIR, "..", "..");
-
-// ── Helpers ────────────────────────────────────────────────────────────────
-
-function isoWeek(d: Date): string {
-  const jan4 = new Date(d.getFullYear(), 0, 4);
-  const s = new Date(jan4); s.setDate(jan4.getDate() - ((jan4.getDay() + 6) % 7));
-  return `${d.getFullYear()}-W${String(Math.ceil(((d.getTime() - s.getTime()) / 86400000 + 1) / 7)).padStart(2, "0")}`;
-}
-
-function loadJson<T>(p: string, fb: T): T {
-  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return fb; }
-}
-
-interface ProjectPath { alias: string; localPath: string; }
-
-function loadProjectPaths(): ProjectPath[] {
-  const pathsFile = path.join(AI_DIR, "local", "paths.md");
-  if (!fs.existsSync(pathsFile)) return [{ alias: path.basename(CWD), localPath: CWD }];
-  const projects: ProjectPath[] = [];
-  const seen = new Set<string>();
-  for (const line of fs.readFileSync(pathsFile, "utf8").split("\n")) {
-    const m = line.match(/\|\s*`([^`]+)`\s*\|\s*`([^`]+)`/);
-    if (!m) continue;
-    const [, alias, rawPath] = m;
-    const localPath = rawPath.replace(/\//g, path.sep);
-    const real = fs.existsSync(localPath) ? fs.realpathSync(localPath) : localPath;
-    if (!seen.has(real) && fs.existsSync(localPath)) { projects.push({ alias, localPath }); seen.add(real); }
-  }
-  return projects.length ? projects : [{ alias: path.basename(CWD), localPath: CWD }];
-}
-
-interface WeeklyData {
-  week_id: string;
-  total_tokens: number;
-  projects: Record<string, { project: string; priority: string; tokens: number; tool_calls: number; turns: number; }>;
-}
-
-interface SessionTurn {
-  ts: string; session_id: string; project: string; priority: string;
-  week_id: string; turn_tokens: number; session_total_tokens: number;
-  tool_calls: number; estimated: boolean;
-}
-
-// ── Main ───────────────────────────────────────────────────────────────────
-
-const args    = process.argv.slice(2);
-const weekArg = args.includes("--week") ? args[args.indexOf("--week") + 1] : null;
-const format  = args.includes("--format") ? args[args.indexOf("--format") + 1] : "text";
-const weekId  = weekArg || isoWeek(new Date());
-
-const projects = loadProjectPaths();
-
-// Aggregate across all projects
-const byProject: Record<string, {
-  tokens: number; tool_calls: number; turns: number;
-  priority: string; sessions: number; estimated: number;
-}> = {};
-
-let grandTotal = 0;
-
-for (const { localPath } of projects) {
-  const kpiDir     = path.join(localPath, ".ai-assistance", "local", "kpi");
-  const weeklyFile = path.join(kpiDir, `weekly-${weekId}.json`);
-  const budget     = loadJson<any>(path.join(localPath, ".ai-assistance", "token-budget.json"), {});
-  const projectName= budget.project?.name || path.basename(localPath);
-  const priority   = budget.project?.priority || "medium";
-
-  if (!fs.existsSync(weeklyFile)) continue;
-
-  const weekly = loadJson<WeeklyData>(weeklyFile, { week_id: weekId, total_tokens: 0, projects: {} });
-
-  // Sum sessions for this project
-  let tokens = 0, toolCalls = 0, turns = 0, sessions = 0, estimated = 0;
-  for (const s of Object.values(weekly.projects)) {
-    if (s.project === projectName) {
-      tokens    += s.tokens;
-      toolCalls += s.tool_calls || 0;
-      turns     += s.turns || 0;
-      sessions++;
-    }
-  }
-
-  // Count estimated sessions from JSONL
-  const jsonl = path.join(kpiDir, `sessions-${weekId}.jsonl`);
-  if (fs.existsSync(jsonl)) {
-    const lines = fs.readFileSync(jsonl, "utf8").split("\n").filter(Boolean);
-    estimated = lines.filter(l => { try { return JSON.parse(l).estimated; } catch { return false; } }).length;
-  }
-
-  if (tokens > 0) {
-    byProject[projectName] = { tokens, tool_calls: toolCalls, turns, priority, sessions, estimated };
-    grandTotal += tokens;
-  }
-}
-
-if (format === "json") {
-  console.log(JSON.stringify({ week_id: weekId, grand_total_tokens: grandTotal, projects: byProject }, null, 2));
-  process.exit(0);
-}
-
-// ── Text report ────────────────────────────────────────────────────────────
-
-const sortedProjects = Object.entries(byProject)
-  .sort(([, a], [, b]) => b.tokens - a.tokens);
-
-console.log(`\n${"=".repeat(70)}`);
-console.log(`  Token Usage Report — ${weekId}`);
-console.log(`  Generated: ${new Date().toISOString().slice(0, 16)}`);
-console.log(`${"=".repeat(70)}\n`);
-console.log(`  Grand total: ${grandTotal.toLocaleString()} tokens across ${sortedProjects.length} project(s)\n`);
-
-console.log(`  ${"Project".padEnd(30)} ${"Priority".padEnd(10)} ${"Tokens".padStart(10)} ${"Share".padStart(7)} ${"Tool calls".padStart(12)} ${"Turns".padStart(6)}`);
-console.log(`  ${"-".repeat(78)}`);
-
-for (const [name, data] of sortedProjects) {
-  const share = grandTotal > 0 ? Math.round((data.tokens / grandTotal) * 100) : 0;
-  const est   = data.estimated > 0 ? " ~" : "  ";
-  console.log(`  ${name.padEnd(30)} ${data.priority.padEnd(10)} ${est}${data.tokens.toLocaleString().padStart(8)} ${`${share}%`.padStart(7)} ${data.tool_calls.toString().padStart(12)} ${data.turns.toString().padStart(6)}`);
-}
-
-console.log(`\n  ~ = some sessions used token estimation (transcript had no usage data)`);
-
-// Priority allocation analysis
-const targetPct = 75;
-const weights   = { high: 50, medium: 30, low: 20 };
-console.log(`\n  Priority allocation vs actuals (target utilization: ${targetPct}%):`);
-for (const priority of ["high", "medium", "low"]) {
-  const w = (weights as any)[priority];
-  const actual = Object.values(byProject)
-    .filter(p => p.priority === priority)
-    .reduce((s, p) => s + p.tokens, 0);
-  const actualPct = grandTotal > 0 ? Math.round((actual / grandTotal) * 100) : 0;
-  const projects  = Object.entries(byProject).filter(([, p]) => p.priority === priority).map(([n]) => n).join(", ") || "(none)";
-  console.log(`    ${priority.padEnd(8)} target ~${w}%  actual ${`${actualPct}%`.padStart(4)}  — ${projects}`);
-}
-
-console.log(`\n${"=".repeat(70)}\n`);

data/.ai-assistance/scripts/token-session-start.js

@@ -1,66 +0,0 @@
-#!/usr/bin/env node
-/**
- * token-session-start.js
- *
- * Claude Code SessionStart hook.
- * Checks current week's token usage, warns if over allocation,
- * and shows the budget status for this project.
- *
- * Wired in .claude/settings.json:
- *   "SessionStart": [{ "type": "command", "command": "node .ai-assistance/scripts/token-session-start.js" }]
- */
-
-const fs   = require("fs");
-const path = require("path");
-
-function isoWeek(d) {
-  const jan4 = new Date(d.getFullYear(), 0, 4);
-  const s = new Date(jan4); s.setDate(jan4.getDate() - ((jan4.getDay() + 6) % 7));
-  return `${d.getFullYear()}-W${String(Math.ceil(((d - s) / 86400000 + 1) / 7)).padStart(2, "0")}`;
-}
-function loadJson(p, fb) { try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return fb; } }
-
-async function main() {
-  let event = {};
-  try { event = JSON.parse(fs.readFileSync("/dev/stdin", "utf8")); } catch {}
-
-  const cwd     = event.cwd || process.cwd();
-  const weekId  = isoWeek(new Date());
-  const budget  = loadJson(path.join(cwd, ".ai-assistance", "token-budget.json"), {});
-  const weekly  = loadJson(path.join(cwd, ".ai-assistance", "local", "kpi", `weekly-${weekId}.json`), { total_tokens: 0, projects: {} });
-
-  const project  = budget.project?.name || path.basename(cwd);
-  const priority = budget.project?.priority || "medium";
-  const total    = budget.weekly_quota?.total_tokens;
-  const targetPct= (budget.weekly_quota?.target_utilization_pct || 75);
-
-  // My project's tokens this week across all sessions
-  const myTokens = Object.values(weekly.projects)
-    .filter(p => p.project === project)
-    .reduce((s, p) => s + p.tokens, 0);
-
-  const lines = [`\n[token-budget] Week ${weekId} | Project: ${project} (${priority})`];
-  lines.push(`  All projects this week: ${weekly.total_tokens.toLocaleString()} tokens`);
-  lines.push(`  This project this week: ${myTokens.toLocaleString()} tokens`);
-
-  if (total) {
-    const usedPct = Math.round((weekly.total_tokens / total) * 100);
-    const weights = budget.project_allocation?.priority_weights || { high: 50, medium: 30, low: 20 };
-    const myAlloc = Math.round(total * (targetPct / 100) * ((weights[priority] || 30) / 100));
-    const myPct   = myAlloc > 0 ? Math.round((myTokens / myAlloc) * 100) : 0;
-    lines.push(`  Week quota: ${usedPct}% used (target ${targetPct}%) | This project: ${myPct}% of ${myAlloc.toLocaleString()} alloc`);
-    if (usedPct >= targetPct) lines.push(`  !! Over weekly target — consider deferring low-priority work`);
-    if (myPct >= 90)          lines.push(`  !! This project near allocation limit`);
-  }
-
-  process.stderr.write(lines.join("\n") + "\n");
-
-  // Also run bridge-init if it exists
-  const bridgeInit = path.join(cwd, ".ai-assistance", "scripts", "bridge-init.sh");
-  if (fs.existsSync(bridgeInit)) {
-    const { execSync } = require("child_process");
-    try { execSync(`bash "${bridgeInit}"`, { stdio: "inherit" }); } catch {}
-  }
-}
-
-main().catch(() => {});

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

@@ -1,48 +0,0 @@
-# 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 +0,0 @@
-# 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.