egeo 2.0.0__tar.gz

egeo-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vera Badias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

egeo-2.0.0/PKG-INFO

@@ -0,0 +1,662 @@
+Metadata-Version: 2.4
+Name: egeo
+Version: 2.0.0
+Summary: E-GEO: runtime-agnostic Generative Engine Optimization toolkit and CLI.
+Author: Vera Badias
+License: MIT
+Project-URL: Homepage, https://egeoagents.com
+Project-URL: Repository, https://github.com/mverab/eGEOagents
+Project-URL: Documentation, https://egeoagents.com/docs/getting-started/
+Keywords: geo,generative-engine-optimization,ai-search,llm,cli
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jsonschema>=4.0
+Dynamic: license-file
+
+<div align="center">
+
+<!-- HERO BANNER -->
+<img src="assets/hero-banner.png" alt="E-GEO: Rank #1 in AI Search Engines" width="100%" />
+
+<br />
+
+# 🌍 E-GEO
+
+### **Generative Engine Optimization (GEO)** & **Answer Engine Optimization (AEO)** for AI-Powered Search
+
+<p>
+  <a href="https://github.com/mverab/eGEOagents/actions/workflows/ci.yml"><img src="https://github.com/mverab/eGEOagents/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License" /></a>
+  <a href="https://github.com/mverab/eGEOagents/stargazers"><img src="https://img.shields.io/github/stars/mverab/eGEOagents?style=social" alt="GitHub Stars" /></a>
+  <a href="https://github.com/mverab/eGEOagents/network/members"><img src="https://img.shields.io/github/forks/mverab/eGEOagents?style=social" alt="GitHub Forks" /></a>
+  <a href="https://github.com/mverab/eGEOagents/issues"><img src="https://img.shields.io/github/issues/mverab/eGEOagents" alt="Issues" /></a>
+  <a href="https://arxiv.org/abs/2511.20867"><img src="https://img.shields.io/badge/arXiv-2511.20867-b31b1b.svg" alt="Research Paper" /></a>
+</p>
+
+<p>
+  <a href="https://claude.com/claude-code"><img src="https://img.shields.io/badge/Built%20with-Claude%20Code-8B5CF6?logo=anthropic" alt="Built with Claude Code" /></a>
+  <a href="CONTRIBUTING.md#ai-transparency"><img src="https://img.shields.io/badge/🤖-AI--Assisted-blueviolet" alt="AI-Assisted" /></a>
+</p>
+
+<br />
+
+> **🚀 One command. Premium results.**<br />
+> Rank higher in **ChatGPT**, **Perplexity**, **Claude**, and **Gemini**.
+
+<br />
+
+[**📖 Docs**](docs/getting-started.md) • [**🐛 Issues**](https://github.com/mverab/eGEOagents/issues) • [**💬 Discussions**](https://github.com/mverab/eGEOagents/discussions) • [**📝 Research Paper**](https://arxiv.org/abs/2511.20867)
+
+---
+
+</div>
+
+<!-- AI TRANSPARENCY BADGE -->
+<p align="center">
+  <sub>🤖 <strong>AI-Assisted Development</strong> — <a href="CONTRIBUTING.md#ai-transparency">See what's AI-generated vs human-authored</a></sub>
+</p>
+
+---
+
+## ✨ What is E-GEO?
+
+<table>
+<tr>
+<td width="60%">
+
+**E-GEO** is an open-source **Generative Engine Optimization (GEO)** and **Answer Engine Optimization (AEO)** toolkit that transforms your website content to rank higher in AI-powered search engines — including **ChatGPT**, **Perplexity**, **Google AI Overviews**, **Claude**, and **Gemini**.
+
+Also known as **AI SEO** or **LLM SEO**, GEO is the practice of optimizing content so that generative AI engines can crawl, understand, cite, and recommend it. E-GEO automates this entire process.
+
+Based on the [E-GEO research preprint](https://arxiv.org/abs/2511.20867) (arXiv:2511.20867), it applies **10 research-derived features** — including competitive framing, citation optimization, structured data, and semantic density improvements — as documented in the paper's experiments.
+
+- ✅ **No learning curve** — One command to optimize
+- ✅ **Research-backed** — Based on published GEO research
+- ✅ **Production-ready** — Copy-paste optimized content
+- ✅ **Multi-engine** — Optimizes for ChatGPT, Perplexity, Gemini, Claude & Google AI Overviews
+- ✅ **Full pipeline** — Analyze → Rank → Rewrite → Schema in one command
+
+</td>
+<td width="40%">
+
+```bash
+/geo https://yoursite.com/pricing
+```
+
+↓
+
+```
+geo-output/
+├── report.md
+├── optimized/
+│   └── pricing.md
+└── schema/
+    └── pricing.json
+```
+
+</td>
+</tr>
+</table>
+
+---
+
+## 📈 Why AI Visibility Matters in 2026
+
+AI search engines give one synthesized answer and cite a handful of sources. If your site isn't one of them, you're invisible — even if you rank #1 on Google.
+
+```
+User asks ChatGPT: "What's the best GEO tool?"
+
+ChatGPT: "According to [Competitor], the best tool is..."
+          ↑ They get cited. You don't.
+```
+
+- **ChatGPT serves 900M+ weekly users** — a growing share of sessions that used to be Google searches.
+- **28.3% of ChatGPT's most-cited pages have *zero* organic visibility on Google** (Ahrefs) — AI engines reward different signals than classic SEO.
+- **Proper JSON-LD schema lifts LLM extraction accuracy from 16% to 54%** (Semrush study on GPT-4).
+- **844,000+ sites** already ship an `llms.txt`. Is yours one of them?
+
+Traditional SEO optimizes for blue links. **GEO optimizes for citations in AI-generated answers.** E-GEO is the open-source tool that bridges this gap.
+
+---
+
+## 🚀 Quick Start (3 Steps)
+
+### 1. Install
+
+Copy the `.claude/` folder to your project:
+
+```bash
+cp -r /path/to/eGEOagents/.claude .
+```
+
+### 2. Activate
+
+In Claude Code, switch to GEO mode:
+
+```
+/output-style geo-optimizer
+```
+
+### 3. Optimize
+
+Run your first optimization:
+
+```
+/geo https://yoursite.com
+```
+
+---
+
+## 🧩 Install as Skills (skills.sh)
+
+Install the complete skill collection:
+
+```bash
+npx skills add https://github.com/mverab/eGEOagents
+```
+
+Install one skill only:
+
+```bash
+npx skills add https://github.com/mverab/eGEOagents --skill competitive-analysis
+```
+
+Validate parser discovery before shipping updates:
+
+```bash
+npx skills add https://github.com/mverab/eGEOagents --list
+```
+
+Verify indexing pages:
+
+- Collection: [skills.sh/mverab/egeoagents](https://skills.sh/mverab/egeoagents)
+- Owner: [skills.sh/mverab](https://skills.sh/mverab)
+
+---
+
+## 📋 Commands
+
+| Command | What it does |
+|---------|--------------|
+| `/geo <url>` | **Full pipeline** - Analyze, rank, rewrite, schema |
+| `/geo:audit <url>` | Analysis only, no changes |
+| `/geo:optimize <file>` | Optimize local content file |
+| `/geo:batch <folder>` | Process entire folder |
+| `/geo:report` | Generate executive report |
+| `/geo:compete <query>` | Competitive analysis |
+| `/geo:loop <domain>` | One bounded [loop-mode](#-loop-mode-continuous-geo) iteration over a workspace domain |
+
+---
+
+## 📊 What You Get
+
+After running `/geo`:
+
+```
+geo-output/
+├── report.md           # Executive summary + scores
+├── analysis.json       # Raw analysis data
+├── optimized/
+│   └── pricing.md      # Rewritten content (ready to use)
+├── schema/
+│   └── pricing.json    # JSON-LD markup (copy to site)
+└── checklist.md        # Step-by-step implementation
+```
+
+---
+
+## 🎯 Results: Backed by Research
+
+E-GEO is grounded in the research described in the [E-GEO preprint](https://arxiv.org/abs/2511.20867) (arXiv:2511.20867), building on foundational work by [Aggarwal et al. (Princeton, KDD 2024)](https://arxiv.org/abs/2311.09735) — the original study that defined Generative Engine Optimization as a discipline.
+
+The E-GEO paper reports that:
+
+1. **Competitive framing** produces the strongest immediate ranking lift among all GEO strategies tested.
+2. A **universal optimization strategy** (applying all 10 features together) outperforms individual heuristics by a wide margin.
+3. The **10 GEO features** (ranking emphasis, user intent matching, competitive edge, social proof, authority signals, scannability, citation density, structured data, factual language, and freshness) consistently appear in higher-ranking content across ChatGPT, Perplexity, and Gemini.
+
+| Feature | What E-GEO Does |
+|---------|-----------------|
+| **Ranking Emphasis** | Positions your content as the top choice |
+| **User Intent** | Directly answers what users are looking for |
+| **Competitive Edge** | Highlights your unique advantages |
+| **Social Proof** | Integrates trust signals and testimonials |
+| **Authority** | Establishes expert, confident tone |
+| **Scannability** | Structures for easy AI parsing |
+
+Results vary by content quality and competition. See the paper for full methodology and findings: [arXiv:2511.20867](https://arxiv.org/abs/2511.20867).
+
+---
+
+## 🧪 Reproducible Results
+
+E-GEO ships an evaluation harness so you can measure prompt quality yourself —
+no trust required. It scores whether the GEO rewriter moves a target item *up*
+in an LLM-simulated ranking.
+
+```bash
+pip install pyyaml jsonschema
+
+# Deterministic, offline smoke run (no API key needed)
+GEO_EVAL_MOCK=1 python geo_eval.py evaluate \
+  --dataset eval/datasets/geo_smoke.jsonl --limit 5 --verbose
+```
+
+This is the exact check that runs in [CI](.github/workflows/ci.yml) on every
+pull request. Reported metrics: `avg_rank_improvement`, `win_rate`, and
+`stderr_rank_improvement`.
+
+> **Honest scope:** these numbers are a **proxy** produced by an LLM-ranker, not
+> a measurement of real ChatGPT/Perplexity rankings. See
+> **[docs/evaluation.md](docs/evaluation.md)** for the full methodology,
+> metric definitions, and limitations.
+
+---
+
+## 🖥️ Standalone CLI (`egeo`)
+
+Beyond Claude Code, E-GEO ships a **runtime-agnostic command line** so the same
+GEO engine runs anywhere Python runs — local shells, notebooks, Docker, or CI.
+The CLI is a thin wrapper around the **exact same** `geo_eval.py` and
+`llm_client.py` modules used by the Claude Code agents, so there is **no
+duplicated optimization logic** — both runtimes share one source of truth.
+
+### Install
+
+```bash
+# From the repo root — installs the `egeo` console script + deps
+pip install -e .
+
+# ...or run without installing (deps: pip install pyyaml jsonschema)
+python -m egeo --help
+```
+
+### Commands
+
+| Command | What it does |
+|---------|--------------|
+| `egeo optimize <file>` | **Full pipeline** — analyze → rank → rewrite → schema, writes `report.md`, `optimized/*.md`, `schema/*.json`, `analysis.json` |
+| `egeo evaluate` | Run the evaluation harness (reuses `geo_eval.py`, identical metrics) |
+| `egeo optimize-prompts` | Meta-optimize the rewriter prompt (non-destructive by default) |
+| `egeo runtimes` | List available runtime adapters and their status |
+| `egeo loop <run\|collect\|doctor>` | [Loop mode](#-loop-mode-continuous-geo) — plan a run, run a collector, or check the workspace |
+
+```bash
+# Optimize a local content file (output dir defaults to ./geo-output)
+egeo optimize examples/sample-input.md --out-dir ./geo-output
+
+# Score prompt quality on a dataset
+egeo evaluate --dataset eval/datasets/geo_smoke.jsonl --limit 5
+
+# Inspect the runtime adapters
+egeo runtimes
+```
+
+### Offline / deterministic mode
+
+Every command honors `GEO_EVAL_MOCK=1`, which swaps in a deterministic mock LLM
+client — **no API key required**. This is exactly how the CLI is exercised in
+[CI](.github/workflows/ci.yml):
+
+```bash
+GEO_EVAL_MOCK=1 egeo optimize examples/sample-input.md --out-dir /tmp/egeo
+GEO_EVAL_MOCK=1 egeo evaluate --dataset eval/datasets/geo_smoke.jsonl --limit 3
+```
+
+### Supported Runtimes
+
+E-GEO exposes a small **runtime adapter** layer so the same agents (Analyzer,
+Ranker, Rewriter, Indexer) can be driven by different execution hosts:
+
+| Runtime | Aliases | Mode | Status | Description |
+|---------|---------|------|:------:|-------------|
+| **`python`** | `cli`, `local` | in-process | ✅ Available | Pure-Python runtime behind the `egeo` CLI. Runs the full pipeline in-process and honors `GEO_EVAL_MOCK` for offline, deterministic runs. |
+| **`claude-code`** | `claude` | host-executed | ✅ Available | Executes the `.claude/` agents through Claude Code `/geo` slash commands on the host. Auto-detected when a `.claude/` directory is present. |
+
+> Run `egeo runtimes` to print the live status of each adapter in your
+> environment. Additional hosts (Cursor, Codex, Windsurf, …) can be added by
+> implementing the `RuntimeAdapter` interface in
+> [`egeo/runtimes.py`](egeo/runtimes.py).
+
+---
+
+## 🔁 Loop Mode (continuous GEO)
+
+One-shot GEO answers *"how is this page doing today?"*. **Loop mode** answers
+*"what changed, and what should I do about it?"* — week after week, without you
+asking. It is fully **opt-in**: `/geo <url>` and `egeo optimize` behave exactly
+as before and never need a workspace.
+
+### The workspace (`$EGEO_HOME`)
+
+All loop state lives **outside the repo**, in the workspace resolved from
+`$EGEO_HOME` (default `~/.egeo/`), so `git pull` never touches your data:
+
+```
+$EGEO_HOME/
+├── LOG.md                        # append-only activity feed (one line per event)
+├── config.yaml                   # cadence, models, budgets, scaling weights
+├── project.yaml                  # portable project identity, targets, guardrails
+├── SUBSTRATE.md                  # the contract, vendored on bootstrap
+├── signals/<slug>.md             # evidence — deduped, frequency-counted
+├── docs/<slug>.md                # durable knowledge — analyses, decisions
+├── data/<collector>/*.jsonl      # raw collector output (not artifacts)
+├── domains/<loop>/README.md      # charter: focus, backlog, run Timeline
+└── prompts/                      # optimized prompts (repo prompts/ stay pristine)
+```
+
+The layout and the artifact rules are defined by [`SUBSTRATE.md`](SUBSTRATE.md)
+and mechanically enforced by `python -m egeo.substrate_lint`.
+
+`project.yaml` is optional during migration. When present, it is the validated
+source for the active project's canonical domain, tracked queries, tracked
+pages, and anti-spam/canibalization guardrails. `config.yaml` remains the
+machine-facing loop configuration. If `project.yaml` is absent, collectors use
+the legacy `config.yaml` fields and `egeo loop doctor` reports that fallback.
+See [`examples/project.yaml`](examples/project.yaml) for the portable contract.
+
+### Commands
+
+| Command | What it does |
+|---------|--------------|
+| `egeo loop doctor` | Bootstrap the workspace if missing, then health-check it (layout, config, budgets, substrate lint) |
+| `egeo loop decide` | Rank exactly one next action from collector JSONL + the outcome ledger (LLM-free; never publishes) |
+| `egeo loop collect serp` | Record a search-result snapshot (Brave API) into `data/serp/*.jsonl` |
+| `egeo loop collect page` | Record a page snapshot (hash, title, meta, JSON-LD types, word count) into `data/page/*.jsonl` |
+| `egeo loop run <domain>` | Resolve and print the run plan — current focus, fresh collector deltas, candidate signals |
+| `/geo:loop <domain>` | Execute one bounded loop iteration in Claude Code (the agent does the interpretive work) |
+
+```bash
+# 1. Create the workspace
+egeo loop doctor
+
+# 2. Describe what you want watched: $EGEO_HOME/domains/example-com/README.md
+#    (## Charter, ## Cadence, ## Current focus, ## Backlog, ## Timeline)
+
+# 3. Collect ground truth
+export BRAVE_API_KEY=...
+egeo loop collect serp --query "best geo tool" --target-domain example.com
+egeo loop collect page --url https://example.com/pricing
+
+# 4. See what a run would do — writes nothing
+egeo loop run example-com --dry-run
+
+# 5. Do the run (Claude Code, or headless)
+claude -p "/geo:loop example-com"
+```
+
+`egeo loop run` is **LLM-free by design**: it is the trigger seam that prepares
+and validates the plan. The reasoning happens in
+[`.claude/skills/geo-loop/SKILL.md`](.claude/skills/geo-loop/SKILL.md), which
+enforces the run contract: **one** unit of work, **one** Timeline entry ending in
+`Outcome: success|partial|failure|no-op`, **one** `LOG.md` line, verified before
+exit.
+
+### Collectors
+
+Collectors are the loop's senses: deterministic, LLM-free, budget-aware, and
+append-only. Every collector honours the same 10-point contract
+([`collectors/README.md`](collectors/README.md)) — in short: write JSONL to
+`$EGEO_HOME/data/<name>/`, one record per observation with a `schema_version`,
+respect the daily budget in `config.yaml`, append exactly one `LOG.md` line per
+pass, and **fail loudly** instead of writing a partial or fabricated record.
+
+| Collector | Needs | Output |
+|-----------|-------|--------|
+| `serp` | `BRAVE_API_KEY` | Top-10 results per query + your target's position |
+| `page` | nothing | `content_hash`, title, meta description, JSON-LD types, word count |
+
+Both accept `--fixture` for offline, deterministic runs — that is how they are
+tested without touching the network.
+
+### Scheduling (Hermes cron reference)
+
+Any scheduler drives the same commands. Pin **provider and model per job**, and
+for anything more frequent than weekly deliver **locally** and let a weekly
+digest do the notifying:
+
+```
+# hourly — local delivery only (JSONL + LOG line, no notification)
+0 * * * *   provider=anthropic model=claude-sonnet-4-5 deliver=local \
+            egeo loop collect page --url https://example.com/pricing
+
+# daily — one bounded loop run
+30 6 * * *  provider=anthropic model=claude-sonnet-4-5 deliver=local \
+            claude -p "/geo:loop example-com"
+
+# weekly — the only job that pings you
+0 9 * * 1   provider=anthropic model=claude-opus-4-1 deliver=notify \
+            claude -p "Summarize $EGEO_HOME/LOG.md for the past 7 days"
+```
+
+---
+
+## 🆚 E-GEO vs Other GEO Tools
+
+| Feature | E-GEO | GEO Optimizer | GEO-optim/GEO | Awesome GEO | Traditional SEO |
+|---------|-------|---------------|---------------|-------------|----------------|
+| **Type** | CLI + Claude Code | CLI + MCP | Research repo | Curated list | — |
+| **Content Rewriting** | ✅ Full pipeline | ⚠️ Audit only | ❌ | ❌ | ❌ No |
+| **AI-Ranking Simulation** | ✅ LLM-based | ❌ | ❌ | ❌ | ❌ No |
+| **Schema Generation** | ✅ Auto JSON-LD | ⚠️ Partial | ❌ | ❌ | ❌ Manual |
+| **Competitive Analysis** | ✅ Built-in | ❌ | ❌ | ❌ | ❌ No |
+| **Academic Foundation** | ✅ [arXiv:2511.20867](https://arxiv.org/abs/2511.20867) | ✅ KDD 2024 | ✅ Original GEO paper | ❌ | ❌ Heuristics |
+| **Multi-Runtime** | ✅ Python + Claude Code | ✅ Python + MCP | ❌ | ❌ | ❌ |
+| **llms.txt Support** | ✅ | ✅ | ❌ | 📖 Listed | ❌ |
+| **Cost** | Free / MIT | Free / MIT | Free | Free | Expensive |
+
+> **E-GEO is the only open-source GEO tool that combines content rewriting, ranking simulation, and schema generation in a single pipeline.** Others focus on auditing or listing — E-GEO does the full optimization.
+
+---
+
+## 💎 Premium Output
+
+E-GEO delivers outputs that look like they came from a $100M company:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  🎯 GEO AUDIT REPORT                                        │
+├─────────────────────────────────────────────────────────────┤
+│  URL: yoursite.com/pricing                                  │
+│  Score: 78/100                                              │
+│  Ranking Potential: ████████░░ 78%                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ✅ STRENGTHS                                               │
+│  • Clear value proposition                                  │
+│  • Good content structure                                   │
+│                                                             │
+│  ⚠️ GAPS                                                    │
+│  • Missing social proof → Add customer count                │
+│  • No urgency signals → Add limited-time offer              │
+│                                                             │
+│  📈 PRIORITY ACTIONS                                        │
+│  1. Add testimonials (+15 points)                           │
+│  2. Include pricing comparison (+10 points)                 │
+│  3. Add schema markup (+5 points)                           │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🤖 How It Works
+
+<div align="center">
+
+<!-- SYSTEM DIAGRAM -->
+<img src="assets/egeo-agents.png" alt="E-GEO Multi-Agent System" width="600" />
+
+</div>
+
+<br />
+
+E-GEO uses **4 specialized AI agents** orchestrated by Claude Code:
+
+| Agent | What it does | Output |
+|:------|:-------------|:-------|
+| 🔍 **Analyzer** | Extracts content, scores GEO signals, identifies gaps | `analysis.json` |
+| 📊 **Ranker** | Simulates AI-engine ranking, predicts positions | Baseline score |
+| ✍️ **Rewriter** | Optimizes content while preserving brand voice | `optimized/*.md` |
+| 🗂️ **Indexer** | Generates schema markup and technical assets | `schema/*.json` |
+
+---
+
+## 📁 What's Included
+
+```
+.claude/
+├── CLAUDE.md                    # System knowledge base
+├── output-styles/
+│   └── geo-optimizer.md         # Premium formatting mode
+├── agents/
+│   ├── geo-analyzer.md          # Content analysis
+│   ├── geo-rewriter.md          # Content optimization
+│   ├── geo-ranker.md            # Ranking simulation
+│   └── geo-indexer.md           # Schema generation
+├── skills/
+│   ├── competitive-analysis/    # Auto-triggered competitor analysis
+│   ├── content-scoring/         # Auto-triggered scoring
+│   ├── schema-generator/        # Auto-triggered schema
+│   └── geo-loop/                # Loop-mode run contract
+└── commands/
+    ├── geo.md                   # Main command
+    ├── geo-audit.md
+    ├── geo-optimize.md
+    ├── geo-batch.md
+    ├── geo-report.md
+    ├── geo-compete.md
+    └── geo-loop.md
+
+egeo/                            # Standalone CLI package
+├── cli.py                       # `egeo` entrypoint
+├── loop.py                      # `egeo loop run|collect|doctor`
+├── workspace.py                 # $EGEO_HOME resolution + bootstrap
+└── substrate_lint.py            # SUBSTRATE.md enforcement
+
+collectors/                      # Deterministic, LLM-free senses
+├── README.md                    # The collector contract
+├── serp.py                      # Brave search snapshots
+├── page.py                      # Page snapshots
+└── fixtures/                    # Offline test data
+
+SUBSTRATE.md                     # Workspace/artifact contract
+```
+
+---
+
+## 🎁 Perfect For
+
+<table>
+<tr>
+<td align="center" width="20%">
+🚀<br /><strong>SaaS Founders</strong><br /><sub>AI-engine traffic</sub>
+</td>
+<td align="center" width="20%">
+💼<br /><strong>B2B Marketers</strong><br /><sub>Landing pages</sub>
+</td>
+<td align="center" width="20%">
+🛍️<br /><strong>E-commerce</strong><br /><sub>Product descriptions</sub>
+</td>
+<td align="center" width="20%">
+✍️<br /><strong>Content Creators</strong><br /><sub>AI discoverability</sub>
+</td>
+<td align="center" width="20%">
+🏢<br /><strong>Agencies</strong><br /><sub>GEO services</sub>
+</td>
+</tr>
+</table>
+
+---
+
+## 📚 Documentation
+
+| Resource | Description |
+|:---------|:------------|
+| 📖 **[Getting Started](docs/getting-started.md)** | Step-by-step tutorial |
+| ⚙️ **[How It Works](docs/how-it-works.md)** | Technical deep dive |
+| ❓ **[FAQ](docs/faq.md)** | Common questions answered |
+| 🧩 **[skills.sh Playbook](docs/skills-sh-playbook.md)** | Listing, ranking, and metadata checklist |
+| 🧪 **[Evaluation Harness](docs/evaluation.md)** | Dataset format, commands, metrics, and honest limitations |
+| 📝 **[Usage Guide](USAGE.md)** | Complete command reference |
+| 📝 **[Research Paper](https://arxiv.org/abs/2511.20867)** | The science behind E-GEO |
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+**Quick ways to contribute:**
+- Report bugs via [issues](https://github.com/mverab/eGEOagents/issues)
+- Submit pull requests for features
+- Improve documentation
+- Share your GEO results
+
+---
+
+## 🔍 SEO & AI Search Glossary
+
+E-GEO covers the full spectrum of AI search optimization. If you're searching for any of these, you're in the right place:
+
+| Term | What it means |
+|------|---------------|
+| **GEO** (Generative Engine Optimization) | Optimizing content for AI answer engines like ChatGPT, Perplexity, Gemini |
+| **AEO** (Answer Engine Optimization) | Structuring content so AI engines can parse and cite it |
+| **AI SEO** | Adapting traditional SEO for AI-powered search |
+| **LLM SEO** | Optimization specifically for large language model responses |
+| **AI Visibility** | How often and how well your brand appears in AI-generated answers |
+| **Citation Tracking** | Monitoring whether AI engines cite your site as a source |
+| **llms.txt** | A standard file (like robots.txt) that tells AI crawlers what content to prioritize |
+
+---
+
+## 📜 License
+
+MIT License - use it, modify it, sell with it. See [LICENSE](LICENSE) for details.
+
+---
+
+## 🙋 Support & Community
+
+- **Issues:** [GitHub Issues](https://github.com/mverab/eGEOagents/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/mverab/eGEOagents/discussions)
+- **Research:** [E-GEO Paper (arXiv:2511.20867)](https://arxiv.org/abs/2511.20867)
+
+---
+
+## 🚀 Ready to Rank Higher?
+
+<div align="center">
+
+```bash
+# Install
+cp -r eGEOagents/.claude .
+
+# Activate (in Claude Code)
+/output-style geo-optimizer
+
+# Optimize your first page
+/geo https://yoursite.com
+```
+
+<br />
+
+<a href="https://github.com/mverab/eGEOagents">
+  <img src="https://img.shields.io/badge/⭐-Star%20on%20GitHub-yellow?style=for-the-badge&logo=github" alt="Star on GitHub" />
+</a>
+
+<br /><br />
+
+---
+
+**Built for the AI-first web — optimize your content for ChatGPT, Perplexity, Claude, and Gemini with E-GEO, the open-source GEO tool.** 🌐
+
+<sub>Made with ❤️ by <a href="https://verabadias.gumroad.com/">Vera Badias</a> • Based on research from <a href="https://arxiv.org/abs/2511.20867">arXiv:2511.20867</a></sub>
+
+<sub>🤖 This project is AI-assisted. See <a href="CONTRIBUTING.md#ai-transparency">AI Transparency</a> for details.</sub>
+
+</div>