everything-gemini 1.2.0 → 1.8.0

package/examples/python-sdk/release_readiness_audit.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""
+Everything Gemini (everything-gemini) Python SDK Example
+Release Readiness & Multi-Agent Gate Pipeline
+
+Orchestrates a 4-stage release qualification loop:
+Planner -> Code Reviewer -> Security Auditor -> Release Engineer
+"""
+
+import sys
+import json
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional
+
+@dataclass
+class ReleaseCandidate:
+    target_version: str
+    target_branch: str = "main"
+    git_head_commit: str = "HEAD"
+    breaking_changes: List[str] = field(default_factory=list)
+    features: List[str] = field(default_factory=list)
+    fixes: List[str] = field(default_factory=list)
+    test_results: Dict[str, Any] = field(default_factory=dict)
+    security_scan: Dict[str, Any] = field(default_factory=dict)
+
+class ReleaseAuditPipeline:
+    """Automates multi-agent release qualification using Antigravity principles."""
+
+    def __init__(self, rc: ReleaseCandidate):
+        self.rc = rc
+        self.audit_trail: List[Dict[str, str]] = []
+
+    def log_step(self, agent: str, action: str, status: str, details: str):
+        self.audit_trail.append({
+            "agent": agent,
+            "action": action,
+            "status": status,
+            "details": details
+        })
+        print(f"[{agent.upper()}] {action}: {status} - {details}")
+
+    def run_stage_1_planner(self) -> bool:
+        """Stage 1: Planner sets release perimeter and validation gates."""
+        self.log_step(
+            agent="planner",
+            action="define_release_gates",
+            status="SUCCESS",
+            details=f"Scope established for v{self.rc.target_version} on branch {self.rc.target_branch}."
+        )
+        return True
+
+    def run_stage_2_code_reviewer(self) -> bool:
+        """Stage 2: Code Reviewer verifies test coverage and conventional commits."""
+        all_passed = self.rc.test_results.get("all_tests_passed", True)
+        if not all_passed:
+            self.log_step(
+                agent="code-reviewer",
+                action="verify_tests",
+                status="FAILED",
+                details="Automated test suite reported regressions."
+            )
+            return False
+
+        self.log_step(
+            agent="code-reviewer",
+            action="verify_commits",
+            status="SUCCESS",
+            details=f"Conventional commit syntax validated for {len(self.rc.features)} features and {len(self.rc.fixes)} fixes."
+        )
+        return True
+
+    def run_stage_3_security_auditor(self) -> bool:
+        """Stage 3: Security Auditor inspects secrets, CVEs, and permissions."""
+        cves = self.rc.security_scan.get("critical_vulnerabilities", 0)
+        if cves > 0:
+            self.log_step(
+                agent="security-auditor",
+                action="scan_cves",
+                status="FAILED",
+                details=f"Found {cves} critical vulnerabilities."
+            )
+            return False
+
+        self.log_step(
+            agent="security-auditor",
+            action="secret_scrubbing",
+            status="SUCCESS",
+            details="Zero unmasked API keys or private keys found in build manifests."
+        )
+        return True
+
+    def run_stage_4_release_engineer(self) -> Dict[str, Any]:
+        """Stage 4: Release Engineer compiles changelog, calculates checksums, and signs release."""
+        bump_type = "major" if self.rc.breaking_changes else ("minor" if self.rc.features else "patch")
+        
+        release_manifest = {
+            "version": self.rc.target_version,
+            "semver_bump": bump_type,
+            "git_tag": f"v{self.rc.target_version}",
+            "artifact_checksum_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+            "ready_to_deploy": True
+        }
+
+        self.log_step(
+            agent="release-engineer",
+            action="generate_release_manifest",
+            status="SUCCESS",
+            details=f"Release {release_manifest['git_tag']} approved as {bump_type.upper()} bump."
+        )
+        return release_manifest
+
+    def execute(self) -> Optional[Dict[str, Any]]:
+        print(f"\n🚀 Initiating Release Readiness Audit for v{self.rc.target_version}...\n")
+        
+        if not self.run_stage_1_planner():
+            return None
+        if not self.run_stage_2_code_reviewer():
+            return None
+        if not self.run_stage_3_security_auditor():
+            return None
+        
+        manifest = self.run_stage_4_release_engineer()
+        print("\n✨ Release Readiness Audit PASSED! All 4 Subagent Gates Cleared.")
+        return manifest
+
+if __name__ == "__main__":
+    candidate = ReleaseCandidate(
+        target_version="1.7.0",
+        features=[
+            "langgraph-orchestrator skill",
+            "playwright-visual-regression skill",
+            "open-telemetry-tracing skill",
+            "argo-workflows skill",
+            "audit CLI command"
+        ],
+        fixes=["strict subagent contract assertion"],
+        test_results={"all_tests_passed": True, "total_tests": 24},
+        security_scan={"critical_vulnerabilities": 0}
+    )
+
+    pipeline = ReleaseAuditPipeline(candidate)
+    result = pipeline.execute()
+    if not result:
+        sys.exit(1)

package/hooks/secret-scrubber/hooks.json

@@ -0,0 +1,16 @@
+{
+  "secret-scrubber": {
+    "PreToolUse": [
+      {
+        "matcher": "write_to_file|replace_file_content|multi_replace_file_content",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ./scripts/scrub-secrets.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/secret-scrubber/scripts/scrub-secrets.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# Everything Gemini Secret Scrubber: PreToolUse Security Gate
+# Reads protojson hook payload from stdin, inspects write content for plaintext credentials,
+# and outputs JSON decision on stdout.
+
+set -eo pipefail
+
+PAYLOAD=$(cat)
+
+# Extract content being written using node
+SECRET_FOUND=$(node -e "
+try {
+  const p = JSON.parse(process.argv[1]);
+  const args = p.toolCall?.args || {};
+  let content = '';
+
+  if (args.CodeContent) content += args.CodeContent + '\n';
+  if (args.ReplacementContent) content += args.ReplacementContent + '\n';
+  if (Array.isArray(args.ReplacementChunks)) {
+    content += args.ReplacementChunks.map(c => c.ReplacementContent || '').join('\n');
+  }
+
+  // Regex patterns for live production credentials
+  const patterns = [
+    { name: 'AWS Access Key', regex: /AKIA[0-9A-Z]{16}/ },
+    { name: 'OpenAI Secret Key', regex: /sk-[a-zA-Z0-9]{48}|sk-proj-[a-zA-Z0-9_-]{40,}/ },
+    { name: 'Google API Key', regex: /AIza[0-9A-Za-z\\-_]{35}/ },
+    { name: 'GitHub Personal Access Token', regex: /ghp_[0-9a-zA-Z]{36}|github_pat_[0-9a-zA-Z_]{82}/ },
+    { name: 'Slack Bot Token', regex: /xoxb-[0-9]{11,13}-[0-9]{11,13}-[a-zA-Z0-9]{24}/ },
+    { name: 'Stripe Live Secret Key', regex: /sk_live_[0-9a-zA-Z]{24}/ },
+    { name: 'Private Key', regex: /-----BEGIN [A-Z ]+PRIVATE KEY-----/ }
+  ];
+
+  for (const { name, regex } of patterns) {
+    if (regex.test(content)) {
+      console.log(name);
+      process.exit(0);
+    }
+  }
+  console.log('');
+} catch (e) {
+  console.log('');
+}
+" "$PAYLOAD")
+
+if [ -n "$SECRET_FOUND" ]; then
+  cat <<EOF
+{
+  "decision": "deny",
+  "reason": "Security Alert: Secret Scrubber detected raw ${SECRET_FOUND} in file write payload. Do not commit or hardcode live credentials. Use environment variables (process.env / os.environ) instead."
+}
+EOF
+  exit 0
+fi
+
+# Clean content
+cat <<EOF
+{
+  "decision": "allow"
+}
+EOF
+exit 0

package/mcp/README.md

@@ -37,5 +37,25 @@ Antigravity connects to a remote MCP endpoint over HTTPS:
 }
 ```
 
+## Curated MCP Server Blueprints
+
+Everything Gemini bundles ready-to-use blueprints in `mcp/mcp_config.example.json`:
+
+| Server Name | Package | Purpose | Transport |
+| :--- | :--- | :--- | :--- |
+| **`memory`** | `@modelcontextprotocol/server-memory` | Persistent knowledge graph semantic memory across agent sessions | Stdio |
+| **`fetch`** | `@modelcontextprotocol/server-fetch` | Efficient HTTP scraping and web documentation extraction | Stdio |
+| **`redis`** | `@modelcontextprotocol/server-redis` | High-speed key-value caching, Pub/Sub, and distributed locks | Stdio |
+| **`docker`** | `@modelcontextprotocol/server-docker` | Container lifecycle inspection, logs, and containerized testing | Stdio |
+| **`clickhouse`** | `@modelcontextprotocol/server-clickhouse` | High-throughput OLAP analytics and vector similarity search | Stdio |
+| **`sequential-thinking`** | `@modelcontextprotocol/server-sequential-thinking` | Dynamic multi-step reasoning, hypothesis testing & decomposition | Stdio |
+| **`github`** | `@modelcontextprotocol/server-github` | Pull requests, issues, repo search, and commit inspection | Stdio |
+| **`postgres`** | `@modelcontextprotocol/server-postgres` | PostgreSQL relational schema inspection and SQL queries | Stdio |
+| **`sqlite`** | `@modelcontextprotocol/server-sqlite` | Local SQLite database querying and table inspection | Stdio |
+| **`filesystem`** | `@modelcontextprotocol/server-filesystem` | Direct multi-directory filesystem inspection | Stdio |
+| **`sentry`** | `@modelcontextprotocol/server-sentry` | Real-time production error tracking, issue triage, and stacktrace analysis | Stdio |
+| **`slack`** | `@modelcontextprotocol/server-slack` | Automated incident channels, alert broadcasts, and team collaboration | Stdio |
+
 ## Tool Auto-Discovery & Execution
 Once connected, tools declared by MCP servers are automatically injected into the agent's system prompt and executed through Antigravity's Language Server. Inspect active MCP servers in the Antigravity UI via **Additional Options (...) > MCP Servers**.
+

package/mcp/mcp_config.example.json

@@ -22,9 +22,44 @@
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "./docs", "./src"]
     },
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"]
+    },
     "fetch": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-fetch"]
+    },
+    "redis": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-redis", "redis://localhost:6379"]
+    },
+    "docker": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-docker"]
+    },
+    "clickhouse": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-clickhouse", "http://default:@localhost:8123/default"]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    },
+    "sentry": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sentry"],
+      "env": {
+        "SENTRY_AUTH_TOKEN": "YOUR_SENTRY_AUTH_TOKEN"
+      }
+    },
+    "slack": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-slack"],
+      "env": {
+        "SLACK_BOT_TOKEN": "YOUR_SLACK_BOT_TOKEN",
+        "SLACK_TEAM_ID": "YOUR_SLACK_TEAM_ID"
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "everything-gemini",
-  "version": "1.2.0",
+  "version": "1.8.0",
   "description": "Everything Gemini (everything-gemini) - The Ultimate Agent Harness, Multi-Agent Orchestrator & Performance Suite for Gemini & Google Antigravity",
   "main": "bin/everything-gemini",
   "bin": {
@@ -11,6 +11,8 @@
   "scripts": {
     "test": "bash scripts/validate.sh",
     "validate": "bash scripts/validate.sh",
+    "benchmark": "node bin/everything-gemini test-all",
+    "completion": "node bin/everything-gemini completion",
     "install:core": "bash scripts/install.sh --profile core",
     "install:dev": "bash scripts/install.sh --profile developer",
     "install:full": "bash scripts/install.sh --profile full"

package/plugins/core/rules/core-practices.md

@@ -1,5 +1,64 @@
-# Core Engineering Practices
+# Core Engineering Practices (Antigravity & Gemini)
 
-- **Self-Healing Verification**: Whenever a command errors, parse the traceback before making subsequent edits.
-- **Atomic Operations**: Never leave files in half-written or unparseable states.
-- **Defensive Coding**: Validate all inputs at the boundary. Fail fast and fail clearly.
+These principles govern all agentic interactions, tool executions, and file modifications within this repository and downstream Antigravity workspaces.
+
+---
+
+## 1. Zero Hallucination & Evidence-First Protocol
+1. **Verify Before Asserting**:
+   - Never assume file structures, function signatures, dependencies, or configuration schemas exist without inspecting them first.
+   - Use `view_file`, `grep_search`, or `list_dir` to confirm actual filesystem reality before proposing or applying code changes.
+2. **Clickable Markdown File References**:
+   - Always format file paths and symbols as clickable Markdown links with the `file://` scheme (e.g. `[filename](file:///absolute/path/to/file)`).
+3. **Truth Grounding**:
+   - When referencing APIs or libraries, rely on codebase evidence, lockfiles, or live search grounding over training-time assumptions.
+
+---
+
+## 2. Proactive Verification Loop
+1. **Automated Verification After Modification**:
+   - Every modification MUST be followed by automated verification (running tests, linters, or typecheckers like `npm test` or `bash scripts/validate.sh`).
+2. **Defect Isolation**:
+   - If a command fails, inspect the error output and stack trace immediately. Fix the root cause rather than guessing or applying speculative patches.
+3. **Never Repeat Blind Failures**:
+   - Never execute the identical failing command in a loop without modifying code or resolving the underlying dependency failure.
+
+---
+
+## 3. Minimal Surgical Diffs
+1. **Preserve Code Formatting & Comments**:
+   - Preserve all existing code formatting, comments, licenses, and docstrings unrelated to your immediate task.
+2. **Targeted Replacement**:
+   - Use targeted edit tools (`replace_file_content` or `multi_replace_file_content`) instead of overwriting whole files whenever possible.
+3. **Zero Accidental Refactoring**:
+   - Do not reformat untouched functions or change style conventions outside the scope of the requested change.
+
+---
+
+## 4. Self-Healing & Traceback Analysis
+1. **Traceback Parsing**:
+   - Extract exact file paths, line numbers, and error codes from compiler tracebacks.
+2. **Targeted Reproduction**:
+   - Craft minimal reproduction test cases before applying large structural alterations.
+3. **Clean Teardown**:
+   - When running scratch test scripts or temporary directories, ensure exit traps cleanly remove test artifacts.
+
+---
+
+## 5. Progressive Disclosure Discipline
+1. **Context Efficiency**:
+   - Keep conversation context lean. Rely on on-demand skills in `skills/` and reference documents in `references/`.
+2. **Cache-Friendly Structures**:
+   - Structure prompt headers and system guidelines deterministically to maximize Gemini 3.8 prefix caching (~75% cost savings).
+3. **Modular Plugin Separation**:
+   - Keep domain rules, skills, and hooks encapsulated in their respective namespaces.
+
+---
+
+## 6. Defensive Boundary Validation & Idempotency
+1. **Input Sanitization**:
+   - Validate and normalize all paths, CLI flags, and JSON payloads at system boundaries.
+2. **Idempotent Operations**:
+   - Ensure setup, install, and update commands can run repeatedly without duplicating configuration entries or corrupting files.
+3. **Safe Execution**:
+   - Never execute destructive shell operations (`rm -rf *`, `git reset --hard`) with unvalidated wildcard expansions.

package/plugins/python-ai/rules/ai-agent-patterns.md

@@ -1,5 +1,68 @@
-# AI Agent & LLM Engineering Standards
+# AI Agent & LLM Engineering Standards (Python & Gemini)
 
-- **Streaming First**: Always stream LLM response tokens and reasoning thoughts for enhanced observability and interactive responsiveness.
-- **Strongly-Typed Tool Calls**: Validate tool schemas using Pydantic or TypedDict before exposing them to agents.
-- **Graceful Error Recovery**: Handle API rate limits, model overloads, and context length limits with exponential backoff and message compaction.
+These principles guide the development and orchestration of AI agents, tool declarations, and model interactions using Python and the Gemini / Antigravity SDKs.
+
+---
+
+## 1. Streaming & Real-Time Reasoning
+- **Streaming First**:
+  - Always stream response tokens for interactive user sessions (`client.models.generate_content_stream`) to minimize Time-to-First-Token (TTFT).
+- **Separation of Reasoning & Final Output**:
+  - Distinguish agent thought sequences from final customer-facing responses. Stream thinking blocks to developer logs while streaming final text to UI clients.
+- **Async Event Loops**:
+  - Leverage `asyncio` for non-blocking I/O when handling parallel agent invocations and external tool queries.
+
+---
+
+## 2. Strongly-Typed Tool Declarations
+- **Pydantic Tool Schemas**:
+  - Define all agent tool parameters using Pydantic `BaseModel` with explicit type annotations and field descriptions:
+  ```python
+  from pydantic import BaseModel, Field
+
+  class QueryDatabaseArgs(BaseModel):
+      query: str = Field(description="Sanitized SQL query to execute")
+      limit: int = Field(default=50, ge=1, le=1000, description="Max rows to return")
+  ```
+- **Unambiguous Parameter Descriptions**:
+  - Clearly document valid enum values, format constraints, and default behaviors so the model never generates hallucinated arguments.
+- **Fail-Fast Boundary Validation**:
+  - Catch Pydantic `ValidationError` at the tool gate and return structured error messages back to the agent for self-correction.
+
+---
+
+## 3. Structured Output Guarantees
+- **JSON Schema Enforcement**:
+  - Use `response_mime_type="application/json"` combined with `response_schema` to guarantee valid JSON formatting without regex post-processing.
+- **Envelope Contracts**:
+  - Always wrap structured agent payloads in standardized envelopes containing status, findings, and metadata.
+
+---
+
+## 4. Context Caching & Token Optimization
+- **Deterministic Prompt Prefixing**:
+  - Place static repository maps, immutable system instructions, and schema definitions at the very beginning of the prompt to maximize Gemini 3.8 static prefix cache hits.
+- **Cache Eviction Discipline**:
+  - For corpuses exceeding 32,768 tokens, establish explicit TTL-based Context Caches (`client.caches.create`) to achieve ~75% cost reduction.
+- **Progressive Disclosure Memory**:
+  - In long-running multi-turn sessions, summarize intermediate reasoning steps and compact transcript history to prevent context overflow.
+
+---
+
+## 5. Deterministic Subagent Orchestration
+- **Explicit Scoping**:
+  - Delegate tasks to specialized subagents with strictly isolated toolsets (e.g. read-only subagents for code search, execution subagents for testing).
+- **Structured Synthesis Handoff**:
+  - Child agents must return standardized Markdown reports containing:
+    1. Executive Summary
+    2. Modified Files List
+    3. Test / Verification Output
+    4. Open Risks & Blockers
+
+---
+
+## 6. Resilience & Fault Tolerance
+- **Exponential Backoff with Jitter**:
+  - Wrap API calls in retry handlers catching HTTP 429 (rate limit) and 503 (service overloaded) with exponential backoff and randomized jitter.
+- **Fallback Models**:
+  - Configure automatic failover from high-reasoning models (e.g. Gemini 1.5 Pro) to high-throughput models (e.g. Gemini 1.5 Flash) during transient network outages.

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.