everything-gemini 2.1.0 → 2.5.0

package/skills/bigquery-vector-search/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: bigquery-vector-search
+description: Implements Google BigQuery native vector search, VECTOR_SEARCH SQL statements, ML.GENERATE_TEXT_EMBEDDING, IVF indexing, and BigLake hybrid semantic RAG.
+---
+
+# BigQuery Vector Search & Semantic Analytics
+
+Architects, indexes, and queries large-scale vector embeddings directly inside Google BigQuery using native `VECTOR_SEARCH` syntax, Inverted File (IVF) vector indexes, and `ML.GENERATE_TEXT_EMBEDDING` with Gemini models.
+
+---
+
+## 1. Architecture: BigQuery In-Database Vector Analytics
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                            Google Cloud BigQuery                            │
+│                                                                             │
+│   ┌────────────────────┐      ┌──────────────────┐      ┌─────────────────┐ │
+│   │ Structured Records │      │ Unstructured     │      │ BigLake Object  │ │
+│   │ (SQL Tables)       │      │ Text & Metadata  │      │ Tables (GCS)    │ │
+│   └─────────┬──────────┘      └────────┬─────────┘      └────────┬────────┘ │
+│             │                          │                         │          │
+│             └──────────────────┬───────┴─────────────────────────┘          │
+│                                │                                            │
+│                                ▼                                            │
+│            ┌───────────────────────────────────────────────┐                │
+│            │ ML.GENERATE_TEXT_EMBEDDING (Vertex AI Gemini) │                │
+│            │ 768-dim embeddings stored as ARRAY<FLOAT64>   │                │
+│            └───────────────────────┬───────────────────────┘                │
+│                                    │                                        │
+│                                    ▼                                        │
+│            ┌───────────────────────────────────────────────┐                │
+│            │ IVF Vector Index (Inverted File Partitioning) │                │
+│            │ Distance: COSINE / EUCLIDEAN / DOT_PRODUCT    │                │
+│            └───────────────────────┬───────────────────────┘                │
+│                                    │                                        │
+│                                    ▼                                        │
+│            ┌───────────────────────────────────────────────┐                │
+│            │ VECTOR_SEARCH + Post-Filter SQL Join          │                │
+│            │ Sub-second Top-K nearest neighbor retrieval   │                │
+│            └───────────────────────────────────────────────┘                │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. IVF Vector Indexing
+
+BigQuery supports Inverted File Flat (IVF) indexes to partition vector space into Voronoi cells, accelerating approximate nearest neighbor (ANN) retrieval across billions of rows.
+
+```sql
+-- 1. Create native vector index on embedding column
+CREATE VECTOR INDEX IF NOT EXISTS knowledge_vector_idx
+ON `my_project.agent_knowledge.document_chunks`(embedding)
+STORING(chunk_id, doc_id, section_title)
+OPTIONS(
+  index_type = 'IVF',
+  distance_type = 'COSINE',
+  ivf_options = '{"num_lists": 1000}'
+);
+```
+
+- **`num_lists`**: The number of Voronoi partitions (rule of thumb: $\sqrt{N}$ where $N$ is row count).
+- **`distance_type`**: `COSINE` (recommended for normalized embeddings), `EUCLIDEAN`, or `DOT_PRODUCT`.
+- **`STORING`**: Co-locates frequently queried payload attributes in the vector index leaf nodes, eliminating secondary table lookups.
+
+---
+
+## 3. In-Database Embeddings Generation with Gemini
+
+Connect BigQuery directly to Vertex AI Gemini text-embedding models:
+
+```sql
+-- 1. Create connection to Vertex AI Remote Model
+CREATE OR REPLACE MODEL `my_project.agent_knowledge.gemini_embedding_model`
+REMOTE WITH CONNECTION `projects/my_project/locations/us-central1/connections/vertex-ai-conn`
+OPTIONS(
+  endpoint = 'text-embedding-004'
+);
+
+-- 2. Batch generate embeddings for newly inserted document chunks
+INSERT INTO `my_project.agent_knowledge.document_chunks` (chunk_id, doc_id, content, embedding)
+SELECT
+  ml_generate_embedding_result.chunk_id,
+  ml_generate_embedding_result.doc_id,
+  ml_generate_embedding_result.content,
+  ml_generate_embedding_result.text_embedding AS embedding
+FROM ML.GENERATE_TEXT_EMBEDDING(
+  MODEL `my_project.agent_knowledge.gemini_embedding_model`,
+  (
+    SELECT chunk_id, doc_id, content
+    FROM `my_project.agent_knowledge.raw_chunks`
+    WHERE processed_at IS NULL
+  ),
+  STRUCT(
+    'RETRIEVAL_DOCUMENT' AS task_type,
+    768 AS output_dimensionality
+  )
+) AS ml_generate_embedding_result;
+```
+
+---
+
+## 4. Native `VECTOR_SEARCH` Execution
+
+Query embeddings directly with sub-second latency and zero external vector database infrastructure:
+
+```sql
+-- Top-10 semantic search with structured tenant/date pre-filtering
+SELECT
+  base.chunk_id,
+  base.doc_id,
+  base.content,
+  distance
+FROM VECTOR_SEARCH(
+  TABLE `my_project.agent_knowledge.document_chunks`,
+  'embedding',
+  (
+    -- Embed user query dynamically using Gemini
+    SELECT text_embedding AS query_vector
+    FROM ML.GENERATE_TEXT_EMBEDDING(
+      MODEL `my_project.agent_knowledge.gemini_embedding_model`,
+      (SELECT 'What are the spend limit policies for autonomous subagents?' AS content),
+      STRUCT('RETRIEVAL_QUERY' AS task_type, 768 AS output_dimensionality)
+    )
+  ),
+  top_k => 10,
+  distance_type => 'COSINE',
+  options => '{"fraction_lists_to_search": 0.05}'
+);
+```
+
+- **`fraction_lists_to_search`**: Controls recall vs. latency tradeoff (0.01 to 0.20). Higher values increase recall at slightly higher compute cost.
+
+---
+
+## 5. Hybrid Search (Lexical BM25 + Semantic Vector)
+
+Combine BigQuery native search indexes (`SEARCH`) with `VECTOR_SEARCH` using Reciprocal Rank Fusion (RRF):
+
+```sql
+WITH vector_matches AS (
+  SELECT
+    base.chunk_id,
+    base.content,
+    ROW_NUMBER() OVER (ORDER BY distance ASC) AS vector_rank
+  FROM VECTOR_SEARCH(
+    TABLE `my_project.agent_knowledge.document_chunks`,
+    'embedding',
+    (SELECT text_embedding FROM ML.GENERATE_TEXT_EMBEDDING(
+      MODEL `my_project.agent_knowledge.gemini_embedding_model`,
+      (SELECT 'subagent spend guardrails' AS content),
+      STRUCT('RETRIEVAL_QUERY' AS task_type)
+    )),
+    top_k => 50,
+    distance_type => 'COSINE'
+  )
+),
+keyword_matches AS (
+  SELECT
+    chunk_id,
+    content,
+    ROW_NUMBER() OVER () AS keyword_rank
+  FROM `my_project.agent_knowledge.document_chunks`
+  WHERE SEARCH(content, 'guardrail spend budget ceiling')
+  LIMIT 50
+)
+SELECT
+  COALESCE(v.chunk_id, k.chunk_id) AS chunk_id,
+  COALESCE(v.content, k.content) AS content,
+  (
+    COALESCE(1.0 / (60 + v.vector_rank), 0.0) +
+    COALESCE(1.0 / (60 + k.keyword_rank), 0.0)
+  ) AS rrf_score
+FROM vector_matches v
+FULL OUTER JOIN keyword_matches k ON v.chunk_id = k.chunk_id
+ORDER BY rrf_score DESC
+LIMIT 10;
+```
+
+---
+
+## 6. Enterprise Best Practices & Anti-Patterns
+
+| Category | Recommended Pattern | Anti-Pattern |
+| :--- | :--- | :--- |
+| **Index Choice** | Use IVF with `num_lists` scaled to $\sqrt{N}$ for $N > 100,000$ rows | Querying `ARRAY<FLOAT64>` with brute-force `COSINE_DISTANCE()` |
+| **Payload Storage** | Store lightweight metadata with `STORING(...)` inside index | Joining 10 high-cardinality tables after vector search |
+| **Embedding Types** | Specify `RETRIEVAL_DOCUMENT` during indexing, `RETRIEVAL_QUERY` during search | Using default task types causing asymmetric vector drift |
+| **Partitioning** | Partition and cluster base table on tenant ID or ingestion date | Single unpartitioned table forcing full-table vector scans |
+
+---
+
+## 7. CLI Runbook (`bq` CLI)
+
+```bash
+# 1. Create BigQuery dataset for vector embeddings
+bq mk --dataset --location=us-central1 my_project:agent_knowledge
+
+# 2. Check vector index status and coverage
+bq show --format=prettyjson my_project:agent_knowledge.document_chunks | jq '.vectorSearchStatistics'
+
+# 3. Dry-run vector query to estimate bytes scanned
+bq query --use_legacy_sql=false --dry_run < vector_query.sql
+```

package/skills/cloud-run-agents/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: cloud-run-agents
+description: Packages, deploys, and scales autonomous Antigravity and Gemini agents on Google Cloud Run services and Cloud Run Jobs with Eventarc triggers and GPU scheduling.
+---
+
+# Cloud Run Autonomous Agents
+
+Packages, containerizes, and deploys autonomous Google Antigravity & Gemini agents on Google Cloud Run. Covers HTTP agent services, batch-oriented Cloud Run Jobs for recursive Harness² probing, Eventarc event triggers, and NVIDIA L4 GPU acceleration.
+
+---
+
+## 1. Architecture: Cloud Run Agent Execution Models
+
+```
+                                Google Cloud Run
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ 1. CLOUD RUN SERVICE (Interactive / Webhook Agents)                         │
+│    • Real-time Gemini Live WebSocket / HTTP streaming                        │
+│    • Automatic scale-to-zero when idle                                      │
+│    • Up to 60-minute request timeout with WebSockets enabled                │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ 2. CLOUD RUN JOBS (Batch / Recursive Probing Agents)                         │
+│    • Long-running Harness² Propose-Probe-Compose workflows (up to 24 hours) │
+│    • Parallel array task execution for multi-candidate testing              │
+│    • Zero HTTP gateway overhead; triggered via Cloud Scheduler / Workflows │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ 3. CLOUD RUN WITH GPU (NVIDIA L4 / T4)                                      │
+│    • Co-locates agent logic with local verification models (vLLM / Triton)   │
+│    • Direct hardware acceleration for code analysis & AST parsing           │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Agent Container Specification (Dockerfile)
+
+Production multi-stage Dockerfile bundling the agent runtime, Node CLI, and Python SDK:
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM python:3.11-slim AS base
+
+ENV PYTHONUNBUFFERED=1 \
+    DEBIAN_FRONTEND=noninteractive \
+    PORT=8080
+
+WORKDIR /app
+
+# Install system dependencies & Node.js for CLI tools
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    git \
+    ca-certificates \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install everything-gemini CLI globally
+RUN npm install -g everything-gemini
+
+# Copy Python requirements & install
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy agent definitions and source code
+COPY . .
+
+# Run as non-root user for enterprise container security
+RUN useradd -m -u 10001 agentuser && chown -R agentuser:agentuser /app
+USER 10001
+
+EXPOSE 8080
+ENTRYPOINT ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080"]
+```
+
+---
+
+## 3. Cloud Run Service Deployment (`gcloud`)
+
+Deploy an interactive agent service with Workload Identity and automated secret injection:
+
+```bash
+gcloud run deploy antigravity-agent-service \
+  --image="gcr.io/my_project/antigravity-agent:v2.2.0" \
+  --region="us-central1" \
+  --platform="managed" \
+  --service-account="agent-runner@my_project.iam.gserviceaccount.com" \
+  --cpu=4 \
+  --memory=8Gi \
+  --concurrency=10 \
+  --timeout=3600 \
+  --min-instances=0 \
+  --max-instances=20 \
+  --set-env-vars="GEMINI_MODEL=gemini-2.0-flash,MAX_USD_BUDGET=15.00" \
+  --set-secrets="GEMINI_API_KEY=gemini-api-key:latest" \
+  --vpc-egress=private-ranges-only \
+  --ingress=internal-and-cloud-load-balancing
+```
+
+---
+
+## 4. Cloud Run Jobs for Harness² Recursive Probing
+
+When running test-time recursive optimization (Propose-Probe-Compose) that exceeds standard HTTP request limits, package the run into a Cloud Run Job:
+
+```bash
+# 1. Create Cloud Run Job with 3 parallel task instances
+gcloud run jobs create harness2-probe-runner \
+  --image="gcr.io/my_project/harness2-runner:v2.2.0" \
+  --region="us-central1" \
+  --tasks=3 \
+  --max-retries=1 \
+  --task-timeout=7200s \
+  --cpu=8 \
+  --memory=16Gi \
+  --command="everything-gemini" \
+  --args="harness2,run,--bench,local,--max-usd,25,--snapshot,--json"
+
+# 2. Trigger asynchronous execution of the probe job
+gcloud run jobs execute harness2-probe-runner --region="us-central1" --wait
+```
+
+---
+
+## 5. Eventarc Trigger Binding (Event-Driven Agent Workflow)
+
+Automatically invoke agents whenever new code repositories or error traces land in Cloud Storage:
+
+```bash
+gcloud eventarc triggers create trace-ingestion-trigger \
+  --location="us-central1" \
+  --destination-run-service="antigravity-agent-service" \
+  --destination-run-region="us-central1" \
+  --destination-run-path="/webhooks/trace-ingest" \
+  --event-filters="type=google.cloud.storage.object.v1.finalized" \
+  --event-filters="bucket=production-failure-traces" \
+  --service-account="eventarc-invoker@my_project.iam.gserviceaccount.com"
+```
+
+---
+
+## 6. NVIDIA L4 GPU Configuration
+
+Accelerate on-container verification models or local embedding calculations:
+
+```bash
+gcloud beta run deploy local-verifier-agent \
+  --image="gcr.io/my_project/verifier-agent-l4:latest" \
+  --region="us-central1" \
+  --cpu=8 \
+  --memory=32Gi \
+  --gpu=1 \
+  --gpu-type=nvidia-l4 \
+  --no-cpu-throttling \
+  --timeout=1800
+```
+
+---
+
+## 7. Enterprise Production Checklist
+
+| Category | Requirement | Verification Method |
+| :--- | :--- | :--- |
+| **IAM Security** | Dedicated service account with least-privilege Vertex AI roles | `roles/aiplatform.user` only; no Owner/Editor permissions |
+| **Secret Management** | Mount API keys directly from Google Secret Manager | Use `--set-secrets`; never bake keys into Docker layers |
+| **Budget Enforcement** | Enforce `--set-env-vars="MAX_USD_BUDGET=..."` bound to `budget-guard` | Verification in PreToolUse hook |
+| **Graceful Shutdown** | Handle `SIGTERM` within 10s to flush ephemeral logs to Cloud Storage | Python `signal.signal(signal.SIGTERM, handler)` |

package/skills/context-warmer/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: context-warmer
+description: Analyzes active repository workspace structure, clusters knowledge items, and pre-warms Gemini prefix context caches (1M-2M+ tokens) before long-running multi-agent invocations.
+---
+
+# Gemini Context Warmer (Prefix Cache Orchestration)
+
+Automates prefix context cache pre-warming for Google Gemini 2.0 and 3.8 models, maximizing cache hit rates, lowering token expenditure by up to 75%, and slashing time-to-first-token (TTFT) from seconds to milliseconds across long-running Antigravity agent loops.
+
+---
+
+## 1. Architectural Strategy
+
+Gemini Context Caching uses **deterministic prefix matching** over an immutable sequence of static tokens. The `context-warmer` skill structures repository knowledge into an optimal cache hierarchy:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ 1. FROZEN PREFIX (Cached via google-genai client.caches.create)             │
+│    ├── System Directives & Security Rules (rules/common/GEMINI.md)          │
+│    ├── Multi-Agent Interaction Protocols (rules/common/AGENTS.md)           │
+│    ├── Repository Structural Map & Dependency Schemas                       │
+│    └── Workspace Knowledge Items (<appDataDir>/knowledge/)                  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ 2. DYNAMIC TURN SUFFIX (Uncached - Sent with each execution turn)           │
+│    ├── Active User Objective & Incremental Task Diff                        │
+│    └── Recent Execution Logs / Transient Subagent Scratchpad                │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Thresholds & Cost Efficiency
+
+| Metric | Non-Cached Gemini Turn | Context-Warmed Prefix Cache | Efficiency Gain |
+| :--- | :--- | :--- | :--- |
+| **Input Cost** | $0.075 / 1M tokens | $0.01875 / 1M tokens | **75% Cost Reduction** |
+| **TTFT Latency** | 2,800ms - 4,500ms | 280ms - 450ms | **10x Faster First Token** |
+| **Minimum Tokens** | 1 token | 32,768 tokens minimum | Optimal at >100k tokens |
+| **Default TTL** | None (ephemeral) | 3,600s (1 hour, auto-refresh) | Sustained across sessions |
+
+---
+
+## 3. Python SDK Cache Warming Implementation
+
+Use the official `google-genai` SDK to construct and warm the persistent prefix cache before orchestrating subagents:
+
+```python
+import os
+from datetime import timedelta
+from google import genai
+from google.genai import types
+
+def prewarm_workspace_cache(
+    workspace_root: str,
+    model: str = "gemini-2.0-flash",
+    ttl_minutes: int = 60
+) -> str:
+    """Scans workspace KIs, builds frozen prefix content, and creates cached content resource."""
+    client = genai.Client()
+
+    # 1. Collate static rules and Knowledge Items (KIs)
+    static_documents = []
+    rules_path = os.path.join(workspace_root, "rules", "common", "GEMINI.md")
+    if os.path.exists(rules_path):
+        with open(rules_path, "r", encoding="utf-8") as f:
+            static_documents.append(f.read())
+
+    # 2. Gather repository knowledge items
+    ki_root = os.path.expanduser("~/.gemini/knowledge")
+    if os.path.exists(ki_root):
+        for root, _, files in os.walk(ki_root):
+            for file in files:
+                if file.endswith((".md", ".json", ".yaml")):
+                    with open(os.path.join(root, file), "r", encoding="utf-8") as f:
+                        static_documents.append(f.read())
+
+    combined_content = "\n\n---\n\n".join(static_documents)
+
+    # 3. Create frozen context cache
+    cache = client.caches.create(
+        model=model,
+        config=types.CreateCachedContentConfig(
+            contents=[types.Content(parts=[types.Part.from_text(combined_content)])],
+            display_name="everything-gemini-workspace-cache",
+            ttl=f"{ttl_minutes * 60}s",
+        )
+    )
+
+    print(f"🔥 Cache Warmed Successfully! Cache Name: {cache.name}")
+    print(f"⏱️  TTL: {ttl_minutes} minutes | Expires at: {cache.expire_time}")
+    return cache.name
+
+def invoke_cached_subagent(cache_name: str, task_prompt: str, model: str = "gemini-2.0-flash"):
+    """Invokes multi-agent query referencing the warmed prefix cache."""
+    client = genai.Client()
+    response = client.models.generate_content(
+        model=model,
+        contents=task_prompt,
+        config=types.GenerateContentConfig(
+            cached_content=cache_name,
+            temperature=0.2,
+        )
+    )
+    return response.text
+```
+
+---
+
+## 4. TypeScript / Node.js Warming Pattern
+
+```typescript
+import { GoogleGenAI } from '@google/genai';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export async function warmPrefixContext(repoRoot: string): Promise<string> {
+  const ai = new GoogleGenAI();
+  const rules = fs.readFileSync(path.join(repoRoot, 'rules', 'common', 'GEMINI.md'), 'utf8');
+
+  const cache = await ai.caches.create({
+    model: 'gemini-2.0-flash',
+    config: {
+      displayName: 'antigravity-repo-cache',
+      ttl: '3600s',
+      contents: [{ role: 'user', parts: [{ text: rules }] }]
+    }
+  });
+
+  return cache.name;
+}
+```
+
+---
+
+## 5. Verification Checklist
+
+- [ ] Static prefix exceeds the minimum 32k token threshold.
+- [ ] No variable nonces, random seeds, or dynamic timestamps are embedded in the static prefix.
+- [ ] Subagent invocations specify `cached_content=cache.name`.
+- [ ] TTL refreshed before expiration for long-running recursive optimization loops.

package/skills/cost-oracle-finops/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: cost-oracle-finops
+description: Pre-flight predictive token cost modeling, spend budgeting, and pricing tier optimization for Gemini 2.0 Flash, Pro, and Gemini 3.8 extended reasoning agents.
+---
+
+# Cost Oracle & FinOps Agent Modeling
+
+Implements pre-flight predictive token cost estimation, model pricing tier arbitrage, and autonomous budget forecasting for multi-agent workflows across Google Gemini 2.0 Flash, Gemini 2.0 Pro, and Gemini 3.8 models.
+
+---
+
+## 1. Architecture: Pre-Flight Financial Oracle
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        PRE-FLIGHT COST ORACLE ENGINE                        │
+│                                                                             │
+│   ┌─────────────────────┐                                                   │
+│   │ Proposed Task &     │                                                   │
+│   │ Subagent Trajectory │                                                   │
+│   └──────────┬──────────┘                                                   │
+│              │                                                              │
+│              ▼                                                              │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 1. Token Predictor (Context Caching vs. Dynamic Suffix Heuristics)  │   │
+│   │    • System & Skill Frontmatter Tokens                              │   │
+│   │    • Expected Reasoning Depth (Extended Thinking Tokens)            │   │
+│   │    • Tool Call Frequency & Speculative Probing Branches             │   │
+│   └──────────────────────────────────┬──────────────────────────────────┘   │
+│                                      │                                      │
+│                                      ▼                                      │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 2. FinOps Pricing Engine (Per Model Rates & Discount Tiers)        │   │
+│   │    • Gemini 2.0 Flash: $0.075 / 1M input, $0.30 / 1M output         │   │
+│   │    • Context Caching: 75% input discount ($0.01875 / 1M input)      │   │
+│   │    • Gemini 2.0 Pro: $1.25 / 1M input, $5.00 / 1M output            │   │
+│   └──────────────────────────────────┬──────────────────────────────────┘   │
+│                                      │                                      │
+│                                      ▼                                      │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 3. Pre-Flight Financial Gating (Pass / Downgrade / Deny)            │   │
+│   │    • If Expected Cost > MAX_USD_BUDGET -> Abort or switch to Flash  │   │
+│   │    • If Expected Cost <= Budget Ceiling -> Issue Financial Clearance │ │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Mathematical Cost Modeling Formula
+
+Let $T_{in}$ be input tokens, $T_{cache}$ be context-cached prefix tokens, $T_{out}$ be output generation tokens, and $T_{think}$ be internal reasoning tokens:
+
+$$\text{Cost} = (T_{cache} \times P_{cache}) + ((T_{in} - T_{cache}) \times P_{in}) + ((T_{out} + T_{think}) \times P_{out})$$
+
+Where for **Gemini 2.0 Flash**:
+- $P_{in} = \$0.075 / 10^6$
+- $P_{cache} = \$0.01875 / 10^6$
+- $P_{out} = \$0.30 / 10^6$
+
+---
+
+## 3. Python Pre-Flight Cost Estimator
+
+```python
+from dataclasses import dataclass
+from typing import Dict, Any
+
+@dataclass
+class CostEstimate:
+    model: str
+    expected_input_tokens: int
+    cached_prefix_tokens: int
+    expected_output_tokens: int
+    expected_thinking_tokens: int
+    estimated_usd: float
+    confidence_interval: tuple[float, float]
+
+class FinOpsCostOracle:
+    RATES = {
+        "gemini-2.0-flash": {
+            "input": 0.075 / 1_000_000,
+            "cache": 0.01875 / 1_000_000,
+            "output": 0.30 / 1_000_000
+        },
+        "gemini-2.0-pro": {
+            "input": 1.25 / 1_000_000,
+            "cache": 0.3125 / 1_000_000,
+            "output": 5.00 / 1_000_000
+        }
+    }
+
+    def estimate_task_cost(
+        self,
+        model: str,
+        prompt_length: int,
+        active_skills_count: int,
+        estimated_turns: int = 5,
+        uses_extended_thinking: bool = False
+    ) -> CostEstimate:
+        rates = self.RATES.get(model, self.RATES["gemini-2.0-flash"])
+        
+        # Heuristics based on empirical benchmarks
+        cached_prefix = 32_768 if active_skills_count > 10 else 0
+        input_per_turn = prompt_length + (active_skills_count * 250)
+        output_per_turn = 800
+        thinking_per_turn = 2048 if uses_extended_thinking else 0
+        
+        total_input = input_per_turn * estimated_turns
+        total_output = output_per_turn * estimated_turns
+        total_thinking = thinking_per_turn * estimated_turns
+        
+        cost = (
+            (cached_prefix * rates["cache"]) +
+            (max(0, total_input - cached_prefix) * rates["input"]) +
+            ((total_output + total_thinking) * rates["output"])
+        )
+        
+        # 95% Confidence Interval (+/- 25% due to variable branching)
+        ci = (round(cost * 0.75, 4), round(cost * 1.35, 4))
+        
+        return CostEstimate(
+            model=model,
+            expected_input_tokens=total_input,
+            cached_prefix_tokens=cached_prefix,
+            expected_output_tokens=total_output,
+            expected_thinking_tokens=total_thinking,
+            estimated_usd=round(cost, 4),
+            confidence_interval=ci
+        )
+```
+
+---
+
+## 4. Enterprise FinOps Best Practices
+
+| Strategy | Action | Benefit |
+| :--- | :--- | :--- |
+| **Model Cascading** | Use Gemini 2.0 Flash for verification; reserve Pro for system design | Up to 80% cost reduction |
+| **Prefix Freezing** | Maintain minimum 32,768 tokens in static prefix to qualify for context caching | 75% discount on repeated turns |
+| **Budget Ceiling** | Enforce `--max-usd` via `hooks/budget-guard` | Guarantees zero surprise runaway charges |
+| **Thinking Caps** | Constrain `max_thinking_tokens` on speculative probes | Prevents unbounded internal reasoning loops |