everything-gemini 1.1.1 → 1.8.0

package/rules/paradigms/security-hardened.md

@@ -1,17 +1,60 @@
 # Security & Hardening Protocol
 
-Security rules enforced for all agent code generation and execution.
+Security rules and defensive engineering standards enforced for all agent code generation and execution across projects.
+
+---
 
 ## 1. Zero Secret Leakage
-- Never print, log, or commit API keys, tokens, certificates, or credentials.
-- Always load secrets via environment variables (`process.env`, `os.environ`).
-- Ensure `.env` files and secret patterns are listed in `.gitignore`.
+- **Never Commit Secrets**:
+  - Never print, log, or commit API keys, personal access tokens, private keys, or passwords.
+  - Always ingest sensitive configuration via environment variables (`process.env`, `os.environ`).
+- **Git & Artifact Sanitation**:
+  - Ensure `.env`, `.env.local`, `.pem`, and certificate files are explicitly listed in `.gitignore`.
+  - When creating demonstration snippets or documentation, use standardized redaction placeholders (e.g. `GEMINI_API_KEY="YOUR_GEMINI_API_KEY"`).
+
+---
 
 ## 2. Command & Injection Defense
-- Never execute shell commands by concatenating unsanitized user strings.
-- Always use parameterized queries for SQL/NoSQL databases to prevent SQL injection.
-- Validate paths with `path.resolve` and verify they remain within the authorized workspace directory to prevent directory traversal.
+- **Safe Process Spawning**:
+  - Never concatenate unvalidated user strings into shell commands.
+  - Avoid `shell: true` in Node.js `child_process.spawn`. Pass binary names and arguments as separate arrays:
+    ```javascript
+    // INSECURE: exec(`curl ${userInput}`)
+    // SECURE:
+    const { execFile } = require('child_process');
+    execFile('curl', ['--silent', sanitizedUrl]);
+    ```
+- **SQL & Query Injection**:
+  - Always use parameterized queries or type-safe ORM query builders (Prisma, Drizzle, SQLAlchemy). Never interpolate raw string variables into SQL statements.
+- **Path Traversal Guardrails**:
+  - Sanitize all file paths with `path.resolve` and verify that the target path begins with the authorized root directory:
+    ```javascript
+    const resolvedPath = path.resolve(authorizedDir, userFilename);
+    if (!resolvedPath.startsWith(path.resolve(authorizedDir))) {
+      throw new Error('Access denied: Path traversal attempt detected.');
+    }
+    ```
+
+---
+
+## 3. Cryptographic Hygiene
+- **Constant-Time Comparisons**:
+  - When comparing webhook signatures, API tokens, or password hashes, always use constant-time comparison utilities (`crypto.timingSafeEqual`) to eliminate timing attack vectors.
+- **Modern Cryptographic Primitives**:
+  - Use cryptographically secure pseudorandom number generators (`crypto.randomBytes` or `secrets.token_hex`). Never use `Math.random()` for security-critical values.
+
+---
+
+## 4. Prototype Pollution & Input Validation
+- **Deep Object Cloning**:
+  - Prevent prototype pollution by sanitizing keys against `__proto__`, `constructor`, and `prototype`.
+- **Strict Schema Parsing**:
+  - Validate all JSON payloads at HTTP route boundaries using schema validators (Zod, Pydantic, or TypeBox). Strip unknown properties before processing.
+
+---
 
-## 3. Dependency Security
-- Review new packages before adding them to `package.json` or `pyproject.toml`.
-- Run automated vulnerability audits (`npm audit`, `pip-audit`, `govulncheck`) on dependencies.
+## 5. Dependency Audit & Supply Chain Security
+- **Automated CVE Scans**:
+  - Run vulnerability audits (`npm audit`, `pip-audit`, `govulncheck`) on third-party dependencies before introducing new packages.
+- **Lockfile Enforcement**:
+  - Commit deterministic lockfiles (`package-lock.json`, `poetry.lock`) to ensure repeatable, tamper-evident builds.

package/rules/paradigms/tdd.md

@@ -1,19 +1,76 @@
 # Test-Driven Development (TDD) Protocol
 
-Enforce this workflow when developing features, fixing bugs, or refactoring code.
+Enforce this workflow whenever developing features, fixing bugs, or refactoring existing logic across the repository.
+
+---
 
 ## The TDD Iron Law
 
-> **Never write production code unless an existing test is currently failing because that code does not exist.**
+> **Never write production code unless an existing test is currently failing because that code does not exist or does not yet behave as expected.**
+
+---
+
+## 1. The Three Disciplined Phases
 
 ### Phase 1: RED (Reproduce & Specify)
-1. Write a minimal, focused unit or integration test describing the desired behavior or reproducing the reported bug.
-2. Run the test suite and verify that the test fails for the expected reason (not due to syntax or import errors).
+1. **Write the Failing Test First**:
+   - Write a minimal, focused unit or integration test describing the desired behavior or reproducing the reported bug.
+2. **Execute to Confirm Failure**:
+   - Run the test suite and verify that the test fails for the expected reason (e.g. `AssertionError: expected false to be true` or `Function not defined`, not due to unrelated compilation or import syntax errors).
 
 ### Phase 2: GREEN (Minimal Implementation)
-1. Write the absolute minimum production code required to make the failing test pass.
-2. Run the test suite and ensure all tests pass. Do not write premature optimizations or unrelated code.
+1. **Surgical Implementation**:
+   - Write the absolute minimum production code required to make the failing test pass.
+2. **Resist Premature Generalization**:
+   - Do not write speculative helper functions, premature optimizations, or unrelated features during the Green phase. Get to green as quickly and simply as possible.
+3. **Verify All Tests Pass**:
+   - Confirm that the new test passes AND all existing regression tests remain green.
 
 ### Phase 3: REFACTOR (Clean & Harden)
-1. Clean up duplicated logic, improve naming, extract helper functions, and enforce type safety.
-2. Re-run tests after every micro-refactor to ensure zero regressions.
+1. **Eliminate Duplication**:
+   - Clean up repeated logic, extract reusable helpers, and clarify variable naming.
+2. **Enforce Type Safety**:
+   - Tighten type annotations, interfaces, and parameter docstrings.
+3. **Zero Regression Guarantee**:
+   - Re-run the automated test suite after every refactoring edit. Never finalize a refactor while any test is failing.
+
+---
+
+## 2. Standardized Test Structure: AAA Pattern
+
+Every test case must follow the **Arrange-Act-Assert (AAA)** pattern:
+```typescript
+describe('TokenCompactor', () => {
+  it('should truncate oldest turns when token budget is exceeded', () => {
+    // Arrange: Set up initial state and test inputs
+    const budget = 1000;
+    const history = createTranscriptFixture({ totalTokens: 1500 });
+
+    // Act: Invoke the unit under test
+    const compacted = compactHistory(history, budget);
+
+    // Assert: Verify expected output and invariants
+    expect(compacted.totalTokens).toBeLessThanOrEqual(budget);
+    expect(compacted.turns[0].isSummary).toBe(true);
+  });
+});
+```
+
+---
+
+## 3. Mandatory Edge-Case Checklist
+
+Every feature or bugfix test suite must assert against these boundary conditions:
+- [ ] **Empty / Nil Inputs**: Null, undefined, empty strings `""`, empty arrays `[]`, empty objects `{}`.
+- [ ] **Boundary Extremes**: Zero, negative integers, max integer bounds (`Number.MAX_SAFE_INTEGER`), very large strings (>1MB).
+- [ ] **Malformed Payloads**: Invalid JSON, broken YAML frontmatter, truncated streams.
+- [ ] **Network & Error Boundaries**: Simulated HTTP 429 (rate limits), 503 timeouts, socket hangups.
+- [ ] **Idempotent Retries**: Running the same operation twice returns identical deterministic results without side effects.
+
+---
+
+## 4. Test Isolation & Determinism
+- **No Shared Mutable State**:
+  - Each test must run independently. Clean up databases, mocks, and temporary directories in `afterEach` hooks.
+- **Deterministic Clocks**:
+  - Avoid `setTimeout` loops in tests. Use mock timers (`vi.useFakeTimers()` or `jest.useFakeTimers()`) to eliminate flaky tests and speed up test execution.

package/scripts/install.ps1

@@ -8,9 +8,18 @@ param (
 Write-Host "🪐 Everything Gemini (everything-gemini) Installer" -ForegroundColor Cyan
 Write-Host "The premier agent harness & customization suite for Google Antigravity`n" -ForegroundColor Gray
 
+$origDir = Get-Location
+$tempDir = ""
+$cleanupTemp = $false
+
+if (-not $Global -and $Workspace -eq "") {
+    $Workspace = Join-Path $origDir ".agents"
+}
+
 if (-not (Test-Path "bin\everything-gemini")) {
     Write-Host "Downloading latest everything-gemini release..." -ForegroundColor Yellow
     $tempDir = [System.IO.Path]::Combine([System.IO.Path]::GetTempPath(), [System.IO.Path]::GetRandomFileName())
+    $cleanupTemp = $true
     git clone --depth 1 https://github.com/salmandev/everything-gemini.git $tempDir
     Set-Location $tempDir
 }
@@ -24,3 +33,8 @@ if ($Workspace -ne "") {
 }
 
 node bin\everything-gemini @cliArgs
+
+if ($cleanupTemp -and (Test-Path $tempDir)) {
+    Set-Location $origDir
+    Remove-Item -Recurse -Force $tempDir -ErrorAction SilentlyContinue
+}

package/scripts/install.sh

@@ -15,9 +15,12 @@ echo "  🪐 Everything Gemini (everything-gemini) Installer"
 echo "  The premier agent harness & customization suite for Google Antigravity"
 echo -e "${RESET}"
 
+ORIG_DIR="$(pwd)"
 PROFILE="developer"
 INSTALL_GLOBAL=false
 TARGET_DIR=""
+TMP_DIR=""
+CLEANUP_TMP=false
 
 while [[ "$#" -gt 0 ]]; do
   case $1 in
@@ -29,10 +32,15 @@ while [[ "$#" -gt 0 ]]; do
   shift
 done
 
-# If run directly via curl pipe, clone into temporary directory or clone repo
+if [ "$INSTALL_GLOBAL" = false ] && [ -z "$TARGET_DIR" ]; then
+  TARGET_DIR="$ORIG_DIR/.agents"
+fi
+
+# If run directly via curl pipe, clone into temporary directory
 if [ ! -f "bin/everything-gemini" ]; then
   echo -e "${YELLOW}Downloading latest everything-gemini release...${RESET}"
   TMP_DIR=$(mktemp -d)
+  CLEANUP_TMP=true
   git clone --depth 1 https://github.com/salmandev/everything-gemini.git "$TMP_DIR/everything-gemini" 2>/dev/null || {
     echo "Failed to clone repository. Please ensure git is installed."
     exit 1
@@ -50,3 +58,9 @@ if [ -n "$TARGET_DIR" ]; then
 fi
 
 ./bin/everything-gemini $CLI_ARGS
+
+# Cleanup temp clone if created
+if [ "$CLEANUP_TMP" = true ] && [ -n "$TMP_DIR" ] && [ -d "$TMP_DIR" ]; then
+  cd "$ORIG_DIR"
+  node -e "try { require('fs').rmSync(process.argv[1], {recursive: true, force: true}); } catch(e){}" "$TMP_DIR" 2>/dev/null || true
+fi

package/scripts/validate.sh

@@ -7,7 +7,7 @@ ERRORS=0
 echo "🔍 Validating Everything Gemini (everything-gemini) repository..."
 
 # 1. Validate SKILL.md Frontmatter
-echo "  [1/4] Checking Skills & YAML frontmatter..."
+echo "  [1/6] Checking Skills & YAML frontmatter..."
 SKILL_FILES=$(find "$REPO_ROOT/skills" "$REPO_ROOT/plugins" -name "SKILL.md" 2>/dev/null || true)
 
 for skill_file in $SKILL_FILES; do
@@ -35,8 +35,29 @@ for skill_file in $SKILL_FILES; do
   echo "    ✔ $rel_path"
 done
 
-# 2. Validate JSON Syntax
-echo "  [2/4] Validating JSON files..."
+# 2. Validate Scoped Subagents
+echo "  [2/6] Checking Subagents specifications..."
+REQUIRED_AGENTS=("planner.md" "code-reviewer.md" "browser-qa.md" "build-repair.md" "security-auditor.md" "architect.md" "database-migrator.md" "performance-tuner.md" "documentation-writer.md" "release-engineer.md" "incident-responder.md")
+for ag in "${REQUIRED_AGENTS[@]}"; do
+  if [ ! -f "$REPO_ROOT/agents/$ag" ]; then
+    echo "    ❌ ERROR: Required subagent specification 'agents/$ag' is missing!"
+    ERRORS=$((ERRORS + 1))
+  fi
+done
+
+AGENT_FILES=$(find "$REPO_ROOT/agents" -name "*.md" 2>/dev/null || true)
+for agent_file in $AGENT_FILES; do
+  rel_path="${agent_file#$REPO_ROOT/}"
+  if ! grep -q "^# " "$agent_file"; then
+    echo "    ❌ ERROR: $rel_path is missing top-level '# ' title"
+    ERRORS=$((ERRORS + 1))
+  else
+    echo "    ✔ $rel_path"
+  fi
+done
+
+# 3. Validate JSON & YAML Files
+echo "  [3/6] Validating JSON files & Action manifest..."
 JSON_FILES=$(find "$REPO_ROOT" -name "*.json" ! -path "*/node_modules/*" 2>/dev/null || true)
 
 for json_file in $JSON_FILES; do
@@ -49,21 +70,91 @@ for json_file in $JSON_FILES; do
   fi
 done
 
-# 3. Validate Shell Scripts Executability
-echo "  [3/4] Verifying script permissions..."
-SH_FILES=$(find "$REPO_ROOT/scripts" "$REPO_ROOT/hooks" "$REPO_ROOT/skills" -name "*.sh" 2>/dev/null || true)
+if [ -f "$REPO_ROOT/action.yml" ]; then
+  if grep -q "name:" "$REPO_ROOT/action.yml" && grep -q "runs:" "$REPO_ROOT/action.yml"; then
+    echo "    ✔ action.yml (composite GitHub action valid)"
+  else
+    echo "    ❌ ERROR: action.yml is missing required composite action fields"
+    ERRORS=$((ERRORS + 1))
+  fi
+fi
+
+# Validate Relative Documentation Links
+if ! node -e "
+const fs = require('fs');
+const path = require('path');
+const mdFiles = [
+  'README.md', 'CONTRIBUTING.md', 'SECURITY.md', 'CHANGELOG.md',
+  ...fs.readdirSync('skills').map(s => 'skills/' + s + '/SKILL.md'),
+  ...fs.readdirSync('agents').map(a => 'agents/' + a)
+];
+let broken = 0;
+for (const file of mdFiles) {
+  if (!fs.existsSync(file)) continue;
+  let content = fs.readFileSync(file, 'utf8');
+  content = content.replace(/\`\`\`[\s\S]*?\`\`\`/g, '');
+  content = content.replace(/\`[^\`]*?\`/g, '');
+  const matches = content.matchAll(/\[([^\]]+)\]\(([^)]+)\)/g);
+  for (const m of matches) {
+    const link = m[2];
+    if (link.startsWith('http://') || link.startsWith('https://') || link.startsWith('#') || link.startsWith('mailto:') || link.startsWith('file://')) continue;
+    const cleanLink = link.split('#')[0];
+    if (!cleanLink) continue;
+    const resolved = path.resolve(path.dirname(file), cleanLink);
+    if (!fs.existsSync(resolved)) {
+      console.error('Broken link in ' + file + ' -> ' + link);
+      broken++;
+    }
+  }
+}
+if (broken > 0) process.exit(1);
+" 2>/dev/null; then
+  echo "    ❌ ERROR: Broken relative links detected in documentation"
+  ERRORS=$((ERRORS + 1))
+else
+  echo "    ✔ Documentation relative links verified"
+fi
+
+# 4. Validate Shell Scripts & CLI Executability
+echo "  [4/6] Verifying script permissions & code syntax..."
+EXEC_FILES=$(find "$REPO_ROOT/scripts" "$REPO_ROOT/hooks" "$REPO_ROOT/skills" "$REPO_ROOT/examples" "$REPO_ROOT/bin" -type f \( -name "*.sh" -o -name "everything-gemini" \) 2>/dev/null || true)
 
-for sh_file in $SH_FILES; do
-  rel_path="${sh_file#$REPO_ROOT/}"
-  if [ ! -x "$sh_file" ]; then
+for exec_file in $EXEC_FILES; do
+  rel_path="${exec_file#$REPO_ROOT/}"
+  if [ ! -x "$exec_file" ]; then
     echo "    ⚠️ Fixing executable bit on: $rel_path"
-    chmod +x "$sh_file"
+    chmod +x "$exec_file"
   fi
   echo "    ✔ $rel_path (executable)"
 done
 
-# 4. Summary
-echo "  [4/4] Validation Summary"
+# Validate Python examples syntax
+if command -v python3 >/dev/null 2>&1; then
+  PY_FILES=$(find "$REPO_ROOT/examples" -name "*.py" 2>/dev/null || true)
+  for py_file in $PY_FILES; do
+    rel_path="${py_file#$REPO_ROOT/}"
+    if ! python3 -m py_compile "$py_file" 2>/dev/null; then
+      echo "    ❌ ERROR: Syntax error in $rel_path"
+      ERRORS=$((ERRORS + 1))
+    else
+      echo "    ✔ $rel_path (valid Python syntax)"
+    fi
+  done
+fi
+
+# 5. CLI E2E Integration Suite
+echo "  [5/6] Running CLI E2E Integration Suite..."
+if [ -f "$REPO_ROOT/tests/cli.test.js" ]; then
+  if ! node "$REPO_ROOT/tests/cli.test.js"; then
+    echo "    ❌ ERROR: CLI test suite failed."
+    ERRORS=$((ERRORS + 1))
+  else
+    echo "    ✔ CLI test suite passed (26 assertions)"
+  fi
+fi
+
+# 6. Summary
+echo "  [6/6] Validation Summary"
 if [ "$ERRORS" -gt 0 ]; then
   echo "❌ Validation failed with $ERRORS error(s)."
   exit 1

package/skills/agent-evals/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: agent-evals
+description: Designs, executes, and benchmarks AI agent evaluation pipelines, LLM-as-a-judge scoring rubrics, golden test datasets, and prompt regression testing harnesses.
+---
+
+# Agent Evals & LLM Benchmark Playbook
+
+This skill guides the creation of automated evaluation harnesses, LLM-as-a-judge scoring pipelines, and regression testing suites for AI agents and LLM applications.
+
+---
+
+## 1. Core Principles
+
+1. **Deterministic Assertions First**:
+   - Prefer deterministic, unit-testable assertions (schema validation, regex matching, exit codes, latency limits) before falling back to subjective LLM judges.
+2. **Golden Datasets with Ground Truth**:
+   - Maintain versioned golden evaluation datasets (`evals/golden.jsonl`) pairing input prompts with expected outputs or behavioral criteria.
+3. **Regression Containment**:
+   - Any prompt revision or model switch must run against the baseline eval suite to measure accuracy deltas, token consumption, and latency shifts.
+
+---
+
+## 2. Evaluation Dimensions
+
+When assessing agent output quality, evaluate across four standardized vectors:
+
+| Dimension | Metric | Measurement Method |
+| :--- | :--- | :--- |
+| **Accuracy / Correctness** | Factual precision, task fulfillment | LLM-as-a-judge with binary pass/fail rubric |
+| **Safety & Alignment** | Injection vulnerability, secret leakage | Automated static analysis & safety classifiers |
+| **Schema Compliance** | Valid JSON, Pydantic type conformance | Deterministic parser validation (`json.loads`, Pydantic) |
+| **Context Economics** | Token count, time-to-first-token (TTFT) | Profiler logs & Gemini metadata tokens |
+
+---
+
+## 3. LLM-as-a-Judge Scoring Template
+
+When using Gemini as an automated evaluator, structure the prompt with strict zero-shot rubrics and JSON output:
+
+```python
+EVAL_SYSTEM_PROMPT = """You are an impartial, expert evaluation judge. 
+Assess the candidate agent response against the provided Reference Criteria.
+Provide a structured JSON evaluation adhering to the schema:
+{
+  "score": <float 0.0 to 1.0>,
+  "reasoning": "<concise explanation of strengths and shortcomings>",
+  "violations": ["<list of any missed constraints>"]
+}
+Only output valid JSON.
+"""
+```
+
+---
+
+## 4. Eval Runner Execution Flow
+
+1. **Load Test Suite**: Ingest test cases from `evals/test_cases.jsonl`.
+2. **Execute Candidate Prompt**: Query the model with temperature=0.0 for reproducible benchmarking.
+3. **Run Deterministic Checks**: Validate JSON schema, required keys, and formatting constraints.
+4. **Run LLM Judge**: Pass model output + reference criteria to the evaluator.
+5. **Aggregate Metrics**: Calculate overall pass rate, p95 latency, and token cost per run.

package/skills/apache-kafka-streams/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: apache-kafka-streams
+description: >-
+  Architects, deploys, and optimizes Apache Kafka event streaming architectures, stateful Kafka Streams / Faust topologies, exactly-once semantics (EOS), consumer group rebalancing, and Schema Registry serialization.
+---
+
+# Apache Kafka Event Streaming & Stream Processing
+
+This skill guides engineering resilient, high-throughput distributed event streaming systems with Apache Kafka, covering partition key strategies, transactional exactly-once processing (EOS), stateful sliding/tumbling window joins, and Schema Registry Avro/Protobuf governance.
+
+---
+
+## ⚡ Core Patterns
+
+### 1. Production Producer with Transactional Exactly-Once Semantics (EOS)
+
+Configure idempotency, reliable acknowledgments, and transactional boundaries:
+
+```typescript
+import { Kafka, CompressionTypes, logLevel } from 'kafkajs';
+
+const kafka = new Kafka({
+  clientId: 'order-dispatch-service',
+  brokers: ['kafka-1.internal:9092', 'kafka-2.internal:9092', 'kafka-3.internal:9092'],
+  ssl: true,
+  logLevel: logLevel.WARN,
+});
+
+const producer = kafka.producer({
+  // Idempotent producer guarantees partition deduplication and in-flight order preservation
+  idempotent: true,
+  maxInFlightRequests: 1,
+  transactionalId: 'order-tx-producer-instance-01',
+});
+
+async function publishOrderEvent(order: { id: string; customerId: string; amount: number }) {
+  await producer.connect();
+  const transaction = await producer.transaction();
+
+  try {
+    await transaction.send({
+      topic: 'enterprise.commerce.orders.v1',
+      compression: CompressionTypes.GZIP,
+      messages: [
+        {
+          key: order.customerId, // Ensures hash-partition ordering per customer
+          value: JSON.stringify(order),
+          headers: {
+            'correlation-id': crypto.randomUUID(),
+            'event-type': 'OrderPlaced',
+            'schema-version': '1.0.0',
+          },
+        },
+      ],
+    });
+
+    await transaction.commit();
+  } catch (err) {
+    await transaction.abort();
+    throw err;
+  }
+}
+```
+
+---
+
+### 2. High-Throughput Consumer Group with Cooperative Sticky Rebalancing
+
+Prevent stop-the-world partition revocations during scale-up or rolling deployments:
+
+```typescript
+const consumer = kafka.consumer({
+  groupId: 'order-fulfillment-workers',
+  sessionTimeout: 30000,
+  heartbeatInterval: 3000,
+  rebalanceTimeout: 60000,
+  // CooperativeSticky assignor migrates only transferred partitions without halting healthy consumers
+  partitionAssigners: [
+    (config) => new (require('kafkajs').PartitionAssigners.cooperativeSticky)(config),
+  ],
+});
+
+await consumer.connect();
+await consumer.subscribe({ topic: 'enterprise.commerce.orders.v1', fromBeginning: false });
+
+await consumer.run({
+  autoCommit: false,
+  eachBatchAutoResolve: false,
+  eachBatch: async ({ batch, resolveOffset, heartbeat, isRunning, isStale }) => {
+    for (const message of batch.messages) {
+      if (!isRunning() || isStale()) break;
+
+      try {
+        const payload = JSON.parse(message.value.toString());
+        await processOrderFulfillment(payload);
+
+        // Mark individual offset for manual deterministic commit
+        resolveOffset(message.offset);
+        await heartbeat();
+      } catch (err) {
+        // Route unrecoverable poison pill to Dead-Letter Queue (DLQ)
+        await publishToDLQ('enterprise.commerce.orders.dlq', message, err);
+        resolveOffset(message.offset);
+      }
+    }
+  },
+});
+```
+
+---
+
+### 3. Stateful Stream Processing (Kafka Streams / Java Topology)
+
+Perform stateful 5-minute tumbling window aggregations with RocksDB state stores:
+
+```java
+StreamsBuilder builder = new StreamsBuilder();
+KStream<String, OrderEvent> orderStream = builder.stream(
+    "enterprise.commerce.orders.v1",
+    Consumed.with(Serdes.String(), new JsonSerde<>(OrderEvent.class))
+);
+
+KTable<Windowed<String>, Long> orderCountsPerStore = orderStream
+    .selectKey((key, order) -> order.getStoreId())
+    .groupByKey(Grouped.with(Serdes.String(), new JsonSerde<>(OrderEvent.class)))
+    .windowedBy(TimeWindows.ofSizeWithNoGrace(Duration.ofMinutes(5)))
+    .count(
+        Materialized.<String, Long, WindowStore<Bytes, byte[]>>as("store-order-counts-store")
+            .withRetention(Duration.ofDays(1))
+    );
+
+orderCountsPerStore.toStream()
+    .map((windowedKey, count) -> new KeyValue<>(windowedKey.key(), new StoreOrderSummary(windowedKey.window().start(), count)))
+    .to("enterprise.commerce.store-aggregates.v1", Produced.with(Serdes.String(), new JsonSerde<>(StoreOrderSummary.class)));
+```
+
+---
+
+## 🎯 Verification & Diagnostics
+
+1. **Check Consumer Group Lag & Partition Distribution**:
+   ```bash
+   kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group order-fulfillment-workers
+   ```
+2. **Inspect Topic Partition Watermarks**:
+   ```bash
+   kafka-run-class.sh kafka.tools.GetOffsetShell --broker-list localhost:9092 --topic enterprise.commerce.orders.v1 --time -1
+   ```
+3. **Tail Stream Events with Header Decoding**:
+   ```bash
+   kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic enterprise.commerce.orders.v1 --from-beginning --property print.key=true --property print.headers=true
+   ```