everything-gemini 1.2.0 → 1.8.0

package/skills/langgraph-orchestrator/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: langgraph-orchestrator
+description: >-
+  Designs and implements stateful multi-agent systems, cyclic graphs, persistent checkpoints, human-in-the-loop pauses, and streaming orchestration using LangGraph (Python/TypeScript).
+---
+
+# LangGraph Multi-Agent Orchestration & Stateful Graphs
+
+This skill guides the design, construction, and deployment of complex multi-agent architectures using LangGraph. It provides deterministic patterns for cyclic routing, persistent graph checkpointing, and human-in-the-loop (HITL) approval gates.
+
+---
+
+## ⚡ Core Concepts
+
+1. **State Graph (`StateGraph`)**: Typed dictionary or Pydantic state passed through graph nodes.
+2. **Nodes**: Discrete execution functions that receive current state and return state updates.
+3. **Edges & Conditional Edges**: Transition rules between nodes (deterministic or LLM-routed).
+4. **Checkpointers (`BaseCheckpointSaver`)**: Persists graph state across turns and enables time-travel debugging.
+5. **Human-in-the-Loop (`interrupt_before`)**: Pauses execution graph at critical checkpoints for human intervention.
+
+---
+
+## 🏗️ Production Implementation (Python)
+
+### 1. State Definition & Reducers (`state.py`)
+
+Define immutable state schemas with explicit reducer operators:
+
+```python
+from typing import Annotated, Sequence, TypedDict
+from langchain_core.messages import BaseMessage
+from langgraph.graph.message import add_messages
+
+class AgentState(TypedDict):
+    # add_messages reducer appends new messages rather than overwriting
+    messages: Annotated[Sequence[BaseMessage], add_messages]
+    sender: str
+    iteration_count: int
+    is_approved: bool
+    context_data: dict
+```
+
+---
+
+### 2. Multi-Agent Nodes & Graph Assembly (`graph.py`)
+
+```python
+from langgraph.graph import StateGraph, END, START
+from langgraph.checkpoint.memory import MemorySaver
+from langchain_core.messages import AIMessage, HumanMessage
+
+def researcher_node(state: AgentState) -> dict:
+    """Researches user inquiry and extracts factual grounding."""
+    # LLM invocation logic here
+    result = "Research findings: latency reduced by 40% via caching."
+    return {
+        "messages": [AIMessage(content=result, name="researcher")],
+        "sender": "researcher",
+        "iteration_count": state.get("iteration_count", 0) + 1,
+    }
+
+def reviewer_node(state: AgentState) -> dict:
+    """Validates research quality and enforces compliance."""
+    last_msg = state["messages"][-1].content
+    approved = "latency" in last_msg.lower()
+    return {
+        "messages": [AIMessage(content="Review complete.", name="reviewer")],
+        "sender": "reviewer",
+        "is_approved": approved,
+    }
+
+def human_approval_node(state: AgentState) -> dict:
+    """Node executed after human approval gate."""
+    return {"messages": [AIMessage(content="Action executed after sign-off.", name="human_gate")]}
+
+def router_condition(state: AgentState) -> str:
+    """Evaluate whether to loop or terminate."""
+    if state.get("is_approved", False):
+        return "human_approval"
+    if state.get("iteration_count", 0) >= 3:
+        return "abort"
+    return "researcher"
+
+# Build State Graph
+workflow = StateGraph(AgentState)
+
+# Add Nodes
+workflow.add_node("researcher", researcher_node)
+workflow.add_node("reviewer", reviewer_node)
+workflow.add_node("human_approval", human_approval_node)
+
+# Add Edges
+workflow.add_edge(START, "researcher")
+workflow.add_edge("researcher", "reviewer")
+workflow.add_conditional_edges(
+    "reviewer",
+    router_condition,
+    {
+        "human_approval": "human_approval",
+        "researcher": "researcher",
+        "abort": END,
+    }
+)
+workflow.add_edge("human_approval", END)
+
+# Compile with Persistent Checkpointer and Human-in-the-Loop Interruption
+checkpointer = MemorySaver()
+app = workflow.compile(
+    checkpointer=checkpointer,
+    interrupt_before=["human_approval"]
+)
+```
+
+---
+
+### 3. Execution & Human-in-the-Loop Resumption
+
+```python
+thread_config = {"configurable": {"thread_id": "session-prod-1024"}}
+
+# Run until human interrupt
+inputs = {"messages": [HumanMessage(content="Optimize database latency.")], "iteration_count": 0}
+for event in app.stream(inputs, config=thread_config):
+    print(f"Step: {event}")
+
+# Inspect current snapshot before approval
+snapshot = app.get_state(thread_config)
+print(f"Next Node Pending Approval: {snapshot.next}")
+
+# Resume graph after human confirmation
+for event in app.stream(None, config=thread_config):
+    print(f"Post-approval Step: {event}")
+```
+
+---
+
+## 🛡️ Best Practices & Anti-Patterns
+
+| Category | ❌ Anti-Pattern | ✅ Production Best Practice |
+| :--- | :--- | :--- |
+| **State Mutation** | Modifying state objects in-place | Return clean partial state dictionaries with reducer keys |
+| **Cycles** | Unbounded recursive loops | Enforce explicit `iteration_count` or recursion limit (`recursion_limit=25`) |
+| **Checkpoints** | Storing giant binary blobs in state | Keep state lean; persist media in object stores (GCS/S3) and store URIs |
+| **HITL** | Hardcoded polling loops | Use native `interrupt_before` / `interrupt_after` with thread configurations |

package/skills/litellm-proxy-gateway/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: litellm-proxy-gateway
+description: >-
+  Enterprise LLM proxy gateway architecture using LiteLLM, multi-provider routing (Gemini, Claude, OpenAI, vLLM), virtual keys, budget tracking, fallback cascading, and rate-limiting. Use when centralizing LLM API access, managing cost quotas, or implementing resilient failover strategies.
+---
+
+# LiteLLM Proxy Gateway Architecture
+
+A production runbook for centralizing, securing, and load-balancing LLM inference across multi-provider deployments (Google Gemini, Anthropic, OpenAI, local vLLM) using **LiteLLM Proxy**.
+
+---
+
+## 🎯 Architectural Principles
+
+1. **Unified API Gateway**: Exposes a standard OpenAI-compatible API (`/v1/chat/completions`, `/v1/embeddings`) for 100+ LLM providers.
+2. **Resilient Fallback Cascades**: Automatically catches rate limits (`429`) or provider outages (`5xx`) and retries the prompt on configured fallback models.
+3. **Budget Controls & Virtual Keys**: Issues team-specific API keys with enforce-able spending caps, RPM/TPM rate limits, and model access whitelists.
+4. **Token Usage & Cost Attribution**: Centralizes Prometheus metrics, OTEL telemetry, and audit logs per team, project, or key.
+
+---
+
+## 🚀 Gateway Configuration (`config.yaml`)
+
+```yaml
+model_list:
+  # Primary: Gemini 2.5 Flash
+  - model_name: production-fast
+    litellm_params:
+      model: gemini/gemini-2.5-flash
+      api_key: "os.environ/GEMINI_API_KEY"
+      rpm: 1000
+      tpm: 1000000
+
+  # Fallback: OpenAI GPT-4o-mini
+  - model_name: production-fast-fallback
+    litellm_params:
+      model: gpt-4o-mini
+      api_key: "os.environ/OPENAI_API_KEY"
+      rpm: 500
+
+  # High-Reasoning: Gemini 2.5 Pro with Claude 3.5 Sonnet Fallback
+  - model_name: high-reasoning
+    litellm_params:
+      model: gemini/gemini-2.5-pro
+      api_key: "os.environ/GEMINI_API_KEY"
+
+  - model_name: high-reasoning-fallback
+    litellm_params:
+      model: anthropic/claude-3-5-sonnet-20241022
+      api_key: "os.environ/ANTHROPIC_API_KEY"
+
+router_settings:
+  routing_strategy: "latency-based-routing" # options: simple-shuffle, least-busy, latency-based-routing
+  redis_host: "redis.internal"
+  redis_port: 6379
+  redis_password: "os.environ/REDIS_PASSWORD"
+  num_retries: 3
+  timeout: 45
+  fallbacks:
+    - production-fast: ["production-fast-fallback"]
+    - high-reasoning: ["high-reasoning-fallback"]
+
+general_settings:
+  master_key: "os.environ/LITELLM_MASTER_KEY"
+  database_url: "os.environ/DATABASE_URL" # PostgreSQL for virtual keys & spend logs
+```
+
+---
+
+## 🐳 Docker Production Deployment
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+
+services:
+  litellm:
+    image: ghcr.io/berriai/litellm:main-latest
+    ports:
+      - "4000:4000"
+    volumes:
+      - ./config.yaml:/app/config.yaml
+    environment:
+      - GEMINI_API_KEY=${GEMINI_API_KEY}
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+      - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY}
+      - DATABASE_URL=postgresql://litellm:${DB_PASS}@postgres:5432/litellm_db
+    command: ["--config", "/app/config.yaml", "--port", "4000", "--workers", "4"]
+```
+
+---
+
+## 🔑 Virtual Key Management (cURL / REST API)
+
+Generate isolated, budget-constrained virtual keys for distinct microservices or teams:
+
+```bash
+curl -X POST 'http://localhost:4000/key/generate' \
+  -H 'Authorization: Bearer sk-master-key-xyz' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "models": ["production-fast", "high-reasoning"],
+    "max_budget": 500.0,
+    "budget_duration": "30d",
+    "rpm_limit": 120,
+    "metadata": {
+      "team": "analytics-agents",
+      "environment": "production"
+    }
+  }'
+```
+
+---
+
+## 💻 Client Invocation (Python / OpenAI SDK)
+
+Applications interact with LiteLLM identically to native OpenAI endpoints:
+
+```python
+from openai import OpenAI
+
+# Connect to internal LiteLLM Proxy Gateway
+client = OpenAI(
+    base_url="http://localhost:4000/v1",
+    api_key="sk-team-analytics-virtual-key",
+)
+
+response = client.chat.completions.create(
+    model="production-fast", # Automatically routes to Gemini 2.5 Flash, falls back to GPT-4o-mini
+    messages=[
+        {"role": "system", "content": "You are a cloud infrastructure specialist."},
+        {"role": "user", "content": "Explain eBPF socket redirection performance."}
+    ],
+    temperature=0.3,
+)
+
+print(response.choices[0].message.content)
+```
+
+---
+
+## 🛡️ Production Health & Monitoring
+
+1. **Check Gateway Health**:
+   ```bash
+   curl http://localhost:4000/health
+   ```
+2. **Prometheus Metrics**:
+   - `litellm_deployment_latency_per_output_token`: Model latency breakdowns.
+   - `litellm_deployment_spend`: Real-time cumulative spend per model and key.
+   - `litellm_proxy_failed_requests`: Rate of fallback activations.
+3. **Automatic Circuit Breaking**:
+   - If a provider triggers 5 consecutive `500` or `503` errors, the router pauses traffic to that upstream for 60 seconds.

package/skills/nats-jetstream/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: nats-jetstream
+description: >-
+  Architects, publishes, and consumes ultra-low latency event streams with NATS JetStream, configuring stream retention, message deduplication, durable consumer groups, and KV buckets.
+---
+
+# NATS JetStream Architecture & High-Speed Event Streaming
+
+This skill guides building resilient, cloud-native event-driven architectures with NATS JetStream, delivering high throughput, sub-millisecond latencies, and at-least-once delivery semantics.
+
+---
+
+## ⚡ Core Concepts: Core NATS vs. JetStream
+
+| Feature | Core NATS | NATS JetStream |
+| :--- | :--- | :--- |
+| **Delivery Model** | At-most-once (Fire & Forget) | At-least-once / Exactly-once (via deduplication) |
+| **Persistence** | In-memory only (ephemeral) | File / Memory persistent disk storage |
+| **Consumer State**| None (real-time listeners only)| Durable cursors with acknowledgments & replays |
+| **Flow Control** | TCP backpressure only | Consumer ack wait, max deliver limits, backoffs |
+
+---
+
+## 🏗️ Stream Definition & Deduplication (TypeScript)
+
+Configure streams with subject patterns and deduplication windows:
+
+```typescript
+import { connect, JSONCodec, RetentionPolicy, StorageType } from 'nats';
+
+const nc = await connect({ servers: process.env.NATS_URL || 'localhost:4222' });
+const jsm = await nc.jetstreamManager();
+const jc = JSONCodec();
+
+// Create or update stream
+await jsm.streams.add({
+  name: 'ORDERS',
+  subjects: ['orders.>'],
+  storage: StorageType.File,
+  retention: RetentionPolicy.Limits,
+  max_age: 7 * 24 * 60 * 60 * 1e9, // 7 days in nanoseconds
+  duplicate_window: 120 * 1e9,      // 2 minutes deduplication window
+});
+```
+
+---
+
+## 📤 Publishing with Message Deduplication
+
+Provide a unique `Nats-Msg-Id` header to guarantee idempotent delivery even during network retries:
+
+```typescript
+import { headers } from 'nats';
+
+const js = nc.jetstream();
+
+export async function publishOrderEvent(orderId: string, payload: Record<string, any>) {
+  const h = headers();
+  // Server drops duplicates published with the same ID within the duplicate_window
+  h.append('Nats-Msg-Id', `order-${orderId}-${payload.status}`);
+
+  const ack = await js.publish(`orders.${payload.region}.${orderId}`, jc.encode(payload), {
+    headers: h,
+  });
+
+  return ack.seq;
+}
+```
+
+---
+
+## 📥 Durable Pull Consumers (High-Throughput Worker Pools)
+
+Pull consumers give workers complete control over processing speed and batch sizes:
+
+```typescript
+import { AckPolicy } from 'nats';
+
+export async function startOrderWorker() {
+  const js = nc.jetstream();
+
+  // Create or bind durable consumer
+  const consumer = await js.consumers.get('ORDERS', 'order-fulfillment-workers');
+
+  while (true) {
+    // Pull up to 25 messages, waiting at most 2 seconds
+    const batch = await consumer.fetch({ max_messages: 25, expires: 2000 });
+
+    for await (const msg of batch) {
+      try {
+        const orderData = jc.decode(msg.data);
+        console.log(`Processing Order seq ${msg.seq}:`, orderData);
+
+        // Acknowledge successful processing
+        msg.ack();
+      } catch (err) {
+        // Negative acknowledgment: triggers redelivery based on backoff
+        msg.nak();
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🗄️ NATS Key-Value (KV) Buckets
+
+Use JetStream KV buckets for distributed application configuration and state:
+
+```typescript
+const kv = await js.views.kv('app-configuration');
+
+// Set configuration
+await kv.put('features.dark_mode', jc.encode({ enabled: true }));
+
+// Watch for real-time configuration changes across all pods
+const watcher = await kv.watch({ key: 'features.*' });
+for await (const entry of watcher) {
+  console.log(`Config updated: ${entry.key} =`, jc.decode(entry.value));
+}
+```

package/skills/open-telemetry-tracing/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: open-telemetry-tracing
+description: >-
+  Architects and instruments distributed tracing, OTLP exporters, W3C traceparent propagation, custom span attributes, and metric correlations using OpenTelemetry (Node.js/Python).
+---
+
+# OpenTelemetry Distributed Tracing & Observability
+
+This skill guides the implementation of production-grade distributed tracing using the OpenTelemetry (OTel) standard, providing end-to-end request visibility across microservices, async event buses, and AI agent reasoning loops.
+
+---
+
+## ⚡ The Observability Triad in OpenTelemetry
+
+1. **Traces**: Directed acyclic graphs of spans tracking request lifecycles across process boundaries.
+2. **Context Propagation**: Standardized W3C `traceparent` HTTP headers (`00-<trace_id>-<span_id>-<flags>`).
+3. **Semantic Conventions**: Standardized attribute keys (`http.status_code`, `db.system`, `gen_ai.request.model`).
+
+---
+
+## 🏗️ Production Implementation (Node.js / TypeScript)
+
+### 1. SDK Initialization (`instrumentation.ts`)
+
+Must execute before any other application modules are imported:
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
+import { Resource } from '@opentelemetry/resources';
+import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+
+const sdk = new NodeSDK({
+  resource: new Resource({
+    [SEMRESATTRS_SERVICE_NAME]: 'agentic-gateway',
+    [SEMRESATTRS_SERVICE_VERSION]: '1.7.0',
+    'deployment.environment': process.env.NODE_ENV || 'production',
+  }),
+  traceExporter: new OTLPTraceExporter({
+    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://otel-collector:4318/v1/traces',
+    headers: {},
+  }),
+  instrumentations: [
+    getNodeAutoInstrumentations({
+      '@opentelemetry/instrumentation-fs': { enabled: false }, // Prevent span explosion
+    }),
+  ],
+});
+
+sdk.start();
+
+process.on('SIGTERM', () => {
+  sdk.shutdown()
+    .then(() => console.log('Tracing terminated'))
+    .finally(() => process.exit(0));
+});
+```
+
+---
+
+### 2. Custom Business & Agent Spans (`tracer.ts`)
+
+```typescript
+import { trace, SpanStatusCode, propagation, context } from '@opentelemetry/api';
+
+const tracer = trace.getTracer('agent-core', '1.7.0');
+
+export async function executeAgentReasoningStep<T>(
+  stepName: string,
+  modelName: string,
+  fn: () => Promise<T>
+): Promise<T> {
+  return tracer.startActiveSpan(
+    `agent.reasoning.${stepName}`,
+    {
+      attributes: {
+        'gen_ai.system': 'google-gemini',
+        'gen_ai.request.model': modelName,
+        'agent.step': stepName,
+      },
+    },
+    async (span) => {
+      try {
+        span.addEvent('llm_prompt_dispatched', { timestamp: Date.now() });
+        const result = await fn();
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+      } catch (error: any) {
+        span.recordException(error);
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: error?.message || 'Reasoning execution failed',
+        });
+        throw error;
+      } finally {
+        span.end();
+      }
+    }
+  );
+}
+
+/** Propagate traceparent to downstream HTTP calls */
+export function injectTraceHeaders(targetHeaders: Record<string, string>): void {
+  propagation.inject(context.active(), targetHeaders);
+}
+```
+
+---
+
+## 🐍 Python Implementation (`telemetry.py`)
+
+```python
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.trace import Status, StatusCode
+
+provider = TracerProvider(
+    resource=Resource.create({"service.name": "python-worker", "service.version": "1.7.0"})
+)
+processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="http://otel-collector:4318/v1/traces"))
+provider.add_span_processor(processor)
+trace.set_tracer_provider(provider)
+
+tracer = trace.get_tracer("worker-agent", "1.7.0")
+
+def run_workflow_step(task_id: str):
+    with tracer.start_as_current_span("worker.process_task") as span:
+        span.set_attribute("task.id", task_id)
+        try:
+            # Task logic here
+            span.set_status(Status(StatusCode.OK))
+        except Exception as exc:
+            span.record_exception(exc)
+            span.set_status(Status(StatusCode.ERROR, str(exc)))
+            raise
+```
+
+---
+
+## 🛡️ Best Practices & Guardrails
+
+| Category | ❌ Anti-Pattern | ✅ Production Best Practice |
+| :--- | :--- | :--- |
+| **Span Lifecycle** | Forgetting to invoke `span.end()` in error blocks | Wrap with `try / catch / finally` and call `span.end()` |
+| **High Cardinality** | Injecting user emails, passwords, or raw tokens into attributes | Use hashed IDs (`user_hash`), sanitize PII, follow semantic conventions |
+| **Context Leaks** | Starting detached spans without active parent context | Use `tracer.startActiveSpan()` to maintain parent-child hierarchy |
+| **Over-instrumentation** | Tracing every internal loop iteration or file read | Instrument service boundaries, external HTTP/DB calls, and workflow steps |

package/skills/playwright-visual-regression/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: playwright-visual-regression
+description: >-
+  Implements automated visual regression testing, pixelmatch snapshot diffing, cross-browser viewport matrices, dynamic element masking, and containerized baseline stability using Playwright.
+---
+
+# Playwright Visual Regression Testing & Snapshot Diffing
+
+This skill provides production standards for catching unintended UI regressions, CSS layout shifts, and visual anomalies across viewports using Playwright's native screenshot comparison engine.
+
+---
+
+## ⚡ The Golden Rules of Visual Testing
+
+1. **Deterministic Environment**: Always generate reference snapshots inside the same containerized Linux environment (`mcr.microsoft.com/playwright`) to avoid font rendering divergence between macOS and CI runners.
+2. **Mask Dynamic Elements**: Mask timestamps, avatars, animations, and non-deterministic text using Playwright's `mask` option.
+3. **Wait for Font & Network Idle**: Ensure web fonts and critical API payloads are loaded before capturing snapshots.
+4. **Strict Diff Thresholds**: Use `maxDiffPixelRatio: 0.01` (1% tolerance) to balance anti-aliasing tolerance against regression detection.
+
+---
+
+## 🏗️ Production Playwright Configuration (`playwright.config.ts`)
+
+```typescript
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/visual',
+  snapshotPathTemplate: '{testDir}/__snapshots__/{testFilePath}/{arg}{ext}',
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixelRatio: 0.01,
+      animations: 'disabled',
+      threshold: 0.2, // Pixel color sensitivity (0.0 to 1.0)
+    },
+  },
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    {
+      name: 'Desktop Chrome',
+      use: { ...devices['Desktop Chrome'], viewport: { width: 1440, height: 900 } },
+    },
+    {
+      name: 'Mobile Safari',
+      use: { ...devices['iPhone 14'], viewport: { width: 390, height: 844 } },
+    },
+    {
+      name: 'Tablet iPad',
+      use: { ...devices['iPad Pro 11'], viewport: { width: 834, height: 1194 } },
+    },
+  ],
+});
+```
+
+---
+
+## 🧪 Visual Test Implementation (`tests/visual/dashboard.spec.ts`)
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Dashboard Visual Regression Suite', () => {
+  test.beforeEach(async ({ page }) => {
+    // Navigate and stabilize network
+    await page.goto('/dashboard', { waitUntil: 'networkidle' });
+    
+    // Wait for custom web fonts to be completely rendered
+    await page.evaluate(() => document.fonts.ready);
+  });
+
+  test('full dashboard page layout matches baseline', async ({ page }) => {
+    // Dynamic locators that vary between test runs
+    const dynamicTimestamp = page.locator('[data-testid="last-sync-time"]');
+    const userAvatar = page.locator('[data-testid="user-avatar"]');
+
+    await expect(page).toHaveScreenshot('dashboard-main-view.png', {
+      fullPage: true,
+      mask: [dynamicTimestamp, userAvatar],
+      maskColor: '#1e293b',
+    });
+  });
+
+  test('component-level snapshot for modal dialog', async ({ page }) => {
+    await page.click('[data-testid="open-settings-modal"]');
+    const modal = page.locator('[role="dialog"]');
+    
+    await expect(modal).toBeVisible();
+    await expect(modal).toHaveScreenshot('settings-modal.png');
+  });
+});
+```
+
+---
+
+## 🐳 Containerized Snapshot Workflow (CI Stability)
+
+Run snapshots inside the official Playwright Docker container to prevent cross-platform font rendering diffs:
+
+```bash
+# 1. Update baseline snapshots inside Docker container
+docker run --rm --network host -v $(pwd):/work/ -w /work/ \
+  mcr.microsoft.com/playwright:v1.45.0-jammy \
+  npx playwright test --update-snapshots
+
+# 2. Run visual validation in CI
+docker run --rm --network host -v $(pwd):/work/ -w /work/ \
+  mcr.microsoft.com/playwright:v1.45.0-jammy \
+  npx playwright test
+```
+
+---
+
+## 📋 Checklist & Anti-Patterns
+
+| Category | ❌ Anti-Pattern | ✅ Production Best Practice |
+| :--- | :--- | :--- |
+| **Animation** | Taking snapshots with active CSS transitions | Set `animations: 'disabled'` in config |
+| **Flakiness** | Relying on `page.waitForTimeout(3000)` | Wait on `networkidle`, `document.fonts.ready`, and locator visibility |
+| **Scope** | Capturing entire page for minor widget changes | Use element locators: `expect(locator).toHaveScreenshot()` |
+| **OS Mismatch** | Committing macOS snapshots to run in Ubuntu CI | Generate reference snapshots with Docker container |