everything-gemini 1.2.0 → 1.9.0

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/milvus-vector-clustering/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: milvus-vector-clustering
+description: >-
+  Architects, scales, and optimizes Milvus distributed vector databases, HNSW/IVF-PQ indexing, hybrid dense-sparse search, dynamic schema partition keys, and scalar metadata filtering.
+---
+
+# Milvus Vector Clustering & Distributed Similarity Search
+
+This skill guides the design, indexing, and high-throughput querying of enterprise-scale vector collections using Milvus and Zilliz Cloud.
+
+---
+
+## ⚡ Indexing Selection Matrix
+
+| Index Type | Search Latency | Recall Rate | Memory Footprint | Best For |
+| :--- | :--- | :--- | :--- | :--- |
+| **`HNSW`** | Ultra-low (<5ms) | High (>98%) | High (in-memory graph) | Mission-critical search where latency is top priority. |
+| **`IVF_FLAT`** | Medium (10-30ms) | Tunable (nprobe) | Moderate | Standard baseline for medium datasets (<10M vectors). |
+| **`IVF_PQ`** | Low (5-15ms) | Moderate (85-92%) | Very Low (quantized) | Massive scale (100M+ vectors) with tight RAM budgets. |
+| **`SCANN`** | Very Low (<8ms) | High (>95%) | Moderate | High-dimensional CPU-accelerated similarity search. |
+| **`SPARSE_INVERTED_INDEX`**| Ultra-low | Exact / BM25 | Low | Sparse lexical vectors (SPLADE, BM25 hybrid ranking). |
+
+---
+
+## 🏗️ Production Collection Schema with Partition Keys
+
+Multi-tenant applications should leverage Milvus **Partition Keys** to isolate tenant data logically without exceeding physical partition limits:
+
+```python
+from pymilvus import (
+    connections, FieldSchema, CollectionSchema, DataType,
+    Collection, utility
+)
+
+# Connect to Milvus Cluster / Standalone
+connections.connect(alias="default", host="localhost", port="19530")
+
+fields = [
+    # Primary Key
+    FieldSchema(name="doc_id", dtype=DataType.VARCHAR, max_length=128, is_primary=True, auto_id=False),
+    
+    # Multi-tenant Partition Key (routes queries to physical partition clusters)
+    FieldSchema(name="tenant_id", dtype=DataType.VARCHAR, max_length=64, is_partition_key=True),
+    
+    # Scalar Metadata for Pre-filtering
+    FieldSchema(name="category", dtype=DataType.VARCHAR, max_length=64),
+    FieldSchema(name="created_at", dtype=DataType.INT64),
+    FieldSchema(name="is_archived", dtype=DataType.BOOL),
+    
+    # Dense Vector Embedding (e.g., text-embedding-004, 768 dimensions)
+    FieldSchema(name="dense_vector", dtype=DataType.FLOAT_VECTOR, dim=768),
+    
+    # Sparse Lexical Vector (e.g., SPLADE or BM25 tokens)
+    FieldSchema(name="sparse_vector", dtype=DataType.SPARSE_FLOAT_VECTOR),
+]
+
+schema = CollectionSchema(fields=fields, description="Enterprise Knowledge Base Vectors", enable_dynamic_field=True)
+collection = Collection(name="knowledge_embeddings", schema=schema)
+```
+
+---
+
+## 🔍 Building Vector Indexes
+
+Build indexes before loading the collection into memory:
+
+```python
+# 1. Dense Vector Index (HNSW for high recall & low latency)
+dense_index_params = {
+    "metric_type": "COSINE",
+    "index_type": "HNSW",
+    "params": {
+        "M": 16,               # Max outgoing links per node (16-64)
+        "efConstruction": 200  # Exploration factor during index build
+    }
+}
+collection.create_index(field_name="dense_vector", index_params=dense_index_params)
+
+# 2. Sparse Vector Index
+sparse_index_params = {
+    "metric_type": "IP",       # Inner Product for sparse lexical weights
+    "index_type": "SPARSE_INVERTED_INDEX",
+    "params": {"drop_ratio_build": 0.2}
+}
+collection.create_index(field_name="sparse_vector", index_params=sparse_index_params)
+
+# Load into query nodes
+collection.load()
+```
+
+---
+
+## 🚀 Hybrid Search with Reciprocal Rank Fusion (RRF)
+
+Combine dense semantic search with sparse lexical matching for optimal recall:
+
+```python
+from pymilvus import AnnSearchRequest, RRFRanker
+
+# Dense vector query request
+dense_req = AnnSearchRequest(
+    data=[query_dense_embedding],
+    anns_field="dense_vector",
+    param={"metric_type": "COSINE", "params": {"ef": 64}},
+    limit=50,
+    expr='tenant_id == "org_acme" and is_archived == false'
+)
+
+# Sparse vector query request
+sparse_req = AnnSearchRequest(
+    data=[query_sparse_dict],
+    anns_field="sparse_vector",
+    param={"metric_type": "IP", "params": {"drop_ratio_search": 0.1}},
+    limit=50,
+    expr='tenant_id == "org_acme" and is_archived == false'
+)
+
+# Execute hybrid search with RRF reranking
+results = collection.hybrid_search(
+    reqs=[dense_req, sparse_req],
+    rerank=RRFRanker(k=60),
+    limit=10,
+    output_fields=["doc_id", "category", "created_at"]
+)
+```
+
+---
+
+## 📋 Architectural Rules & Best Practices
+
+1. **Partition Key Limits**: Use `is_partition_key=True` for tenant routing; Milvus maps millions of logical tenants into ~64-256 physical partition clusters automatically.
+2. **Pre-Filtering Optimization**: Place high-selectivity scalar filters (`expr='category == "tech"'`) directly in the ANN search request to prune candidate sets before graph traversal.
+3. **Compaction Management**: Call `collection.compact()` after bulk insertions or deletions to merge small segment files and purge deleted entity tombstones.
+4. **Memory Sizing**: For HNSW, allocate approximately `(dim * 4 + M * 8) * num_vectors` bytes of RAM on QueryNodes.

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 |