everything-gemini 1.0.0 → 1.1.1

package/hooks/ephemeral-context/scripts/inject-context.sh

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
-# eagy Ephemeral Context Injector: PreInvocation Hook
+# Everything Gemini Ephemeral Context Injector: PreInvocation Hook
 # Sends a transient reminder to the agent prior to model invocation.
 
 set -eo pipefail
 
-echo '{"injectSteps": [{"ephemeralMessage": "[eagy Harness Active]: Verify code with tests, follow progressive disclosure, and ensure all file links use markdown file:// scheme."}]}'
+echo '{"injectSteps": [{"ephemeralMessage": "[Everything Gemini Harness Active]: Verify code with tests, follow progressive disclosure, and ensure all file links use markdown file:// scheme."}]}'
 exit 0

package/hooks/goal-verifier/scripts/verify-goal.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# eagy Goal Verifier: Stop Hook
+# Everything Gemini Goal Verifier: Stop Hook
 # Checks if the workspace has uncommitted broken tests before allowing termination.
 
 set -eo pipefail
@@ -14,7 +14,7 @@ if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
     # If package.json has a test script, verify tests pass
     if [ -f "package.json" ] && grep -q '"test"' package.json; then
       if ! npm test >/dev/null 2>&1; then
-        echo "{\"decision\": \"continue\", \"reason\": \"[eagy Goal Verifier] Uncommitted changes failed 'npm test'. Please resolve failing tests before stopping.\"}"
+        echo "{\"decision\": \"continue\", \"reason\": \"[Everything Gemini Goal Verifier] Uncommitted changes failed 'npm test'. Please resolve failing tests before stopping.\"}"
         exit 0
       fi
     fi

package/hooks/safety-shield/scripts/safety-gate.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# eagy Safety Shield: PreToolUse Security Gate
+# Everything Gemini Safety Shield: PreToolUse Security Gate
 # Reads protojson hook payload from stdin, evaluates safety, outputs JSON on stdout.
 
 set -eo pipefail
@@ -46,7 +46,7 @@ ASK_PATTERNS=(
 # Check blocked patterns
 for pattern in "${BLOCKED_PATTERNS[@]}"; do
   if [[ "$CMD" == *"$pattern"* ]]; then
-    echo "{\"decision\": \"deny\", \"reason\": \"[eagy Safety Shield] Catastrophic command pattern detected and blocked: '$pattern'\"}"
+    echo "{\"decision\": \"deny\", \"reason\": \"[Everything Gemini Safety Shield] Catastrophic command pattern detected and blocked: '$pattern'\"}"
     exit 0
   fi
 done
@@ -54,7 +54,7 @@ done
 # Check ask patterns
 for pattern in "${ASK_PATTERNS[@]}"; do
   if [[ "$CMD" == *"$pattern"* ]]; then
-    echo "{\"decision\": \"ask\", \"reason\": \"[eagy Safety Shield] Potentially destructive command requires user confirmation: '$pattern'\"}"
+    echo "{\"decision\": \"ask\", \"reason\": \"[Everything Gemini Safety Shield] Potentially destructive command requires user confirmation: '$pattern'\"}"
     exit 0
   fi
 done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "everything-gemini",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Everything Gemini (everything-gemini) - The Ultimate Agent Harness, Multi-Agent Orchestrator & Performance Suite for Gemini & Google Antigravity",
   "main": "bin/everything-gemini",
   "bin": {
@@ -35,6 +35,7 @@
     "type": "git",
     "url": "git+https://github.com/salmandev/everything-gemini.git"
   },
+  "homepage": "https://salmandev.github.io/everything-gemini/",
   "engines": {
     "node": ">=18.0.0"
   }

package/plugins/core/plugin.json

@@ -1,3 +1,3 @@
 {
-  "name": "eagy Core Safety & Engineering"
+  "name": "Everything Gemini Core Safety & Engineering"
 }

package/plugins/python-ai/plugin.json

@@ -1,3 +1,3 @@
 {
-  "name": "eagy Python & AI Systems"
+  "name": "Everything Gemini Python & AI Systems"
 }

package/plugins/security-shield/plugin.json

@@ -1,3 +1,3 @@
 {
-  "name": "eagy Security Shield"
+  "name": "Everything Gemini Security Shield"
 }

package/plugins/web-fullstack/plugin.json

@@ -1,3 +1,3 @@
 {
-  "name": "eagy Web Fullstack Suite"
+  "name": "Everything Gemini Web Fullstack Suite"
 }

package/rules/common/AGENTS.md

@@ -1,4 +1,4 @@
-# Antigravity Core Behavioral Standards (eagy)
+# Antigravity Core Behavioral Standards (everything-gemini)
 
 These standards govern all Antigravity agent interactions within this project.
 

package/rules/common/GEMINI.md

@@ -1,4 +1,4 @@
-# Antigravity Core Behavioral Standards (eagy)
+# Antigravity Core Behavioral Standards (everything-gemini)
 
 These standards govern all Antigravity agent interactions within this project.
 

package/skills/ai-first-engineering/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: ai-first-engineering
+description: Decomposes ambiguous software requirements into deterministic milestones, executable acceptance criteria, and test-backed delivery pipelines for AI agent development.
+---
+
+# AI-First Engineering Principles & Delivery Playbook
+
+This skill establishes best practices for orchestrating high-velocity software engineering tasks with AI agents. It bridges the gap between human product intent and deterministic, zero-hallucination agent execution.
+
+---
+
+## 1. Core Directives
+
+1. **Deterministic Specification Before Code**:
+   - Never write production code based on vague requirements.
+   - Deconstruct high-level prompts into verifiable acceptance criteria (Given/When/Then).
+2. **Blast Radius Minimization**:
+   - Scope code modifications strictly to the files necessary to satisfy the feature.
+   - Guard against accidental refactoring of unrelated subsystems or styles.
+3. **Continuous Verification Loop**:
+   - Every modification must be coupled with automated validation (unit tests, integration suites, linters, or visual browser assertions).
+   - If tests fail, diagnose the root cause from the error log before modifying code.
+
+---
+
+## 2. Requirement Decomposition Matrix
+
+When given an ambiguous task (e.g., *"Make user onboarding faster"* or *"Add subscription billing"*), follow this three-stage breakdown:
+
+```
+[Ambiguous Goal] ──► [Milestone Decomposition] ──► [Executable Criteria] ──► [Zero-Regression Delivery]
+```
+
+### Stage 1: Milestone Decomposition
+Break large tasks into discrete, independently testable phases:
+- **Phase 1: Contracts & Schema**: Types, interfaces, database schemas, and API contracts.
+- **Phase 2: Failing Assertions (Red)**: Unit / integration tests validating expected behavior.
+- **Phase 3: Implementation (Green)**: Minimal surgical code satisfying the tests.
+- **Phase 4: Hardening & Docs (Refactor)**: Error handling, edge cases, logging, and documentation.
+
+### Stage 2: Executable Acceptance Criteria
+Formulate specifications using the standard Gherkin / BDD structure:
+- **Given**: Initial system state and prerequisites.
+- **When**: Specific user or API action occurs.
+- **Then**: Measurable system response, database state, or error envelope.
+
+---
+
+## 3. Risk Radius & Boundary Containment
+
+Before modifying core abstractions, evaluate the **Risk Radius**:
+
+| Radius Tier | Scope | Required Precautions |
+| :--- | :--- | :--- |
+| **Tier 1: Leaf Node** | Isolated helper functions, standalone components | Standard unit test verification |
+| **Tier 2: Service / Store** | State management, database queries, shared services | Integration tests + typechecking |
+| **Tier 3: Core Abstraction**| DB migrations, auth middleware, global config | Migration rollback plan + full test suite run |
+
+---
+
+## 4. Autonomous Debugging Protocol
+
+When encountering unexpected test failures or runtime regressions:
+
+1. **Read Full Error Trace**: Never guess or apply speculative patches without inspecting the actual stack trace.
+2. **Reproduce in Isolation**: Create a minimal reproduction test or script before touching implementation files.
+3. **Binary Search (Bisect)**: If behavior unexpectedly changed, identify the breaking commit or input change systematically.
+4. **Surgical Fix**: Apply the smallest possible fix that resolves the issue while preserving surrounding code formatting and comments.

package/skills/cloudflare-workers/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: cloudflare-workers
+description: >-
+  Use this skill when developing Cloudflare Workers, configuring Wrangler v3, integrating Cloudflare D1 SQL or KV storage, or deploying global edge APIs.
+---
+
+# Cloudflare Workers & Edge Infrastructure
+
+## Overview
+Cloudflare Workers execute on V8 isolates across 300+ edge locations worldwide. This skill provides architectural patterns for ultra-low latency serverless APIs, D1 relational databases, KV storage, and Wrangler configuration.
+
+## Procedural Workflow
+
+### 1. Project Scaffolding & Wrangler Config
+Structure `wrangler.jsonc` or `wrangler.toml` with strict environment bindings:
+```jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "edge-api",
+  "main": "src/index.ts",
+  "compatibility_date": "2024-09-23",
+  "compatibility_flags": ["nodejs_compat"],
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "prod-db",
+      "database_id": "xxxx-xxxx"
+    }
+  ],
+  "kv_namespaces": [
+    {
+      "binding": "CACHE",
+      "id": "yyyy-yyyy"
+    }
+  ]
+}
+```
+
+### 2. Edge Request Handling
+Use typed `Env` interfaces and native `fetch` handlers:
+```typescript
+export interface Env {
+  DB: D1Database;
+  CACHE: KVNamespace;
+  API_SECRET: string;
+}
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+    if (request.method === "OPTIONS") {
+      return handleCors(request);
+    }
+    // Execution context for background tasks that shouldn't block response
+    ctx.waitUntil(logAnalytics(request, env));
+    return new Response(JSON.stringify({ status: "ok" }), {
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+};
+```
+
+### 3. Edge Storage Patterns
+- **Cloudflare KV**: High-read, low-write caching (eventually consistent). Ideal for session tokens, feature flags, and redirect maps.
+- **Cloudflare D1**: Serverless SQLite at the edge. Always use parameterized queries (`env.DB.prepare("SELECT * FROM users WHERE id = ?").bind(id).first()`).
+- **Cloudflare R2**: Zero-egress S3-compatible object storage.
+
+## Verification Checklist
+- [ ] `compatibility_date` pinned to a modern version
+- [ ] Secrets managed via `wrangler secret put`, never hardcoded
+- [ ] Background telemetry wrapped in `ctx.waitUntil`
+- [ ] D1 queries use parameterized bindings to prevent SQL injection

package/skills/gemini-function-calling/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: gemini-function-calling
+description: >-
+  Designs, validates, and tests production Gemini function calling schemas, structured outputs with Pydantic/JSON Schema, parallel tool dispatch, and error recovery loops.
+---
+
+# Gemini Function Calling & Structured Outputs
+
+## Overview
+Gemini models support native, high-precision function calling and constrained JSON output schemas. This skill outlines best practices for defining deterministic tool declarations, handling parallel tool invocations, enforcing response schemas, and recovering gracefully from tool execution exceptions.
+
+## Core Capabilities
+
+### 1. Function Declarations (Tools)
+Define tools with clear semantics, parameter types, descriptions, and required constraints:
+
+```python
+from google.genai import types
+
+def get_db_schema_declaration() -> types.FunctionDeclaration:
+    return types.FunctionDeclaration(
+        name="query_database",
+        description="Executes a read-only SQL query against the application replica.",
+        parameters=types.Schema(
+            type=types.Type.OBJECT,
+            properties={
+                "query": types.Schema(
+                    type=types.Type.STRING,
+                    description="The SQL query to execute. Must be a SELECT statement."
+                ),
+                "limit": types.Schema(
+                    type=types.Type.INTEGER,
+                    description="Maximum number of rows to return (default: 50, max: 200)."
+                )
+            },
+            required=["query"]
+        )
+    )
+```
+
+### 2. Structured JSON Outputs (`response_schema`)
+When an application requires guaranteed JSON outputs matching a domain model, configure `response_mime_type="application/json"` and supply a `response_schema` (or Pydantic class):
+
+```python
+from pydantic import BaseModel, Field
+
+class CodeAnalysisReport(BaseModel):
+    summary: str = Field(description="High-level architecture assessment")
+    vulnerabilities: list[str] = Field(description="List of identified security vulnerabilities")
+    risk_score: int = Field(description="Risk rating from 1 (lowest) to 10 (critical)", ge=1, le=10)
+
+config = types.GenerateContentConfig(
+    response_mime_type="application/json",
+    response_schema=CodeAnalysisReport,
+    temperature=0.1
+)
+```
+
+### 3. Parallel & Multi-Turn Function Calling
+- **Parallel Dispatch**: Gemini can return multiple function calls in a single response turn. Process independent read operations concurrently using `asyncio.gather` or `Promise.all`.
+- **Function Response Envelope**: Return the results of each tool back to the model with matching tool names and execution status:
+
+```python
+tool_response_part = types.Part.from_function_response(
+    name="query_database",
+    response={"status": "success", "rows": rows, "count": len(rows)}
+)
+```
+
+### 4. Error Recovery & Defensive Handling
+When a tool execution fails (e.g., database timeout or syntax error):
+1. **Never suppress the error silently**: Feed the error back to Gemini in the function response envelope.
+2. **Include Contextual Remediation**: Inform the model why the call failed so it can self-correct in the next turn:
+
+```python
+error_part = types.Part.from_function_response(
+    name="query_database",
+    response={
+        "status": "error",
+        "error_code": "SYNTAX_ERROR",
+        "message": "Column 'user_id' does not exist in table 'accounts'. Available columns: [id, account_number, balance]."
+    }
+)
+```
+
+## Verification Checklist
+- [ ] Tool parameters have unambiguous `description` fields
+- [ ] `required` fields explicitly defined
+- [ ] Read-only vs destructive operations strictly separated
+- [ ] Tool execution errors safely fed back to model for autonomous self-correction

package/skills/gemini-grounding/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: gemini-grounding
+description: >-
+  Use this skill when verifying dynamic facts, researching live documentation, fact-checking technical claims, or integrating Google Search grounding into Gemini agent reasoning workflows.
+---
+
+# Gemini Search Grounding & Dynamic Fact Verification
+
+## Overview
+Gemini frontier models feature native **Google Search Grounding**, enabling agents to supplement static training weights with real-time web citations, current API documentation, and package release notes. This skill outlines best practices for search grounding, citation verification, and hallucination elimination.
+
+## Procedural Workflow
+
+### 1. Identify Grounding Triggers
+Activate search grounding when:
+- Querying rapidly evolving SDKs, library APIs, or breaking versions released after model cutoffs.
+- Verifying deployment status, cloud service outages, or public CVE advisories.
+- Researching latest framework releases (e.g., Next.js canary features, Tailwind v4, React 19).
+
+### 2. Search Query Formulation
+Formulate targeted search queries:
+- **Exact Syntax Match**: Use quotes for exact error strings or function signatures.
+- **Official Domain Prioritization**: Target authoritative documentation:
+  - `site:github.com` for issue threads and release tags.
+  - `site:npmjs.com` or `site:pypi.org` for version numbers and dependencies.
+  - Official vendor docs (`docs.antigravity.google`, `developer.mozilla.org`).
+
+### 3. Verification & Citation Attribution
+When incorporating search findings into code:
+1. **Cross-Check with Active Code**: Never assume an external snippet works as-is; inspect local types and configurations first.
+2. **Clickable Links**: Link external references using markdown links in documentation and artifacts.
+3. **Zero-Trust Validation**: Verify any third-party code against local linters (`npm test` or typecheckers).
+
+## Verification Checklist
+- [ ] Claims backed by verifiable, recent documentation
+- [ ] No hallucinated imports or deprecated APIs
+- [ ] External references properly attributed

package/skills/github-ops/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: github-ops
+description: Orchestrates GitHub workflows, automated Pull Request generation, code review triage, release management, and issue automation using GitHub MCP and the gh CLI.
+---
+
+# GitHub Ops & Repository Lifecycle Automation
+
+This skill guides the agent in managing end-to-end GitHub workflows, creating production-grade Pull Requests, performing automated multi-file code reviews, orchestrating releases, and triaging issues.
+
+---
+
+## 1. Operating Principles
+
+1. **Atomic & Linear Commits**:
+   - Keep Pull Requests focused on a single logical change or feature.
+   - Use Conventional Commits (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:`).
+2. **Deterministic Verification Before PR**:
+   - Always run the local test suite and lint verification before creating or updating a PR.
+   - Never push failing code or uncommitted working trees.
+3. **Traceability**:
+   - Every PR must link back to an issue or feature specification (`Closes #123` or `Refs #456`).
+   - Every release tag must be accompanied by an auto-generated or structured changelog.
+
+---
+
+## 2. GitHub CLI (`gh`) & MCP Integration
+
+When interacting with GitHub, use either the configured **GitHub MCP Server** or the standard **`gh` CLI**.
+
+### Essential `gh` Command Patterns
+
+| Task | Command |
+| :--- | :--- |
+| **Check Auth Status** | `gh auth status` |
+| **Inspect Open Issues** | `gh issue list --limit 10` |
+| **View Issue Details** | `gh issue view <issue-number>` |
+| **Create Pull Request** | `gh pr create --title "..." --body "..."` |
+| **View PR Status & Checks** | `gh pr status` / `gh pr checks` |
+| **View PR Diff** | `gh pr diff <pr-number>` |
+| **Add PR Comment/Review** | `gh pr review <pr-number> --comment -b "..."` |
+| **Merge Pull Request** | `gh pr merge <pr-number> --squash --delete-branch` |
+| **Create Release Tag** | `gh release create v1.1.0 --title "v1.1.0" --notes "..."` |
+
+---
+
+## 3. Pull Request Generation Workflow
+
+When authoring a Pull Request on behalf of the user, follow this structured template:
+
+```markdown
+## 🎯 Overview
+<!-- 1-2 concise sentences summarizing the problem solved or capability introduced -->
+
+## 🛠️ Changes Implemented
+- **Component / File**: High-level explanation of modification.
+- **Architectural Decision**: Rationale for design choices or trade-offs.
+
+## 🧪 Verification & Testing
+- [x] Unit / Integration tests pass (`npm test`, `pytest`, or `cargo test`).
+- [x] Linters and typecheckers pass (`npm run lint`, `tsc --noEmit`).
+- [x] Verified zero breaking changes to existing public APIs.
+
+## 🔗 Related Issues
+Closes #<issue-number>
+```
+
+---
+
+## 4. Automated PR Review Protocol
+
+When performing automated reviews on a GitHub PR:
+
+1. **Fetch & Inspect Diff**:
+   ```bash
+   gh pr diff <pr-number>
+   ```
+2. **Review Checklist**:
+   - **Correctness**: Does the code satisfy the acceptance criteria without subtle edge-case failures?
+   - **Security**: Are there unsanitized inputs, hardcoded secrets, or privilege escalations?
+   - **Performance**: Are there N+1 database queries, unmemoized expensive loops, or memory leaks?
+   - **Style & Standards**: Does it adhere to the repository's established conventions?
+3. **Submitting Feedback**:
+   - Use `gh pr review <pr-number> --comment` for non-blocking suggestions.
+   - Use `gh pr review <pr-number> --request-changes` for critical bugs or regressions.
+   - Use `gh pr review <pr-number> --approve` once all checks pass.
+
+---
+
+## 5. Release Automation
+
+To publish a clean semantic release:
+1. Verify `package.json` / version files are updated.
+2. Ensure working tree is clean (`git status`).
+3. Create and push git tag:
+   ```bash
+   git tag vX.Y.Z
+   git push origin vX.Y.Z
+   ```
+4. Generate release notes with GitHub CLI:
+   ```bash
+   gh release create vX.Y.Z --generate-notes
+   ```

package/skills/kubernetes-operator/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: kubernetes-operator
+description: >-
+  Use this skill when authoring Kubernetes manifests, configuring Helm charts, setting up Horizontal Pod Autoscalers (HPA), or troubleshooting container cluster deployments.
+---
+
+# Kubernetes Cluster & Workload Operations
+
+## Overview
+This skill guides the agent in writing declarative, production-ready Kubernetes manifests, configuring health probes, resource constraints, ingress controllers, and rolling update strategies.
+
+## Procedural Workflow
+
+### 1. Hardened Deployment Manifest Pattern
+Always configure resource limits, security contexts, and liveness/readiness probes:
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api-service
+  labels:
+    app.kubernetes.io/name: api-service
+spec:
+  replicas: 3
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 1
+      maxUnavailable: 0
+  selector:
+    matchLabels:
+      app: api-service
+  template:
+    metadata:
+      labels:
+        app: api-service
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 10001
+      containers:
+        - name: app
+          image: myregistry.azurecr.io/api-service:v1.0.0
+          securityContext:
+            readOnlyRootFilesystem: true
+            allowPrivilegeEscalation: false
+          resources:
+            requests:
+              cpu: "100m"
+              memory: "128Mi"
+            limits:
+              cpu: "500m"
+              memory: "512Mi"
+          ports:
+            - containerPort: 8080
+          readinessProbe:
+            httpGet:
+              path: /health/ready
+              port: 8080
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          livenessProbe:
+            httpGet:
+              path: /health/live
+              port: 8080
+            initialDelaySeconds: 15
+            periodSeconds: 20
+```
+
+### 2. Auto-scaling & Ingress
+- **HorizontalPodAutoscaler (HPA)**: Target CPU (e.g. 70%) and Memory utilization before traffic spikes.
+- **Ingress with TLS**: Annotate with cert-manager (`cert-manager.io/cluster-issuer: letsencrypt-prod`) for automated SSL lifecycle.
+
+### 3. Triage & Debugging Commands
+- Inspect crash loops: `kubectl logs -l app=api-service --tail=100 -p` (previous container logs).
+- Inspect pod events: `kubectl describe pod <pod-name>`.
+
+## Verification Checklist
+- [ ] Non-root security context configured (`runAsNonRoot: true`)
+- [ ] Both readiness and liveness probes defined
+- [ ] Memory limits defined to prevent cluster OOM killer cascades
+- [ ] Rolling update configured with zero downtime (`maxUnavailable: 0`)

package/skills/rag-architect/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: rag-architect
+description: >-
+  Designs retrieval-augmented generation (RAG) pipelines, semantic chunking strategies, hybrid keyword-vector search, re-ranking, and pgvector embeddings using Gemini models.
+---
+
+# RAG Architecture & Vector Retrieval with Gemini
+
+## Overview
+Retrieval-Augmented Generation (RAG) equips Gemini with localized repository context, enterprise documentation, and proprietary knowledge bases. This skill outlines production architectures for dense embeddings, semantic chunking, hybrid search (keyword + vector), and Gemini-powered re-ranking.
+
+## Core RAG Pipeline
+
+```
+[Documents] ──► [Semantic Chunker] ──► [text-embedding-004] ──► [Vector DB / pgvector]
+                                                                        │
+[User Query] ──► [Hybrid Retrieval: BM25 + Dense Vector] ───────────────┤
+                                                                        ▼
+                                                         [Gemini Reranker & Filter]
+                                                                        ▼
+                                                         [Context Window (Cached)]
+                                                                        ▼
+                                                          [Grounded Synthesis]
+```
+
+## Architectural Guidelines
+
+### 1. Embedding Model Selection
+- Use **`text-embedding-004`** (768 dimensions) for semantic vector representations.
+- Apply task types appropriately when generating embeddings:
+  - `RETRIEVAL_DOCUMENT`: For indexing documents into the knowledge store.
+  - `RETRIEVAL_QUERY`: For embedding the user's incoming query.
+  - `SEMANTIC_SIMILARITY`: For clustering and duplicate detection.
+
+### 2. Semantic Chunking Strategies
+- **Code Repositories**: Chunk by syntax boundaries (AST classes, functions, modules) rather than fixed token lengths.
+- **Documentation**: Chunk by markdown headers (`##`, `###`) preserving title hierarchy as chunk metadata.
+- **Overlap**: Maintain a 10-15% token overlap across sliding windows to prevent boundary truncation of critical concepts.
+
+### 3. Hybrid Retrieval (Sparse + Dense)
+Never rely exclusively on vector distance. Combine:
+- **Dense Vector Search**: Cosine or inner product similarity via `pgvector` or Qdrant for semantic meaning.
+- **Sparse Keyword Search**: Full-text search (BM25 or PostgreSQL `tsvector`) for exact identifier matches, error codes, and function names.
+- Combine scores using Reciprocal Rank Fusion (RRF):
+  $$RRF(d) = \sum \frac{1}{60 + r_i(d)}$$
+
+### 4. Gemini Two-Stage Reranking
+1. Retrieve top 50 candidates from hybrid search.
+2. Pass the top 50 candidate snippets to `gemini-1.5-flash` or `gemini-3.8` for high-speed relevance scoring and deduplication.
+3. Inject the top 5-10 highest-scoring excerpts into the reasoning context window.
+
+### 5. Context Injection & Static Prefix Caching
+- Structure prompt templates with static instruction prefixes placed before retrieved dynamic context to maximize Gemini's automatic **Prefix Context Caching**.
+- Tag all retrieved chunks with clickable source links: `[source.py:L10-L45](file:///path/to/source.py#L10-L45)`.
+
+## Verification Checklist
+- [ ] Appropriate embedding task types specified (`RETRIEVAL_DOCUMENT` vs `RETRIEVAL_QUERY`)
+- [ ] Chunks respect syntax and AST boundaries
+- [ ] Hybrid search active for exact symbol matching
+- [ ] Clickable `file://` citations attached to synthesized outputs