@intentsolutionsio/jeremy-genkit-pro 2.1.0

package/commands/init-genkit-project.md

@@ -0,0 +1,356 @@
+---
+name: init-genkit-project
+description: Initialize a new Firebase Genkit project with best practices, proper...
+model: sonnet
+---
+# Initialize Genkit Project
+
+Initialize a production-ready Firebase Genkit project with proper structure, configuration, and best practices.
+
+## Step 1: Determine Project Language
+
+Ask the user to choose the target language:
+- **Node.js/TypeScript** (Genkit 1.0 - Stable, recommended for most use cases)
+- **Python** (Alpha - Early adopters, Python ecosystem integration)
+- **Go** (1.0 - High performance, backend services)
+
+## Step 2: Initialize Project Structure
+
+### For Node.js/TypeScript
+
+```bash
+# Create project directory
+mkdir my-genkit-app && cd my-genkit-app
+
+# Initialize npm project
+npm init -y
+
+# Install Genkit dependencies
+npm install genkit @genkit-ai/googleai @genkit-ai/firebase zod
+
+# Install dev dependencies
+npm install --save-dev typescript @types/node
+
+# Initialize TypeScript
+npx tsc --init
+```
+
+Create `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+Create `src/index.ts`:
+```typescript
+import { genkit, z } from 'genkit';
+import { googleAI, gemini25Flash } from '@genkit-ai/googleai';
+import { firebase } from '@genkit-ai/firebase';
+
+const ai = genkit({
+  plugins: [
+    googleAI({
+      apiKey: process.env.GOOGLE_API_KEY,
+    }),
+    firebase({
+      projectId: process.env.GOOGLE_CLOUD_PROJECT,
+    }),
+  ],
+  model: gemini25Flash,
+  enableTracingAndMetrics: true,
+});
+
+// Example flow
+const exampleFlow = ai.defineFlow(
+  {
+    name: 'exampleFlow',
+    inputSchema: z.object({
+      query: z.string(),
+    }),
+    outputSchema: z.object({
+      response: z.string(),
+    }),
+  },
+  async (input) => {
+    const { text } = await ai.generate({
+      model: gemini25Flash,
+      prompt: `You are a helpful assistant. Respond to: ${input.query}`,
+    });
+    return { response: text };
+  }
+);
+
+export { exampleFlow };
+```
+
+Create `package.json` scripts:
+```json
+{
+  "scripts": {
+    "dev": "genkit start -- tsx --watch src/index.ts",
+    "build": "tsc",
+    "deploy": "firebase deploy --only functions",
+    "genkit:dev": "genkit start"
+  }
+}
+```
+
+### For Python
+
+```bash
+# Create project directory
+mkdir my-genkit-app && cd my-genkit-app
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install Genkit
+pip install genkit google-generativeai
+
+# Create requirements.txt
+pip freeze > requirements.txt
+```
+
+Create `main.py`:
+```python
+from genkit import genkit
+from genkit.plugins import google_ai
+
+ai = genkit(
+    plugins=[
+        google_ai.google_ai(api_key=os.environ.get("GOOGLE_API_KEY"))
+    ],
+    model="gemini-2.5-flash"
+)
+
+@ai.flow
+async def example_flow(query: str) -> str:
+    """Example Genkit flow."""
+    response = await ai.generate(
+        model="gemini-2.5-flash",
+        prompt=f"You are a helpful assistant. Respond to: {query}"
+    )
+    return response.text
+
+if __name__ == "__main__":
+    import asyncio
+    result = asyncio.run(example_flow("Hello, Genkit!"))
+    print(result)
+```
+
+### For Go
+
+```bash
+# Create project directory
+mkdir my-genkit-app && cd my-genkit-app
+
+# Initialize Go module
+go mod init my-genkit-app
+
+# Install Genkit
+go get github.com/firebase/genkit/go/genkit
+go get github.com/firebase/genkit/go/plugins/googleai
+```
+
+Create `main.go`:
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "os"
+
+    "github.com/firebase/genkit/go/genkit"
+    "github.com/firebase/genkit/go/plugins/googleai"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Initialize Genkit with Google AI
+    if err := genkit.Init(ctx, &genkit.Config{
+        Plugins: []genkit.Plugin{
+            googleai.Plugin(&googleai.Config{
+                APIKey: os.Getenv("GOOGLE_API_KEY"),
+            }),
+        },
+    }); err != nil {
+        log.Fatal(err)
+    }
+
+    // Define a flow
+    genkit.DefineFlow("exampleFlow", func(ctx context.Context, query string) (string, error) {
+        response, err := genkit.Generate(ctx, &genkit.GenerateRequest{
+            Model: googleai.Gemini25Flash,
+            Prompt: genkit.Text(fmt.Sprintf("You are a helpful assistant. Respond to: %s", query)),
+        })
+        if err != nil {
+            return "", err
+        }
+        return response.Text(), nil
+    })
+
+    // Start Genkit server
+    if err := genkit.StartFlowServer(ctx, ""); err != nil {
+        log.Fatal(err)
+    }
+}
+```
+
+## Step 3: Environment Configuration
+
+Create `.env` file:
+```bash
+# Google API Key (for Google AI plugin)
+GOOGLE_API_KEY=your_api_key_here
+
+# Google Cloud Project (for Firebase/Vertex AI)
+GOOGLE_CLOUD_PROJECT=your-project-id
+
+# Environment
+NODE_ENV=development
+```
+
+Create `.env.example` (committed to git):
+```bash
+GOOGLE_API_KEY=
+GOOGLE_CLOUD_PROJECT=
+NODE_ENV=development
+```
+
+## Step 4: Project Structure
+
+Create recommended directory structure:
+
+```
+my-genkit-app/
+├── src/                    # Source code
+│   ├── flows/             # Flow definitions
+│   ├── tools/             # Tool definitions
+│   ├── retrievers/        # RAG retrievers
+│   └── index.ts           # Main entry point
+├── tests/                 # Test files
+├── .env                   # Environment variables (gitignored)
+├── .env.example           # Example env file (committed)
+├── .gitignore             # Git ignore
+├── tsconfig.json          # TypeScript config (for TS)
+├── package.json           # Dependencies (for Node.js)
+├── requirements.txt       # Dependencies (for Python)
+├── go.mod                 # Dependencies (for Go)
+└── README.md              # Project documentation
+```
+
+## Step 5: Configure Monitoring (Production)
+
+For Firebase deployment with AI monitoring:
+
+```bash
+# Install Firebase CLI
+npm install -g firebase-tools
+
+# Login to Firebase
+firebase login
+
+# Initialize Firebase
+firebase init
+
+# Select:
+# - Functions
+# - Enable AI monitoring (when prompted)
+```
+
+Update `firebase.json`:
+```json
+{
+  "functions": [
+    {
+      "source": ".",
+      "codebase": "default",
+      "runtime": "nodejs20",
+      "ai": {
+        "monitoring": {
+          "enabled": true
+        }
+      }
+    }
+  ]
+}
+```
+
+## Step 6: Local Development
+
+Start Genkit Developer UI:
+
+```bash
+# Node.js
+npm run genkit:dev
+
+# Python
+genkit start -- python main.py
+
+# Go
+genkit start -- go run .
+```
+
+Access UI at: `http://localhost:4000`
+
+## Step 7: Testing
+
+Create test file `tests/flows.test.ts`:
+```typescript
+import { describe, it, expect } from 'vitest';
+import { exampleFlow } from '../src/index';
+
+describe('exampleFlow', () => {
+  it('should respond to queries', async () => {
+    const result = await exampleFlow({ query: 'Hello!' });
+    expect(result.response).toBeDefined();
+    expect(result.response.length).toBeGreaterThan(0);
+  });
+});
+```
+
+## Best Practices Included
+
+✅ **Environment Variables**: Secure API key management
+✅ **TypeScript/Type Safety**: Strong typing for reliability
+✅ **Monitoring**: AI monitoring enabled for production
+✅ **Project Structure**: Organized codebase
+✅ **Testing**: Test framework configured
+✅ **Documentation**: README and code comments
+✅ **Git**: Proper .gitignore configuration
+
+## Next Steps
+
+After initialization:
+1. Review and customize the example flow
+2. Add your specific business logic
+3. Implement additional flows for your use case
+4. Configure production deployment
+5. Set up monitoring and alerting
+6. Test thoroughly before deploying
+
+## References
+
+- Genkit Documentation: https://genkit.dev/
+- Node.js Guide: https://genkit.dev/docs/get-started/
+- Python Guide: https://firebase.blog/posts/2025/04/genkit-python-go/
+- Go Guide: https://developers.googleblog.com/en/announcing-genkit-go-10/

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@intentsolutionsio/jeremy-genkit-pro",
+  "version": "2.1.0",
+  "description": "Firebase Genkit expert for production-ready AI workflows with RAG and tool calling",
+  "keywords": [
+    "firebase",
+    "genkit",
+    "ai-flows",
+    "rag",
+    "monitoring",
+    "gemini",
+    "vertex-ai",
+    "vector-search",
+    "production-ai",
+    "claude-code",
+    "claude-plugin",
+    "tonsofskills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremylongshore/claude-code-plugins-plus-skills.git",
+    "directory": "plugins/ai-ml/jeremy-genkit-pro"
+  },
+  "homepage": "https://tonsofskills.com/plugins/jeremy-genkit-pro",
+  "bugs": "https://github.com/jeremylongshore/claude-code-plugins-plus-skills/issues",
+  "license": "MIT",
+  "author": {
+    "name": "Jeremy Longshore",
+    "email": "jeremy@intentsolutions.io"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    ".claude-plugin",
+    "skills",
+    "commands",
+    "agents"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"console.log(\\\"\\\\n→ This npm package is a tracking/proof artifact. Install the plugin via:\\\\n  ccpi install jeremy-genkit-pro\\\\n  or /plugin install jeremy-genkit-pro@claude-code-plugins-plus in Claude Code\\\\n\\\")\""
+  }
+}

package/skills/genkit-production-expert/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: genkit-production-expert
+description: |
+  Build production Firebase Genkit applications including RAG systems, multi-step flows, and tool calling for Node.js/Python/Go. Deploy to Firebase Functions or Cloud Run with AI monitoring. Use when asked to "create genkit flow" or "implement RAG". Trigger with relevant phrases based on skill purpose.
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash(cmd:*)
+version: 2.1.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+effort: medium
+compatible-with: claude-code, codex, openclaw
+tags: [ai, deployment, monitoring, python]
+---
+# Genkit Production Expert
+
+## Overview
+
+Build production-grade Firebase Genkit applications including RAG systems, multi-step flows, and tool-calling agents for Node.js, Python, and Go. This skill covers the full lifecycle from project scaffolding and schema validation through flow implementation, local testing with the Genkit Developer UI, and deployment to Firebase Functions or Cloud Run with AI monitoring and OpenTelemetry tracing.
+
+## Prerequisites
+
+- Node.js 18+ (TypeScript), Python 3.10+ (Python), or Go 1.21+ (Go) runtime
+- Genkit CLI and core packages (`npm install genkit @genkit-ai/googleai` for TypeScript)
+- Google Cloud project with Vertex AI API enabled for Gemini model access
+- Firebase CLI for Firebase Functions deployments (`npm install -g firebase-tools`)
+- Zod (TypeScript), Pydantic (Python), or Go structs for input/output schema validation
+- Environment variables configured for API keys (never hardcoded; use Secret Manager)
+
+## Instructions
+
+1. Analyze the requirements to determine target language, flow complexity (simple, multi-step, or RAG), model selection (Gemini 2.5 Flash vs Pro), and deployment target
+2. Initialize the project structure with appropriate config files (`tsconfig.json`, `genkit.config.ts`, or equivalent)
+3. Install Genkit core, provider plugins, and schema validation dependencies
+4. Define input/output schemas using Zod, Pydantic, or Go structs to enforce type safety at runtime
+5. Implement the Genkit flow using `ai.defineFlow()` with model configuration, temperature tuning, and token limits
+6. Add tool definitions using `ai.defineTool()` with scoped schemas for each external capability the flow requires
+7. For RAG flows: implement a retriever using `ai.defineRetriever()` with embedding generation (text-embedding-gecko) and vector database integration
+8. Configure error handling for safety blocks (`SAFETY_BLOCK`), quota exceeded (`QUOTA_EXCEEDED`), and provider timeouts
+9. Enable OpenTelemetry tracing with custom span attributes for cost and latency tracking
+10. Test locally using the Genkit Developer UI, then deploy to Firebase Functions or Cloud Run with auto-scaling configuration
+
+See `${CLAUDE_SKILL_DIR}/references/how-it-works.md` for the phased workflow and `${CLAUDE_SKILL_DIR}/references/production-best-practices-applied.md` for the production checklist.
+
+## Output
+
+- Complete Genkit flow implementation with typed schemas and model bindings
+- Tool definitions with Zod/Pydantic-validated inputs and outputs
+- Retriever configuration for RAG flows (embeddings, vector search, context injection)
+- Deployment configuration: Firebase Functions (`firebase.json`) or Cloud Run service YAML
+- Monitoring setup: OpenTelemetry tracing, Firebase Console integration, alert policies
+- Cost optimization report: model selection rationale, token usage estimates, caching strategy
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `SAFETY_BLOCK` response | Model safety filters triggered on input or output | Review prompt content; adjust safety settings; add input sanitization before generation |
+| `QUOTA_EXCEEDED` | API rate limit or daily token quota reached | Implement exponential backoff with jitter; request quota increase; cache repeated prompts |
+| Schema validation failure | Runtime input does not match Zod/Pydantic schema | Add descriptive error messages to schema; validate inputs before calling `ai.generate()` |
+| Retriever returns empty results | Vector database query found no matches above similarity threshold | Lower similarity threshold; verify embeddings are indexed; check embedding model version match |
+| Deployment timeout | Cold start exceeds Firebase Functions 60s limit | Increase memory allocation; use Cloud Run for long-running flows; enable min instances > 0 |
+
+See `${CLAUDE_SKILL_DIR}/references/errors.md` for additional error scenarios.
+
+## Examples
+
+**Scenario 1: Question-Answering Flow** -- Create a Genkit flow using Gemini 2.5 Flash with Zod input/output schemas. Set temperature to 0.3 for factual responses. Deploy to Firebase Functions with token usage monitoring. Expected latency: under 2 seconds per query.
+
+**Scenario 2: RAG Document Search** -- Implement a retriever with text-embedding-gecko embeddings connected to Firestore vector search. Build a RAG flow that retrieves top-5 relevant documents, injects them as context, and generates grounded answers with source citations. Include context caching for repeated queries.
+
+**Scenario 3: Multi-Tool Agent** -- Define weather and calendar tools with typed schemas. Create an agent flow that routes user queries to appropriate tools, handles multi-turn conversations, and traces each tool execution for debugging. Deploy to Cloud Run with auto-scaling (2-10 instances).
+
+See `${CLAUDE_SKILL_DIR}/references/workflow-examples.md` for complete code examples.
+
+## Resources
+
+- [Firebase Genkit Documentation](https://firebase.google.com/docs/genkit) -- flows, tools, retrievers, deployment
+- [Genkit GitHub Repository](https://github.com/genkit-ai/genkit) -- source code and examples
+- [Zod Schema Library](https://zod.dev) -- TypeScript schema validation
+- [OpenTelemetry for Node.js](https://opentelemetry.io/docs/languages/js/) -- tracing and observability
+- Gemini model selection guide: Flash for throughput, Pro for reasoning quality
+- Context caching and token optimization strategies for cost management

package/skills/genkit-production-expert/references/ARD.md

@@ -0,0 +1,71 @@
+# ARD: Genkit Production Expert
+
+> Part of [Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)
+
+## System Context
+
+The Genkit Production Expert operates within a developer's project to create, configure, and deploy Firebase Genkit flows. It interacts with the local codebase for implementation and Google Cloud services for model access and deployment.
+
+```
+Developer Request
+       ↓
+[Genkit Production Expert]
+  ├── Reads: project config, existing flows, schemas
+  ├── Writes: flows, tools, retrievers, deploy config
+  └── Calls: genkit CLI, npm/pip, firebase deploy, gcloud
+       ↓
+Deployed Genkit Flow
+  ├── Firebase Functions / Cloud Run
+  ├── Gemini API (Vertex AI)
+  ├── Vector Search (Firestore)
+  └── OpenTelemetry Tracing
+```
+
+## Data Flow
+
+1. **Input**: User request specifying the flow type (simple/multi-step/RAG/agent), target language (TypeScript/Python/Go), model preference, and deployment target (Firebase Functions/Cloud Run)
+2. **Processing**: Scaffold project structure, define typed schemas, implement the flow with model bindings, add tool definitions or retrievers as needed, configure error handling and tracing, then deploy with auto-scaling parameters
+3. **Output**: Complete flow implementation with schemas, deployment configuration (firebase.json or Cloud Run YAML), monitoring setup (OpenTelemetry traces, Firebase Console integration), and cost optimization report
+
+## Key Design Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Schema-first design | Define Zod/Pydantic schemas before flow logic | Catches type errors at runtime boundaries, not deep inside flow execution |
+| Gemini 2.5 Flash default | Flash for throughput, Pro for complex reasoning | 10x cheaper than Pro; sufficient for most flow types; upgrade only when quality demands |
+| OpenTelemetry native | Built-in Genkit tracing over custom logging | Standard observability protocol; integrates with Cloud Monitoring without custom code |
+| Firebase Functions for simple flows | Functions over Cloud Run for single-purpose flows | Zero infrastructure management, automatic scaling, sub-second deployment |
+| Cloud Run for long flows | Cloud Run when execution exceeds 60s Functions limit | Configurable timeout up to 60 minutes; supports streaming responses |
+| Error categorization | Distinct handling for SAFETY_BLOCK, QUOTA_EXCEEDED, schema errors | Each error type needs different recovery: retry, fallback, or user notification |
+| Context caching for RAG | Cache embedding results for repeated document queries | Reduces token costs and latency for frequently accessed knowledge bases |
+
+## Tool Usage Pattern
+
+| Tool | Purpose |
+|------|---------|
+| Read | Inspect existing Genkit config, flow files, schema definitions, and package.json/requirements.txt |
+| Write | Create new flow files, schema definitions, retriever implementations, and deployment configs |
+| Edit | Patch existing flows to add tools, fix schemas, update model config, or add error handling |
+| Grep | Search for import patterns, model usage, schema references, and configuration values |
+| Glob | Discover project layout — flow files, test files, config files across the repository |
+| Bash(cmd:*) | Run genkit CLI, npm/pip install, firebase deploy, test execution, and gcloud commands |
+
+## Error Handling Strategy
+
+| Error Class | Detection | Recovery |
+|------------|-----------|----------|
+| SAFETY_BLOCK | Gemini response contains `finishReason: SAFETY` | Log the blocked content category; retry with adjusted safety settings or sanitized input |
+| QUOTA_EXCEEDED | 429 status or `RESOURCE_EXHAUSTED` error | Implement exponential backoff with jitter; queue requests; request quota increase |
+| Schema validation failure | Zod/Pydantic throws validation error before `ai.generate()` | Return descriptive error message identifying the invalid field; do not call the model |
+| Retriever empty results | Vector search returns zero documents above threshold | Lower similarity threshold; verify embeddings are indexed; check embedding model version |
+| Deployment timeout | Firebase Functions cold start exceeds 60s | Increase memory allocation (512MB+); set min instances > 0; migrate to Cloud Run for long flows |
+
+## Extension Points
+
+- Custom model providers: add non-Google providers (OpenAI, Anthropic) via Genkit's plugin system
+- Evaluation pipelines: integrate Genkit's `ai.evaluate()` for automated flow quality scoring
+- Context caching: add prompt caching for repeated queries to reduce token costs
+- Streaming responses: enable SSE streaming for chat-style flows on Cloud Run
+- Multi-flow orchestration: chain multiple flows using Genkit's flow-to-flow calling pattern
+- Custom retrievers: extend beyond Firestore vector search to Pinecone, Weaviate, or Elasticsearch
+- Cost dashboards: generate Cloud Monitoring dashboards specific to token usage and model cost per flow

package/skills/genkit-production-expert/references/PRD.md

@@ -0,0 +1,70 @@
+# PRD: Genkit Production Expert
+
+**Version:** 2.1.0
+**Author:** Jeremy Longshore <jeremy@intentsolutions.io>
+**Status:** Active
+**Marketplace:** [tonsofskills.com](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io)
+**Portfolio:** [jeremylongshore.com](https://jeremylongshore.com)
+
+---
+
+## Problem Statement
+
+Firebase Genkit applications require integrating multiple concerns — flow definition, schema validation, model configuration, tool calling, RAG retrieval, and deployment — across three languages (Node.js, Python, Go). Developers struggle to connect these pieces correctly: schemas don't match flow signatures, retrievers return empty results due to embedding mismatches, safety filters block legitimate content, and cold starts cause deployment timeouts. Without expert guidance, teams ship Genkit flows that lack type safety, monitoring, and cost controls.
+
+## Target Users
+
+| User | Context | Primary Need |
+|------|---------|-------------|
+| Backend Developer | Building a new AI feature with Genkit for a production app | Complete flow implementation with typed schemas, error handling, and deployment config |
+| AI Engineer | Implementing RAG with vector search and document retrieval | Retriever setup with embeddings, Firestore vector integration, and context caching |
+| Full-Stack Developer | Adding tool-calling agents to an existing Node.js/Python app | Tool definitions with validated schemas and multi-turn conversation support |
+| DevOps Engineer | Deploying Genkit flows to Firebase Functions or Cloud Run | Deployment configuration with auto-scaling, monitoring, and cost optimization |
+
+## Success Criteria
+
+1. Generate a complete Genkit flow with typed input/output schemas that passes validation without modification
+2. RAG flows return relevant documents with source citations on first implementation attempt
+3. Deployed flows have OpenTelemetry tracing and token usage monitoring configured out of the box
+4. Cold start time under 5 seconds for Firebase Functions deployments with appropriate memory allocation
+5. SAFETY_BLOCK errors handled gracefully with fallback response instead of crash
+6. Cost optimization applied: Flash model used by default, Pro only when explicitly needed
+
+## Functional Requirements
+
+1. Analyze requirements to determine target language, flow complexity (simple/multi-step/RAG), model selection, and deployment target
+2. Initialize project structure with proper config files (`tsconfig.json`, `genkit.config.ts`, or language equivalent)
+3. Define input/output schemas using Zod (TypeScript), Pydantic (Python), or Go structs for runtime type safety
+4. Implement Genkit flows using `ai.defineFlow()` with model configuration, temperature, and token limits
+5. Define tools using `ai.defineTool()` with scoped schemas for external capabilities
+6. For RAG: implement retrievers with `ai.defineRetriever()`, embedding generation, and vector database integration
+7. Configure error handling for safety blocks, quota exceeded, and provider timeouts
+8. Enable OpenTelemetry tracing with custom span attributes for cost and latency tracking
+9. Deploy to Firebase Functions or Cloud Run with auto-scaling configuration
+
+## Non-Functional Requirements
+
+- All API keys stored in Secret Manager; never hardcoded in source or environment variables
+- Schema validation must occur at runtime, not just compile time
+- Flows must handle `SAFETY_BLOCK` responses gracefully without crashing
+- Token usage must be tracked per-flow for cost attribution
+- Retry logic with exponential backoff for all model API calls
+- All flows must be testable locally via the Genkit Developer UI before deployment
+- Generated code must follow the conventions of the target language (TypeScript/Python/Go)
+
+## Dependencies
+
+- Node.js 18+ (TypeScript), Python 3.10+ (Python), or Go 1.21+ (Go) runtime
+- Genkit CLI and core packages (`genkit`, `@genkit-ai/googleai` for TypeScript)
+- Google Cloud project with Vertex AI API enabled for Gemini model access
+- Firebase CLI for Firebase Functions deployments
+- Zod, Pydantic, or Go structs for schema validation
+
+## Out of Scope
+
+- Infrastructure provisioning with Terraform (handled by genkit-infra-expert)
+- Fine-tuning or training custom models
+- Non-Google model providers (OpenAI, Anthropic) — Genkit supports them but this skill focuses on Google AI
+- Frontend UI development for chat interfaces
+- Custom embedding model training (uses pre-built text-embedding-gecko)
+- Multi-tenant architecture with per-user flow isolation

package/skills/genkit-production-expert/references/errors.md

@@ -0,0 +1,57 @@
+# Error Handling Reference
+
+## Genkit Flow Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `SAFETY_BLOCK` response | Model safety filters triggered on input or output | Review prompt content for policy violations; adjust safety settings in `GenerationConfig`; add input sanitization before `ai.generate()` |
+| `QUOTA_EXCEEDED` | API rate limit or daily token quota reached | Implement exponential backoff with jitter; request quota increase via Cloud Console; cache repeated prompts with TTL |
+| `ZodError: invalid input` | Runtime input does not match Zod schema | Add `.describe()` to schema fields for better error messages; validate inputs upstream before calling the flow |
+| `ZodError: invalid output` | Model output does not match expected output schema | Tighten the prompt to match schema structure; use `response_mime_type: application/json`; add a retry with rephrased prompt |
+
+## Retriever & RAG Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Empty retrieval results | Vector database query found no matches above similarity threshold | Lower the similarity threshold; verify documents are indexed with matching embedding model version; run `ai.index()` to re-index |
+| `Embedding dimension mismatch` | Retriever uses different embedding model than indexer | Ensure both indexer and retriever use the same embedder (e.g., `textEmbedding004`); re-index if model changed |
+| `Firestore findNearest: index not found` | Firestore vector index not created for the collection | Create a composite index with `gcloud firestore indexes composite create` including the embedding field |
+| Retriever returns stale documents | Indexed content was updated but embeddings were not regenerated | Implement an update pipeline that re-embeds documents on change; add `updatedAt` timestamps for cache invalidation |
+
+## Deployment Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Function timeout` on Firebase Functions | Cold start or flow execution exceeds 60s default limit | Increase `timeoutSeconds` in function config (max 540s for 2nd gen); set `minInstances: 1` to avoid cold starts; use Cloud Run for long-running flows |
+| `ENOMEM` or container OOM | Insufficient memory for model response processing | Increase memory allocation (`--memory 1Gi`); reduce `maxOutputTokens`; stream responses instead of buffering |
+| `ERR_MODULE_NOT_FOUND` in deployed function | Dependencies not bundled correctly | Verify `tsconfig.json` `outDir` matches function entry point; run `npm run build` before deploy; check `package.json` exports field |
+| `Cloud Run: service unavailable` after deploy | Health check fails during startup | Ensure the flow server binds to `0.0.0.0:$PORT`; add a health check endpoint at `/` or `/_ah/health` |
+
+## Model & Provider Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Model not found` | Model ID doesn't match provider format | Use `gemini25Flash` or `gemini25Pro` exports from `@genkit-ai/googleai`; don't use raw model strings unless explicitly supported |
+| `API key not valid` | Missing or expired Google AI API key | Set `GOOGLE_GENAI_API_KEY` env var; rotate keys periodically; use `gcloud secrets` for production |
+| `INVALID_ARGUMENT: max tokens exceeded` | Prompt plus expected output exceeds model context window | Reduce prompt size; summarize context; use retrieval to inject only relevant snippets |
+| Provider timeout | Network or API latency spike | Set `timeout` in generation config; implement circuit breaker pattern; add fallback to alternative model |
+
+## Local Development Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Genkit Developer UI won't start | Port 4000 already in use or missing `genkit` CLI | Kill process on port 4000 (`lsof -i :4000`); ensure `genkit` CLI is installed globally (`npm install -g genkit`) |
+| `tsx` not found | TypeScript execution tool not installed | Install `tsx` as dev dependency: `npm install -D tsx`; or use `npx tsx` |
+| Flow test hangs indefinitely | Async flow never resolves or rejects | Add timeout to test cases; verify all async branches have proper error handling; mock external API calls in tests |
+| `ECONNREFUSED` when testing flows | Flow server not running or wrong port | Start server with `npx genkit start -- tsx src/index.ts`; verify URL matches the flow server port (default 3400) |
+
+## Tracing & Monitoring Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| No traces appearing in Firebase Console | `enableTracingAndMetrics` not set or wrong project | Pass `enableTracingAndMetrics: true` in Genkit config; verify `GOOGLE_CLOUD_PROJECT` env var matches Firebase project |
+| Missing custom span attributes | Span not properly closed or attribute key rejected | Use OpenTelemetry-compliant attribute names; ensure spans are ended in `finally` blocks |
+| High cardinality warning in monitoring | Too many unique flow names or label values | Use parameterized flow names; avoid dynamic values in metric labels |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*