@haposoft/cafekit 0.13.3 → 0.14.0

package/src/claude/hooks/spec-gate.cjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * Stop Hook — spec-gate.cjs
+ * Implements: https://docs.anthropic.com/en/docs/claude-code/hooks
+ *
+ * Blocks turn end when *newly-done* tasks lack a verification receipt.
+ * Block contract (exit 0 + stdout): {"decision":"block","reason":"..."}.
+ *
+ * Safety: stop_hook_active loop guard; runtime.spec.completion_gate=false
+ * escape hatch (missing key → ON); first-run seeds cache without blocking;
+ * crash → fail-open + hooks/.logs/hook-log.jsonl. Exit: 0 always.
+ */
+
+try {
+  const fs   = require('fs');
+  const path = require('path');
+
+  const stdin = fs.readFileSync(0, 'utf8').trim();
+  if (!stdin) process.exit(0);
+
+  const payload = JSON.parse(stdin);
+  const cwd     = payload.cwd || process.cwd();
+
+  // Never re-block a continuation caused by our own block (infinite-loop guard).
+  if (payload.stop_hook_active === true) process.exit(0);
+
+  // Missing/malformed runtime.json keeps the gate ON (fail-closed, valve 3 style).
+  let runtime = {};
+  try {
+    const rp = path.join(cwd, '.claude', 'runtime.json');
+    if (fs.existsSync(rp)) runtime = JSON.parse(fs.readFileSync(rp, 'utf8'));
+  } catch { /* gate stays on */ }
+  if (runtime.spec && runtime.spec.completion_gate === false) process.exit(0);
+
+  // Active-spec discovery — same rules as spec-state.cjs.
+  const baseDir   = process.env.PROJECT_ROOT || cwd;
+  const specsPath = path.join(baseDir, runtime.paths?.specs || 'specs');
+  if (!fs.existsSync(specsPath)) process.exit(0);
+
+  let activeSpec = null;
+  let featureName = null;
+  for (const entry of fs.readdirSync(specsPath, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const specFile = path.join(specsPath, entry.name, 'spec.json');
+    if (!fs.existsSync(specFile)) continue;
+    try {
+      const specData = JSON.parse(fs.readFileSync(specFile, 'utf8'));
+      if (specData.status === 'in_progress' || specData.status === 'in-progress') {
+        activeSpec = specData;
+        featureName = entry.name;
+        break;
+      }
+    } catch { /* skip bad JSON */ }
+  }
+  if (!activeSpec) process.exit(0);
+
+  const taskRegistry = activeSpec.task_registry || {};
+  const cacheFile = path.join(__dirname, '.logs', 'spec-gate-last.json');
+  const cacheExists = fs.existsSync(cacheFile);
+  let cache = {};
+  if (cacheExists) {
+    try { cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8')); } catch { cache = {}; }
+  }
+
+  const currentStatuses = {};
+  for (const [tp, task] of Object.entries(taskRegistry)) {
+    currentStatuses[tp] = task?.status || 'pending';
+  }
+
+  // First run: treat all current done as historical — seed cache, never block.
+  if (!cacheExists) {
+    try {
+      fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+      cache[featureName] = currentStatuses;
+      fs.writeFileSync(cacheFile, JSON.stringify(cache));
+    } catch { /* fail-open */ }
+    process.exit(0);
+  }
+
+  const featureCache = cache[featureName] || {};
+  // Newly done: status is done now AND cached status differs or is absent.
+  const newlyDone = Object.keys(taskRegistry).filter((tp) =>
+    (taskRegistry[tp]?.status || 'pending') === 'done' && featureCache[tp] !== 'done'
+  );
+  if (newlyDone.length === 0) process.exit(0);
+
+  // /m so ^ matches line starts (Evidence is never at byte 0 of the file).
+  const EVID_RE = /^#{2,3}\s+(Evidence|Task Test Plan & Verification Evidence|Verification & Evidence)\b/m;
+  const PROOF_RE = /(PASS|FAIL|exit code|passed|✓)/;
+
+  /** Body of first Evidence heading until next same-or-higher heading. */
+  function evidenceBody(text) {
+    const lines = text.split('\n');
+    let start = -1, level = 0;
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(/^(#{2,3})\s+(Evidence|Task Test Plan & Verification Evidence|Verification & Evidence)\b/);
+      if (m) { start = i + 1; level = m[1].length; break; }
+    }
+    if (start < 0) return null;
+    let end = lines.length;
+    for (let i = start; i < lines.length; i++) {
+      const hm = lines[i].match(/^(#{1,6})\s+/);
+      if (hm && hm[1].length <= level) { end = i; break; }
+    }
+    return lines.slice(start, end).join('\n');
+  }
+
+  // Receipt checks a–d → failed letter list.
+  // a: file + Status header has "done"; b: Evidence heading; c: no {{...}} + (fence|proof); d: completed_at
+  function checkReceipt(taskPath) {
+    const fails = [];
+    const abs = path.join(specsPath, featureName, taskPath);
+    if (!fs.existsSync(abs)) return ['a'];
+    let text = '';
+    try { text = fs.readFileSync(abs, 'utf8'); } catch { return ['a']; }
+
+    const statusLine = text.split('\n').find((l) => /^\s*(\*\*)?Status(\*\*)?\s*:/i.test(l));
+    if (!statusLine || !/\bdone\b/i.test(statusLine)) fails.push('a');
+
+    const body = evidenceBody(text);
+    if (body === null || !EVID_RE.test(text)) {
+      fails.push('b');
+    } else if (/\{\{[^}]+\}\}/.test(body) || !(/```/.test(body) || PROOF_RE.test(body))) {
+      fails.push('c');
+    }
+
+    const at = taskRegistry[taskPath]?.completed_at;
+    if (typeof at !== 'string' || at.trim() === '') fails.push('d');
+    return fails;
+  }
+
+  const failures = newlyDone
+    .map((tp) => ({ taskPath: tp, fails: checkReceipt(tp) }))
+    .filter((f) => f.fails.length > 0);
+
+  // Leave failing newly-done at old cache status so the gate re-fires next Stop.
+  try {
+    const nextFeature = { ...featureCache, ...currentStatuses };
+    for (const { taskPath } of failures) {
+      if (featureCache[taskPath] === undefined) delete nextFeature[taskPath];
+      else nextFeature[taskPath] = featureCache[taskPath];
+    }
+    cache[featureName] = nextFeature;
+    fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+    fs.writeFileSync(cacheFile, JSON.stringify(cache));
+  } catch { /* fail-open */ }
+
+  if (failures.length === 0) process.exit(0);
+
+  const lines = [
+    `⚠️ Completion gate: ${failures.length} newly-done task(s) lack a verification receipt.`,
+  ];
+  for (const { taskPath, fails } of failures) {
+    lines.push(`- \`${taskPath}\`: failed check(s) ${fails.join(', ')}`);
+    lines.push(
+      `  Fix: add a verification receipt to \`## Evidence\` in \`specs/${featureName}/${taskPath}\`: commands run + outcomes, then re-sync spec.json`
+    );
+  }
+  process.stdout.write(JSON.stringify({ decision: 'block', reason: lines.slice(0, 8).join('\n') }) + '\n');
+  process.exit(0);
+
+} catch (e) {
+  try {
+    const fs = require('fs'), p = require('path');
+    const d = p.join(__dirname, '.logs');
+    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+    fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
+      JSON.stringify({ ts: new Date().toISOString(), hook: 'spec-gate', status: 'crash', error: e.message }) + '\n');
+  } catch (_) {}
+  process.exit(0);
+}

package/src/claude/hooks/spec-state.cjs

@@ -98,26 +98,19 @@ try {
     fs.writeFileSync(cacheFile, stateKey);
   } catch { /* fail-open: if the write fails we still print the full block */ }
 
-  // Format the output
+  // Compact state-change block (enforcement lives on Stop via spec-gate.cjs).
   const lines = [];
   lines.push('');
-  lines.push('### 🔴 URGENT SYSTEM TOLLGATE (STATE SYNC) 🔴');
-  lines.push(`- **Active Feature:** \`${featureName}\``);
-  lines.push(`- **Current Phase:** \`${phase}\``);
-  if (taskEntries.length > 0) {
-    lines.push(`- **Task Registry:** \`${taskEntries.length} total | ${(taskCounts.done || 0)} done | ${(taskCounts.in_progress || 0)} in_progress | ${(taskCounts.blocked || 0)} blocked | ${(taskCounts.pending || 0)} pending\``);
-    if (nextUnblocked) {
-      lines.push(`- **Next Unblocked Task:** \`${nextUnblocked[0]}\``);
-    }
+  lines.push(`### Spec state changed: \`${featureName}\``);
+  lines.push(`- Phase: \`${phase}\` | Tasks: ${(taskCounts.done || 0)} done / ${taskEntries.length} total` +
+    (taskEntries.length > 0
+      ? ` (${(taskCounts.in_progress || 0)} in_progress, ${(taskCounts.pending || 0)} pending, ${(taskCounts.blocked || 0)} blocked)`
+      : ''));
+  if (nextUnblocked) {
+    lines.push(`- Next unblocked: \`${nextUnblocked[0]}\``);
   }
-  lines.push('');
-  lines.push(`> BẮT BUỘC (MANDATORY): Nếu bạn vừa hoàn thành một bước, bạn KHÔNG ĐƯỢC báo cáo "Đã xong" ngay.`);
-  lines.push(`> Bạn PHẢI sử dụng công cụ Edit để cập nhật trạng thái vật lý sau khi đã có bằng chứng verify thật (build/test/runtime/artifact), không phải chỉ vì code đã viết xong.`);
-  lines.push(`> 1. Sửa file \`spec.json\` (status, phase/current_phase, timestamps, \`task_files\`, \`task_registry\`, validation state nếu có thay đổi).`);
-  lines.push(`> 2. Chỉ khi verify xong mới sửa file \`tasks/task-*.md\` (status + tick '[x]' các sub-task và completion criteria liên quan).`);
-  lines.push(`> 3. Trước khi set \`ready_for_implementation = true\`, PHẢI chạy \`node .claude/scripts/validate-spec-output.cjs specs/${featureName}\` và sửa mọi lỗi.`);
-  lines.push(`> 4. NẾU VỪA HOÀN THÀNH 1 TASK CÓ SỬA SOURCE CODE, BẮT BUỘC cập nhật ngay tài liệu trong \`docs/\` (\`system-architecture.md\` hoặc Changelog) cho đồng bộ.`);
-  lines.push(`> CẤM VI PHẠM LUẬT TOLLGATE NÀY NHẰM ĐẢM BẢO TÍNH ĐỒNG BỘ CỦA HỆ THỐNG.`);
+  lines.push(`- Sync \`spec.json\` + task file after verified work; run \`node .claude/scripts/validate-spec-output.cjs specs/${featureName}\` before \`ready_for_implementation=true\`.`);
+  lines.push(`- A completion gate verifies receipts when you end a turn with newly-done tasks.`);
   lines.push('');
 
   console.log(lines.join('\n'));

package/src/claude/hooks/task-scaffold-guard.cjs

@@ -66,6 +66,9 @@ try {
   if (!fs.existsSync(scaffold)) process.exit(0);
 
   // Valve 2: block with an actionable message carrying the exact command.
+  // NOTE: deliberately does NOT mention the runtime.json escape hatch — an
+  // OpenCode smoke test proved the model reads the advertised override and
+  // simply disables the guard itself. The hatch stays functional for humans.
   const m = norm.match(/(^|\/)specs\/([^/]+)\/tasks\//);
   const feature = m ? m[2] : '<feature>';
   console.log(
@@ -73,8 +76,7 @@ try {
     `Blocked Write: ${filePath}\n\n` +
     `Generate the stub(s), then Edit-fill the {{...}} placeholders:\n` +
     `  node .claude/scripts/spec-scaffold.cjs ${feature} --tasks "R0-01-slug,R1-01-slug,..." --tasks-only\n` +
-    `Then use Edit (not Write) on each tasks/task-*.md stub.\n` +
-    `Override: set "spec": { "scaffold_guard": false } in .claude/runtime.json`
+    `Then use Edit (not Write) on each tasks/task-*.md stub.`
   );
   process.exit(2);
 

package/src/claude/migration-manifest.json

@@ -19,10 +19,8 @@
       "docx",
       "frontend-design",
       "frontend-development",
-      "generate-graph",
       "git",
       "hotfix",
-      "impact-analysis",
       "inspect",
       "mobile-development",
       "pdf",
@@ -60,7 +58,6 @@
       "validate-docs.cjs",
       "validate-docs-reconstruct.cjs",
       "generate-skill-catalog.cjs",
-      "browser-tool.cjs",
       "validate-spec-output.cjs"
     ]
   },
@@ -73,7 +70,10 @@
   "obsolete": {
     "runtimeFiles": [
       "hooks/skill-router.cjs",
-      "hooks/lib/skill-router-routes.cjs"
+      "hooks/lib/skill-router-routes.cjs",
+      "scripts/browser-tool.cjs",
+      "skills/generate-graph",
+      "skills/impact-analysis"
     ],
     "settingsHookCommandSubstrings": [
       "hooks/skill-router.cjs"
@@ -93,6 +93,7 @@
       "hooks/task-scaffold-guard.cjs",
       "hooks/rules.cjs",
       "hooks/spec-state.cjs",
+      "hooks/spec-gate.cjs",
       "hooks/state.cjs",
       "hooks/lib/color.cjs",
       "hooks/lib/parser.cjs",

package/src/claude/rules/skill-domain-routing.md

@@ -21,8 +21,7 @@ Use `/hapo:react-best-practices` for performance/re-render patterns. Use `/hapo:
 User wants to...
 ├── API, service, auth, database-backed feature          -> /hapo:backend-development
 ├── deployment, Docker, Kubernetes, Cloudflare, CI/CD     -> /hapo:devops
-├── mobile apps, iOS, Android, React Native, Flutter     -> /hapo:mobile-development
-└── impact of changing existing behavior                 -> /hapo:impact-analysis
+└── mobile apps, iOS, Android, React Native, Flutter     -> /hapo:mobile-development
 ```
 
 ## Codebase Understanding
@@ -32,7 +31,7 @@ User wants to...
 ├── answer questions from source code/docs/specs/config    -> /hapo:question
 ├── find files, locate code, scan project structure       -> /hapo:inspect
 ├── diagnose an error or failing check                    -> /hapo:debug
-├── understand possible side effects                      -> /hapo:impact-analysis
+├── understand possible side effects                      -> /hapo:inspect
 └── compare external approaches or best practices         -> /hapo:research
 ```
 

package/src/claude/rules/skill-workflow-routing.md

@@ -55,13 +55,13 @@ Do not turn reconstructed docs directly into implementation. Human review must a
 ## Research And Analysis Workflow
 
 ```text
-/hapo:inspect -> /hapo:impact-analysis -> /hapo:research
+/hapo:inspect -> /hapo:research
 ```
 
 | User intent | Suggested start |
 |---|---|
 | file discovery, codebase structure, source scouting | `/hapo:inspect` |
-| affected files, blast radius, dependency impact, side effects | `/hapo:impact-analysis` |
+| affected files, blast radius, dependency impact, side effects | `/hapo:inspect` |
 | external best practices, tool comparison, technical investigation | `/hapo:research` |
 
 Use `/hapo:research` for external knowledge. Use `/hapo:inspect` for local source truth.
@@ -70,7 +70,6 @@ Use `/hapo:research` for external knowledge. Use `/hapo:inspect` for local sourc
 
 | User intent | Suggested skill |
 |---|---|
-| diagrams, architecture maps, Mermaid/SVG/PNG graph output | `/hapo:generate-graph` |
 | PowerPoint or slide deck creation/editing | `/hapo:pptx` |
 | Word documents | `/hapo:docx` |
 | PDF processing | `/hapo:pdf` |

package/src/claude/rules/state-sync.md

@@ -25,3 +25,7 @@ Before returning control to the user or orchestrator, the agent **MUST**:
 **Canonical state values:** New specs MUST use `status: "in_progress"` for active work. Legacy `in-progress` may be read for compatibility, but must not be emitted in new files.
 
 **Golden Rule:** If the current phase changes, or a task completes, the agent must update the physical files. Never mark a task completed before there is execution proof, and never let `task_registry` disagree with the matching markdown task file. The context is intentionally NOT persisted in the chat to save tokens. An injected Hook (`spec-state.cjs`) constantly enforces and validates this state.
+
+### Completion gate (Stop)
+
+Marking a task `done` is now machine-gated on the **Stop** hook (`spec-gate.cjs`), not only reminded on each prompt. When a turn ends with *newly-done* tasks, the gate requires a verification receipt in each task markdown: `Status: done`, an Evidence section (or legacy `Task Test Plan & Verification Evidence` / `Verification & Evidence`) with real proof (no `{{...}}` placeholders; at least one fenced command block or PASS/FAIL line), and a non-empty `task_registry[path].completed_at`. First adoption (no cache yet) seeds history without blocking. Escape hatch for humans: `"spec": { "completion_gate": false }` in `.claude/runtime.json` (missing key keeps the gate ON).

package/src/claude/runtime.json

@@ -15,6 +15,10 @@
     "docs": "docs",
     "specs": "specs"
   },
+  "spec": {
+    "scaffold_guard": true,
+    "completion_gate": true
+  },
   "locale": {
     "thinkingLanguage": null,
     "responseLanguage": null

package/src/claude/scripts/validate-docs.cjs

@@ -53,17 +53,14 @@ function main() {
 
   const linkIssues = checkBrokenLinks(docsDir);
   if (linkIssues.length > 0) {
-    console.warn('\n⚠️ WARNING: CRITICAL HYPERLINK CORRUPTION DETECTED IN DOCUMENTATION MATRIX!');
+    console.error(`\n❌ FAIL: ${linkIssues.length} broken relative link(s) found:`);
     linkIssues.forEach(issue => {
-      console.warn(`- Compromised File: ${path.relative(process.cwd(), issue.file)} -> Links externally to Missing Null Pointer: ./${issue.brokenLink}`);
+      console.error(`- ${path.relative(process.cwd(), issue.file)} -> ./${issue.brokenLink} (target missing)`);
     });
-  } else {
-    console.log('✅ Validation verified! Zero broken integrity links detected across the system.');
+    process.exit(1);
   }
 
-  // Structural Note: To honor Execution Velocity patterns inherent to Architecture,
-  // aggressive deep-code grepping functions (function tracing) have been stripped.
-  // This ensures document validation pipeline triggers definitively under < 1s (Zero-latency verification).
+  console.log('✅ PASS: no broken relative links detected.');
 }
 
 main();

package/src/claude/scripts/validate-spec-output.cjs

@@ -203,11 +203,13 @@ function extractContractDefs(designText) {
 }
 
 /**
- * From a task body, return the contracts it claims plus the first fenced block
- * it carries (the task's local copy of the contract). Shape:
- *   { names: string[], block: string|null }
- * `names` come from a `Contracts: A, B` line; `block` is the first fenced code
- * block in the task (normalized) used to compare against the canonical defs.
+ * From a task body, return the contracts it claims plus its local contract
+ * copies. Shape: { names: string[], blocks: Map<name, string>, firstBlock: string|null }
+ * `names` come from a `Contracts: A, B` line. `blocks` maps every
+ * `<!-- contract:NAME -->` marker in the task to its fenced block, so a task
+ * carrying multiple contracts has EACH copy verified (not just the first).
+ * `firstBlock` keeps the legacy fallback for single-contract tasks that copy
+ * the block without repeating the marker.
  */
 function extractTaskContracts(taskText) {
   const names = [];
@@ -218,9 +220,10 @@ function extractTaskContracts(taskText) {
       if (name) names.push(name);
     }
   }
+  const blocks = extractContractDefs(taskText); // same marker+fence grammar as design.md
   const blockMatch = taskText.match(/```[^\n]*\n([\s\S]*?)\n```/);
-  const block = blockMatch ? normalizeBlock(blockMatch[1]) : null;
-  return { names, block };
+  const firstBlock = blockMatch ? normalizeBlock(blockMatch[1]) : null;
+  return { names, blocks, firstBlock };
 }
 
 function validateSpec(specDir) {
@@ -393,16 +396,33 @@ function validateSpec(specDir) {
     // (after whitespace normalization). This catches BE/FE drift like
     // user_name vs userName before integration.
     if (contractDefs.size > 0) {
-      const { names, block } = extractTaskContracts(content);
+      const { names, blocks, firstBlock } = extractTaskContracts(content);
       for (const name of names) {
         if (!contractDefs.has(name)) {
           errors.push(`${taskFile}: declares unknown contract "${name}" (not defined in design.md)`);
           continue;
         }
-        if (block !== null && block !== contractDefs.get(name)) {
+        // Prefer the task's marker-tagged copy for this contract; fall back to
+        // the first fenced block only for single-contract tasks (legacy format).
+        const localCopy = blocks.has(name)
+          ? blocks.get(name)
+          : (names.length === 1 ? firstBlock : null);
+        if (localCopy === null) {
+          if (names.length > 1) {
+            errors.push(`${taskFile}: contract "${name}" has no <!-- contract:${name} --> tagged block (multi-contract tasks must tag each copy)`);
+          }
+          continue;
+        }
+        if (localCopy !== contractDefs.get(name)) {
           errors.push(`${taskFile}: contract "${name}" body diverges from the canonical definition in design.md`);
         }
       }
+      // Marker-tagged blocks not declared on the Contracts: line are drift risks.
+      for (const taggedName of blocks.keys()) {
+        if (!names.includes(taggedName)) {
+          warnings.push(`${taskFile}: carries <!-- contract:${taggedName} --> block but does not declare it on the Contracts: line`);
+        }
+      }
     }
   }
 

package/src/claude/settings/settings.json

@@ -102,6 +102,10 @@
     "Stop": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/spec-gate.cjs\""
+          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/state.cjs\""

package/src/claude/skills/ai-multimodal/.env.example

@@ -41,16 +41,16 @@ GEMINI_API_KEY=your_api_key_here
 
 # --- Image Generation ---
 # Used by: --task generate (image)
-# Default: gemini-2.5-flash-image (Nano Banana Flash - fast, cost-effective)
+# Default: gemma-4-31b-it-image (Nano Banana Flash - fast, cost-effective)
 # Alternative: imagen-4.0-generate-001 (production quality)
 # NOTE: All image generation requires billing - no free tier available (limit: 0)
 # Options:
-#   gemini-2.5-flash-image            - Nano Banana Flash: fast, ~$1/1M tokens (DEFAULT)
-#   gemini-3-pro-image-preview        - Nano Banana Pro: 4K text, reasoning (requires billing)
+#   gemma-4-31b-it-image            - Nano Banana Flash: fast, ~$1/1M tokens (DEFAULT)
+#   gemma-4-31b-it-image-preview        - Nano Banana Pro: 4K text, reasoning (requires billing)
 #   imagen-4.0-generate-001           - Imagen 4 Standard: production quality (~$0.02/image)
 #   imagen-4.0-ultra-generate-001     - Imagen 4 Ultra: maximum quality (~$0.04/image)
 #   imagen-4.0-fast-generate-001      - Imagen 4 Fast: speed-optimized (~$0.01/image)
-# IMAGE_GEN_MODEL=gemini-2.5-flash-image
+# IMAGE_GEN_MODEL=gemma-4-31b-it-image
 
 # --- Video Generation ---
 # Used by: --task generate-video (new capability)
@@ -65,17 +65,15 @@ GEMINI_API_KEY=your_api_key_here
 
 # --- Multimodal Analysis ---
 # Used by: --task analyze, transcribe, extract
-# Default: gemini-2.5-flash
+# Default: gemma-4-31b-it
 # Options:
-#   gemini-3-pro-preview           - Latest, agentic workflows, 1M context
-#   gemini-2.5-flash               - Best price/performance (recommended)
-#   gemini-2.5-pro                 - Highest quality
-# MULTIMODAL_MODEL=gemini-2.5-flash
+#   gemma-4-31b-it                 - Best price/performance (recommended)
+# MULTIMODAL_MODEL=gemma-4-31b-it
 
 # --- Legacy Compatibility ---
 # Generic model override (use specific variables above instead)
-# GEMINI_MODEL=gemini-2.5-flash
-# GEMINI_IMAGE_GEN_MODEL=gemini-2.5-flash-image
+# GEMINI_MODEL=gemma-4-31b-it
+# GEMINI_IMAGE_GEN_MODEL=gemma-4-31b-it-image
 
 # ============================================================================
 # MiniMax API Configuration (Optional - for image/video/speech/music generation)
@@ -223,8 +221,8 @@ GEMINI_API_KEY=your_api_key_here
 # 5. Free tier limits: 15 RPM, 1M-4M TPM, 1,500 RPD
 # 6. Vertex AI requires GCP authentication via gcloud CLI
 # 7. Model defaults (Dec 2025):
-#    - Image gen: gemini-2.5-flash-image (Nano Banana Flash - default)
+#    - Image gen: gemma-4-31b-it-image (Nano Banana Flash - default)
 #    - Image gen: imagen-4.0-generate-001 (alternative for production)
 #    - Video gen: veo-3.1-generate-preview
-#    - Analysis: gemini-2.5-flash
+#    - Analysis: gemma-4-31b-it
 # 8. Preview models (veo-3.1, gemini-3) may have API changes

package/src/claude/skills/ai-multimodal/SKILL.md

@@ -43,7 +43,7 @@ export GEMINI_API_KEY_2="key2"  # auto-rotates on rate limit
 ## Models
 
 ### Google Gemini
-- **Analysis**: `gemma-4-31b-it` (recommended), `gemini-2.5-pro` (advanced)
+- **Analysis**: `gemma-4-31b-it` (recommended), `gemma-4-31b-it` (advanced)
 
 ## Scripts