everything-gemini 1.2.0 → 1.9.0

package/plugins/security-shield/rules/zero-trust.md

@@ -1,5 +1,61 @@
-# Zero-Trust Security Policies
+# Zero-Trust Security Policies (Antigravity & Gemini)
 
-- **Least Privilege Tool Execution**: Agents operate with read-only defaults unless explicit write capabilities are granted.
-- **Network Boundaries**: Outbound network requests require explicit authorization unless calling approved APIs in the allowlist.
-- **Sandboxed Execution**: Destructive system utilities are restricted to isolated containers or sandboxes.
+These mandatory policies establish defense-in-depth safety boundaries for automated AI agents, shell execution environments, and tool integrations.
+
+---
+
+## 1. Principle of Least Privilege (PoLP)
+- **Read-Only Defaults**:
+  - Subagents and background tasks default to read-only tool permissions (`view_file`, `grep_search`, `list_dir`) unless explicit write permissions are necessary.
+- **Granular Tool Grants**:
+  - Do not grant shell execution privileges to subagents that only require file inspection or documentation synthesis.
+- **Explicit Confirmation Gates**:
+  - High-risk operations (production deployments, database schema migrations, repository configuration updates) require explicit confirmation gates.
+
+---
+
+## 2. Credential & Secret Leakage Prevention
+- **Proactive Secret Scanning**:
+  - Outbound payloads, diffs, and generated files must be scanned for credential patterns:
+    - Google Cloud / Gemini API Keys (`AIza[0-9A-Za-z\\-_]{35}`)
+    - GitHub Personal Access Tokens (`ghp_[0-9A-Za-z]{36}`)
+    - Stripe Secret Keys (`sk_live_[0-9a-zA-Z]{24}`)
+    - Private SSH / TLS keys (`-----BEGIN.*PRIVATE KEY-----`)
+- **Zero-Logging Policy**:
+  - Never print, echo, or log environment variables containing API keys, tokens, or credentials to terminal stdout/stderr.
+- **Git Hygiene**:
+  - Never commit `.env`, `.env.local`, or secret credentials to version control. Always maintain sanitized `.env.example` templates.
+
+---
+
+## 3. Command Injection & Execution Guardrails
+- **Lifecycle Interception (PreToolUse)**:
+  - All shell commands executed by agents are intercepted by deterministic safety gates (`gemini-shield` / `safety-shield`).
+- **Blocked Catastrophic Commands**:
+  - The following commands are blocked unconditionally:
+    - Destructive filesystem deletion: `rm -rf /`, `rm -rf *`, `rm -rf ~`
+    - Production branch forced overwrites: `git push --force origin main`, `git push -f origin master`
+    - Destructive database operations: `DROP DATABASE`, `DROP TABLE`, `TRUNCATE`
+    - Unaudited remote execution: `curl ... | sh`, `wget ... | bash`
+- **Argument Parameterization**:
+  - Never concatenate raw unvalidated strings into shell command strings. Prefer direct array-based argument passing (`child_process.execFile` or `subprocess.run(["cmd", arg])`).
+
+---
+
+## 4. Path Traversal & Filesystem Containment
+- **Workspace Boundary Enforcement**:
+  - All file operations must resolve to paths strictly within the active workspace root (`process.cwd()`) or designated global config root (`~/.gemini/config/`).
+- **Path Normalization**:
+  - Normalize all incoming file paths (`path.resolve()`) to eliminate directory traversal vectors (`../`, `..\`).
+- **Forbidden Root Modifications**:
+  - Direct writes to `/tmp`, `/etc`, `/usr`, or system binaries outside the designated workspace are strictly prohibited.
+
+---
+
+## 5. Network Boundaries & Safe Integrations
+- **Approved Outbound Endpoints**:
+  - Network requests made by MCP servers or tools must connect to approved domains or local loopback interfaces (`localhost`, `127.0.0.1`).
+- **TLS Certificate Validation**:
+  - Outbound HTTPS calls must enforce valid TLS certificates. Disabling certificate verification (`rejectUnauthorized: false` or `verify=False`) is disallowed.
+- **Deterministic Sandboxes**:
+  - When running untrusted code or third-party dependencies, execute inside isolated Docker containers or sandboxed virtual environments.

package/plugins/web-fullstack/rules/frontend-standards.md

@@ -1,5 +1,75 @@
-# Frontend Engineering Standards
+# Frontend & Web Engineering Standards
 
-- **Accessible HTML (a11y)**: Use semantic HTML5 elements (`<nav>`, `<main>`, `<article>`, `<section>`, `<button>`). Never use `<div onClick="...">` without keyboard accessibility.
-- **Visual Excellence**: Avoid plain, generic color schemes. Use curated palettes (HSL/OKLCH), subtle gradients, and smooth micro-animations.
-- **Zero Layout Shifts**: Always specify dimensions (`width`, `height`) on images and video embeds.
+These principles define visual quality, accessibility standards, Core Web Vitals, and modern fullstack architectures across all web applications.
+
+---
+
+## 1. Visual Aesthetics & Design Excellence
+- **Rich Aesthetics by Default**:
+  - Web applications must make a stunning first impression. Avoid plain, unstyled HTML or generic primary colors (pure red, green, blue).
+  - Use curated HSL or OKLCH color palettes with harmonic tonal contrast and sleek dark-mode backgrounds (e.g. `#07090e`, `#10141f`).
+- **Modern Typography**:
+  - Avoid browser defaults (Times New Roman, basic Arial). Pair modern variable web fonts:
+    - Interface text: *Plus Jakarta Sans*, *Inter*, or *Outfit*
+    - Code / Monospace: *JetBrains Mono* or *Fira Code*
+- **Dynamic Micro-Interactions**:
+  - Interface elements must feel responsive and alive:
+    - Hover states with subtle elevation (`transform: translateY(-2px)`)
+    - Smooth transition timings (`transition: all 0.2s cubic-bezier(0.16, 1, 0.3, 1)`)
+    - Polished button active states and copy confirmations
+
+---
+
+## 2. Semantic HTML5 & Accessibility (WCAG 2.2 AA)
+- **Semantic Structure**:
+  - Always use structural landmark elements: `<header>`, `<nav>`, `<main>`, `<section>`, `<article>`, `<footer>`.
+  - Only one `<h1>` per page, followed by logical heading hierarchy (`<h2>`, `<h3>`).
+- **Interactive Elements**:
+  - Never attach click handlers to unstyled `<div>` or `<span>` tags. Use `<button>` for actions and `<a>` for navigational URLs.
+  - Interactive custom widgets must provide proper ARIA attributes (`aria-expanded`, `aria-label`, `aria-haspopup`).
+- **Keyboard & Focus Navigation**:
+  - Ensure all interactive elements are reachable via `Tab` and triggerable via `Enter` or `Space`.
+  - Maintain high-visibility focus indicators (`:focus-visible`). Never suppress focus rings with `outline: none` without providing an accessible alternative.
+- **Color Contrast**:
+  - Maintain a minimum contrast ratio of 4.5:1 for body copy and 3:1 for large headers and graphical UI boundaries.
+
+---
+
+## 3. Core Web Vitals & Performance
+- **Zero Cumulative Layout Shift (CLS < 0.1)**:
+  - Always declare explicit `width` and `height` attributes or CSS `aspect-ratio` on `<img>`, `<video>`, and canvas elements.
+  - Reserve placeholder dimensions for dynamically injected banners and async data cards.
+- **Fast Largest Contentful Paint (LCP < 2.5s)**:
+  - Preconnect to critical font CDNs (`<link rel="preconnect" href="https://fonts.googleapis.com">`).
+  - Serve compressed next-generation image formats (WebP, AVIF) with appropriate `loading="lazy"` on below-the-fold content.
+- **Interaction to Next Paint (INP < 200ms)**:
+  - Debounce high-frequency events (search input fields, resize listeners).
+  - Avoid heavy JavaScript calculations on the main UI thread.
+
+---
+
+## 4. Responsive Design & Fluid Layouts
+- **Mobile-First Layout**:
+  - Build responsive layouts using CSS Flexbox and modern CSS Grid (`grid-template-columns: repeat(auto-fit, minmax(300px, 1fr))`).
+  - Standardized viewport breakpoints:
+    - Mobile: `< 640px`
+    - Tablet: `640px - 1024px`
+    - Desktop: `> 1024px`
+- **Fluid Typography**:
+  - Scale headers smoothly between viewport sizes using CSS `clamp()`:
+  ```css
+  font-size: clamp(2rem, 5vw + 1rem, 3.75rem);
+  ```
+- **Touch-Friendly Hit Targets**:
+  - Ensure touch targets on mobile viewports are at least `44x44px` with adequate margin spacing.
+
+---
+
+## 5. Modern Fullstack & React Server Components (RSC)
+- **Server vs Client Separation**:
+  - Default to React Server Components (RSC) for data fetching, static rendering, and markdown processing.
+  - Restrict `'use client'` strictly to interactive leaf components requiring browser hooks (`useState`, `useEffect`, `onClick`).
+- **Zero Hydration Mismatch**:
+  - Never reference browser-only APIs (`window`, `localStorage`, `document`) during initial component render passes without an `isMounted` guard.
+- **Resilient Error Boundaries**:
+  - Wrap async route segments in React `<Suspense>` fallbacks and declarative `error.tsx` boundaries to isolate failures.

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 (29 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/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
+   ```