docs(js/samples): add readmes for all samples

js/testapps/basic-gemini/README.md

@@ -0,0 +1,105 @@
+# Basic Gemini
+
+Comprehensive demo of the Google GenAI plugin — from basic generation to
+thinking modes, tool calling, structured output, multimodal, image generation,
+TTS, and advanced features like search grounding and URL context.
+
+## Features Demonstrated
+
+| Feature | Flow | Description |
+|---------|------|-------------|
+| Simple Generation | `basic-hi` | Basic text generation with Gemini |
+| Retry Middleware | `basic-hi-with-retry` | Generation with automatic retry on failure |
+| Fallback Middleware | `basic-hi-with-fallback` | Model fallback chain on failure |
+| Thinking (Pro) | `thinking-level-pro` | Chain-of-thought reasoning (Gemini 2.5 Pro) |
+| Thinking (Flash) | `thinking-level-flash` | Chain-of-thought reasoning (Gemini 2.5 Flash) |
+| Vision (Image) | `describe-image` | Describe a base64-encoded image |
+| YouTube Videos | `youtube-videos` | Transcribe YouTube video content |
+| Search Grounding | `search-grounding` | Web search for real-time info |
+| URL Context | `url-context` | Analyze content from web pages |
+| File Search (RAG) | `file-search` | Search uploaded documents |
+| Tool Calling | `toolCalling` | Streaming tool use (weather + unit conversion) |
+| Screenshot Tool | `screenshot-tool-calling` | Screenshot-based tool use |
+| Structured Tool Calling | `structured-tool-calling` | Tool calling with structured output |
+| Structured Output | `structured-output` | JSON output with Zod schema (RPG character) |
+| Thinking + Structured | `thinking-structured-output` | Structured output with thinking budget |
+| Media Resolution | `gemini-media-resolution` | Image editing with Gemini 2.5 Pro |
+| Image Generation | `nano-banana-pro` | Image generation with Gemini 2.5 Pro Image |
+| Imagen | `imagen-image-generation` | Image generation with Imagen 3 |
+| Text-to-Speech | `basic-tts` | Text-to-speech with Gemini 2.5 Flash |
+| Vertex AI | `basic-hi-vertexai` | Same features via Vertex AI backend |
+
+## Setup
+
+### Prerequisites
+
+- **Node.js** (v18 or higher)
+- **pnpm** package manager
+
+### How to Get Your Gemini API Key
+
+1. Visit [Google AI Studio](https://aistudio.google.com/).
+2. Click on "Get API key" and create a key in a new or existing Google Cloud project.
+
+For more details, check out the [official documentation](https://ai.google.dev/gemini-api/docs/api-key).
+
+```bash
+export GEMINI_API_KEY='<your-api-key>'
+```
+
+### Build and Install
+
+From the repo root:
+
+```bash
+pnpm install
+pnpm run setup
+```
+
+## Run the Sample
+
+### Google AI backend
+
+```bash
+pnpm run genkit:dev:googleai
+```
+
+### Vertex AI backend
+
+```bash
+pnpm run genkit:dev:vertexai
+```
+
+## Testing This Demo
+
+1. **Open DevUI** at http://localhost:4000
+
+2. **Test basic flows**:
+   - [ ] `basic-hi` — Simple greeting generation
+   - [ ] `basic-hi-with-retry` — Generation with retry middleware
+   - [ ] `basic-hi-with-fallback` — Fallback chain on model error
+
+3. **Test thinking modes**:
+   - [ ] `thinking-level-pro` — Input: `HIGH` (or `MINIMAL`, `LOW`, `MEDIUM`)
+   - [ ] `thinking-level-flash` — Input: `MINIMAL`, `LOW`, `MEDIUM`, or `HIGH`
+
+4. **Test multimodal**:
+   - [ ] `describe-image` — Image description from base64
+   - [ ] `youtube-videos` — YouTube video transcription
+
+5. **Test tools**:
+   - [ ] `toolCalling` — Weather tool with streaming
+   - [ ] `structured-tool-calling` — Tool calling with structured output
+
+6. **Test advanced features**:
+   - [ ] `search-grounding` — Web search grounding
+   - [ ] `url-context` — URL content analysis
+   - [ ] `file-search` — File search RAG
+   - [ ] `structured-output` — RPG character generation
+   - [ ] `imagen-image-generation` — Image generation
+
+7. **Expected behavior**:
+   - All flows complete without errors
+   - Streaming shows incremental output
+   - Structured output matches Zod schemas
+   - Tools are called and responses processed

js/testapps/context-caching/README.md

@@ -50,7 +50,7 @@ You can configure the API key in two ways:
 1. **Environment Variable**:
 
    ```bash
-   export GOOGLE_GENAI_API_KEY=your_api_key_here
+   export GEMINI_API_KEY=your_api_key_here
    ```
 
 2. **Inline Configuration** (for testing only, not recommended for production):

js/testapps/context-caching2/README.md

@@ -50,7 +50,7 @@ You can configure the API key in two ways:
 1. **Environment Variable**:
 
    ```bash
-   export GOOGLE_GENAI_API_KEY=your_api_key_here
+   export GEMINI_API_KEY=your_api_key_here
    ```
 
 2. **Inline Configuration** (for testing only, not recommended for production):

js/testapps/dev-ui-gallery/README.md

@@ -0,0 +1,66 @@
+# Dev UI Gallery
+
+Loads plugins and flows to demonstrate and test Genkit Dev UI features.
+
+This test app registers a wide variety of flows, prompts, and tools to
+exercise the Dev UI — including Firebase Functions-compatible flows,
+Dotprompt templates, custom tools, evaluators, and multiple vector store
+backends.
+
+## Features Demonstrated
+
+| Feature | Module | Description |
+|---------|--------|-------------|
+| Flows | `flows.ts` | Various generation flows (streaming, structured output, etc.) |
+| Firebase Functions | `flows-firebase-functions.ts` | Flows wrapped for Firebase Functions compatibility |
+| Dotprompt | `prompts.ts` | Prompt file templates with schemas |
+| Tools | `tools.ts` | Custom tools for model use |
+| Multiple Plugins | `genkit.ts` | Google AI, Vertex AI, Ollama, ChromaDB, Pinecone, Firebase |
+
+## Setup
+
+### Prerequisites
+
+- **Node.js** (v18 or higher)
+- **pnpm** package manager
+
+### API Keys
+
+```bash
+export GEMINI_API_KEY='<your-api-key>'
+```
+
+### Build and Install
+
+From the repo root:
+
+```bash
+pnpm install
+pnpm run setup
+```
+
+## Run the Sample
+
+```bash
+pnpm run genkit:dev
+```
+
+## Testing This Demo
+
+1. **Open DevUI** at http://localhost:4000
+
+2. **Verify UI features**:
+   - [ ] Flows panel lists all defined flows
+   - [ ] Prompts panel lists all Dotprompt templates
+   - [ ] Tools panel lists all defined tools
+   - [ ] Actions panel shows registered actions
+
+3. **Test flows**:
+   - [ ] Run various flows from the Dev UI
+   - [ ] Test streaming flows and verify incremental output
+   - [ ] Test structured output flows
+
+4. **Expected behavior**:
+   - All flows, prompts, and tools appear in the Dev UI
+   - Flows execute and return results
+   - Streaming shows incremental output

js/testapps/durable-streaming/README.md

@@ -0,0 +1,89 @@
+# Durable Streaming
+
+Demonstrates durable streaming with multiple stream manager backends —
+in-memory, Firestore, and Realtime Database. This allows clients to
+reconnect and resume consuming stream chunks even after disconnection.
+
+## Features Demonstrated
+
+| Feature | Flow | Description |
+|---------|------|-------------|
+| Basic Streaming | `streamy` | Counts to N, streaming each step |
+| Error Handling | `streamyThrowy` | Throws an error after 3 chunks |
+| In-Memory Backend | `/streamy` | Stream manager using in-memory storage |
+| Firestore Backend | `/streamyFirestore` | Stream manager backed by Cloud Firestore |
+| RTDB Backend | `/streamyRtdb` | Stream manager backed by Realtime Database |
+
+## Setup
+
+### Prerequisites
+
+- **Node.js** (v18 or higher)
+- **pnpm** package manager
+- **Firebase project** with Firestore and/or Realtime Database enabled
+
+### Build and Install
+
+From the repo root:
+
+```bash
+pnpm install
+pnpm run setup
+```
+
+### Firebase Configuration
+
+Set up Application Default Credentials for Firebase:
+
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS='/path/to/service-account-key.json'
+```
+
+Or use `gcloud`:
+
+```bash
+gcloud auth application-default login
+```
+
+## Run the Sample
+
+```bash
+pnpm build && pnpm start
+```
+
+The Express server starts on port `3500`.
+
+## Testing This Demo
+
+1. **Test in-memory streaming**:
+   ```bash
+   curl -X POST http://localhost:3500/streamy \
+     -H "Content-Type: application/json" \
+     -d '{"data": 5}'
+   ```
+
+2. **Test Firestore-backed streaming**:
+   ```bash
+   curl -X POST http://localhost:3500/streamyFirestore \
+     -H "Content-Type: application/json" \
+     -d '{"data": 5}'
+   ```
+
+3. **Test RTDB-backed streaming**:
+   ```bash
+   curl -X POST http://localhost:3500/streamyRtdb \
+     -H "Content-Type: application/json" \
+     -d '{"data": 5}'
+   ```
+
+4. **Test error handling**:
+   ```bash
+   curl -X POST http://localhost:3500/streamyThrowy \
+     -H "Content-Type: application/json" \
+     -d '{"data": 5}'
+   ```
+
+5. **Expected behavior**:
+   - `streamy` streams count objects `{count: 0}` through `{count: N-1}`
+   - `streamyThrowy` streams 3 chunks then throws an error
+   - All three backends (in-memory, Firestore, RTDB) behave identically

js/testapps/esm/README.md

@@ -0,0 +1,60 @@
+# ESM Compatibility Test
+
+Verifies that all Genkit packages and plugins can be imported and used in
+an ESM (ECMAScript Modules) project with `"type": "module"` in `package.json`.
+
+This is a build-time smoke test, not a runtime sample — it imports every
+plugin and core module to ensure there are no CommonJS/ESM interop issues.
+
+## Plugins Tested
+
+| Plugin | Import |
+|--------|--------|
+| `genkit` | Core library |
+| `@genkit-ai/google-genai` | Google AI + Vertex AI |
+| `@genkit-ai/googleai` | Legacy Google AI |
+| `@genkit-ai/vertexai` | Legacy Vertex AI (evaluation, model garden, rerankers) |
+| `@genkit-ai/firebase` | Firebase telemetry + context |
+| `@genkit-ai/google-cloud` | Google Cloud telemetry |
+| `@genkit-ai/express` | Express handler |
+| `@genkit-ai/next` | Next.js integration |
+| `@genkit-ai/mcp` | MCP client/server/host |
+| `@genkit-ai/evaluator` | Evaluation framework |
+| `@genkit-ai/dev-local-vectorstore` | Local vector store |
+| `@genkit-ai/checks` | Checks plugin |
+| `@genkit-ai/compat-oai` | OpenAI-compatible (OpenAI, DeepSeek, xAI) |
+| `genkitx-ollama` | Ollama |
+| `genkitx-chromadb` | ChromaDB |
+| `genkitx-pinecone` | Pinecone |
+| `genkitx-cloud-sql-pg` | Cloud SQL Postgres |
+
+## Setup
+
+### Prerequisites
+
+- **Node.js** (v18 or higher)
+- **pnpm** package manager
+
+### Build and Install
+
+From the repo root:
+
+```bash
+pnpm install
+pnpm run setup
+```
+
+## Run the Test
+
+```bash
+pnpm test
+```
+
+This builds the TypeScript and then runs the compiled output. If any
+ESM import fails, the process will exit with an error.
+
+## Expected Behavior
+
+- All imports resolve without errors
+- A simple `hello` flow is defined and can be invoked
+- `expressHandler` and `appRoute` wrappers work with the flow