Release SEO Dungeon v2.2.5 env-first integrations

Author: avalonreset

CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.5] - 2026-06-13
+
+### Added
+- **Project `.env` integration path**: the dungeon bridge now forwards known
+  SEO-related keys from the selected project `.env` and `.env.local` into the
+  selected local CLI, including DataForSEO, Firecrawl, Google, GA4, GSC, and
+  Railway variables.
+- **Direct API helpers**: added lightweight DataForSEO and Firecrawl scripts so
+  live SEO data and crawl workflows can run from project credentials without
+  requiring MCP setup.
+
+### Changed
+- **Env-first audit policy**: audit and chat prompts now instruct Codex, Claude,
+  and Gemini to prefer direct API/script access from project credentials, using
+  MCP servers only as quiet optional adapters when already available.
+- **Integration docs**: DataForSEO, Firecrawl, Google, and extension docs now
+  frame MCP as optional instead of required for normal SEO Dungeon audits.
+
 ## [2.2.4] - 2026-06-13
 
 ### Changed

README.md

@@ -6,7 +6,7 @@
 
 [![CI](https://github.com/avalonreset/seo-dungeon/actions/workflows/ci.yml/badge.svg)](https://github.com/avalonreset/seo-dungeon/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![Version](https://img.shields.io/badge/version-2.2.4-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.2.5-blue)](CHANGELOG.md)
 [![Runtime](https://img.shields.io/badge/runtime-Codex%20%7C%20Claude%20%7C%20Gemini-2ea44f)](dungeon/)
 
 SEO Dungeon turns SEO audits into a 16-bit dungeon crawler. Enter a domain,
@@ -136,6 +136,28 @@ Runtime environment:
 Set a model variable to `default`, `auto`, or `none` to let that CLI use its own
 configured default model.
 
+### Project API Credentials
+
+SEO Dungeon treats the selected project folder as the credential source for
+audit integrations. Add a `.env` or `.env.local` file at that project root when
+you want live data:
+
+```bash
+DATAFORSEO_USERNAME=your-login
+DATAFORSEO_PASSWORD=your-password
+FIRECRAWL_API_KEY=fc-your-api-key
+GOOGLE_API_KEY=your-google-api-key
+GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account.json
+GSC_SITE_URL=https://example.com/
+GA4_PROPERTY_ID=123456789
+```
+
+The bridge forwards known SEO-related keys from the project `.env` into the
+selected local CLI. DataForSEO, Firecrawl, and Google workflows should use those
+credentials directly first. MCP servers are optional adapters: if you already
+have one configured, an agent may use it quietly, but SEO Dungeon does not
+require MCP setup for audits.
+
 First audits can take 5-10 minutes because `/seo audit` fans out many tool
 calls. Cached audits are much faster.
 

agents-codex/seo-backlinks.toml

@@ -38,7 +38,7 @@ You are a backlink profile analyst. When delegated tasks during an SEO audit:
 - Bing's unique competitor comparison is especially valuable for gap analysis
 
 ### Tier 3 (+ DataForSEO — Premium)
-- If DataForSEO MCP tools are available, use them for highest-fidelity data
+- If DataForSEO credentials or optional tools are available, use direct DataForSEO data for highest-fidelity analysis
 - DataForSEO data gets **confidence: 1.00**
 - Combine with free source data for cross-validation
 - When DataForSEO and Moz disagree, trust DataForSEO but note the discrepancy

agents-codex/seo-dataforseo.toml

@@ -1,13 +1,14 @@
 name = "seo-dataforseo"
-description = "DataForSEO data analyst. Fetches live SERP data, keyword metrics, backlink profiles, on-page analysis, content analysis, business listings, and AI visibility checks via DataForSEO MCP tools."
+description = "DataForSEO data analyst. Fetches live SERP data, keyword metrics, backlink profiles, on-page analysis, content analysis, business listings, and AI visibility checks via project .env credentials and direct API scripts, with optional adapters when already available."
 nickname_candidates = ["seo-dataforseo", "seo dataforseo", "dataforseo"]
 developer_instructions = """
 You are a DataForSEO data analyst. When delegated tasks during an SEO audit or analysis:
 
-1. Check that DataForSEO MCP tools are available before attempting calls
-2. Use the most efficient tool combination for the requested data
-3. Apply default parameters: location_code=2840 (US), language_code=en unless specified
-4. Format output to match codex-seo conventions (tables, priority levels, scores)
+1. Prefer direct DataForSEO API access via `DATAFORSEO_USERNAME` or `DATAFORSEO_LOGIN` plus `DATAFORSEO_PASSWORD` from the selected project's `.env`.
+2. Use `python scripts/dataforseo_api.py ...` for generic DataForSEO endpoints and specialized scripts such as `scripts/dataforseo_merchant.py` when they fit.
+3. If an optional DataForSEO adapter is already available, you may use it quietly, but do not require MCP setup or spend context inventorying MCP servers unless the user explicitly asks.
+4. Apply default parameters: location_code=2840 (US), language_code=en unless specified.
+5. Format output to match codex-seo conventions (tables, priority levels, scores).
 
 ## Efficient Tool Usage
 
@@ -18,8 +19,8 @@ You are a DataForSEO data analyst. When delegated tasks during an SEO audit or a
 
 ## Error Handling
 
-- If a DataForSEO tool returns an error, report the error clearly to the user
-- If credentials are invalid, suggest running the extension installer again
+- If a DataForSEO API call or optional tool returns an error, report the error clearly to the user
+- If credentials are missing or invalid, ask the user to set `DATAFORSEO_USERNAME` or `DATAFORSEO_LOGIN` and `DATAFORSEO_PASSWORD` in the selected project `.env`
 - If a module is not enabled, note which module is needed
 
 ## Output Format

agents-codex/seo-firecrawl.toml

@@ -1,13 +1,13 @@
 name = "seo-firecrawl"
-description = "Firecrawl-backed site crawling specialist for URL discovery, site mapping, and crawl coverage analysis when the Firecrawl MCP server is available."
+description = "Firecrawl-backed site crawling specialist for URL discovery, site mapping, and crawl coverage analysis via FIRECRAWL_API_KEY and direct API scripts, with optional adapters when already available."
 nickname_candidates = ["seo-firecrawl", "seo firecrawl", "firecrawl"]
 developer_instructions = """
-You are a Firecrawl-backed SEO crawl specialist. Use Firecrawl MCP tools only when they are available and the user has requested or approved crawl-based discovery.
+You are a Firecrawl-backed SEO crawl specialist. Prefer direct Firecrawl API access via `FIRECRAWL_API_KEY` in the selected project's `.env` and `python scripts/firecrawl_api.py ...`. Use an optional Firecrawl adapter only when it is already available and the user has requested or approved crawl-based discovery.
 
 When delegated during a full audit:
-1. Confirm Firecrawl MCP availability before using it.
+1. Check for `FIRECRAWL_API_KEY` before using Firecrawl. Do not require MCP setup.
 2. Map the target site to discover canonical URLs, important sections, and crawl gaps.
 3. Respect user crawl budgets, robots constraints, and same-domain boundaries.
 4. Return a concise URL inventory, sitemap comparison notes, crawl errors, and suggested follow-up specialist skills.
-5. If Firecrawl is unavailable, report that state clearly and recommend the deterministic sitemap/page workflows instead.
+5. If Firecrawl credentials and optional MCP tools are unavailable, continue with deterministic sitemap/page workflows instead of blocking.
 """

agents-codex/seo-geo.toml

@@ -47,7 +47,7 @@ Only 11% of domains are cited by both ChatGPT and Google AI Overviews, so platfo
 
 ## DataForSEO Integration (Optional)
 
-If DataForSEO MCP tools are available, use `ai_optimization_chat_gpt_scraper` for live ChatGPT visibility and `ai_opt_llm_ment_search` for LLM mention tracking.
+If DataForSEO credentials or optional tools are available, use direct DataForSEO calls for live ChatGPT visibility and LLM mention tracking.
 
 ## Output Format
 

agents-codex/seo-local.toml

@@ -56,7 +56,7 @@ Load `skills/seo/references/local-schema-types.md` for:
 
 ## DataForSEO Integration (Optional)
 
-If DataForSEO MCP tools are available, use `local_business_data` for live GBP data and `google_local_pack_serp` for real-time local pack positions.
+If DataForSEO credentials or optional tools are available, use direct DataForSEO calls for live GBP data and real-time local pack positions.
 
 ## Output Format
 

agents-codex/seo-maps.toml

@@ -4,7 +4,7 @@ nickname_candidates = ["seo-maps", "seo maps", "maps"]
 developer_instructions = """
 You are a Maps Intelligence specialist. When delegated tasks during an SEO audit or given a business URL/name:
 
-1. Detect capability tier: check if DataForSEO MCP tools are available (try `business_data_business_listings_search`). If available = Tier 1. If not = Tier 0 (free APIs only).
+1. Detect capability tier: check if DataForSEO credentials are present in the selected project environment, or whether an optional DataForSEO adapter is already available. If available = Tier 1. If not = Tier 0 (free APIs only).
 2. Identify the target business: extract name, location, and category from the URL or provided context
 3. Geocode the business address using Nominatim (free) or DataForSEO (Tier 1)
 4. Run available analyses based on tier (see below)

agents/seo-backlinks.md

@@ -42,7 +42,7 @@ You are a backlink profile analyst. When delegated tasks during an SEO audit:
 - Bing's unique competitor comparison is especially valuable for gap analysis
 
 ### Tier 3 (+ DataForSEO — Premium)
-- If DataForSEO MCP tools are available, use them for highest-fidelity data
+- If DataForSEO credentials or optional tools are available, use direct DataForSEO data for highest-fidelity analysis
 - DataForSEO data gets **confidence: 1.00**
 - Combine with free source data for cross-validation
 - When DataForSEO and Moz disagree, trust DataForSEO but note the discrepancy

agents/seo-dataforseo.md

@@ -1,17 +1,18 @@
 ---
 name: seo-dataforseo
-description: DataForSEO data analyst. Fetches live SERP data, keyword metrics, backlink profiles, on-page analysis, content analysis, business listings, and AI visibility checks via DataForSEO MCP tools.
+description: DataForSEO data analyst. Fetches live SERP data, keyword metrics, backlink profiles, on-page analysis, content analysis, business listings, and AI visibility checks via project .env credentials and direct API scripts, with optional adapters when already available.
 model: sonnet
 maxTurns: 25
 tools: Read, Bash, Write, Glob, Grep
 ---
 
 You are a DataForSEO data analyst. When delegated tasks during an SEO audit or analysis:
 
-1. Check that DataForSEO MCP tools are available before attempting calls
-2. Use the most efficient tool combination for the requested data
-3. Apply default parameters: location_code=2840 (US), language_code=en unless specified
-4. Format output to match claude-seo conventions (tables, priority levels, scores)
+1. Prefer direct DataForSEO API access via `DATAFORSEO_USERNAME` or `DATAFORSEO_LOGIN` plus `DATAFORSEO_PASSWORD` from the selected project's `.env`.
+2. Use `python scripts/dataforseo_api.py ...` for generic DataForSEO endpoints and specialized scripts such as `scripts/dataforseo_merchant.py` when they fit.
+3. If an optional DataForSEO adapter is already available, you may use it quietly, but do not require MCP setup or spend context inventorying MCP servers unless the user explicitly asks.
+4. Apply default parameters: location_code=2840 (US), language_code=en unless specified.
+5. Format output to match claude-seo conventions (tables, priority levels, scores).
 
 ## Efficient Tool Usage
 
@@ -22,8 +23,8 @@ You are a DataForSEO data analyst. When delegated tasks during an SEO audit or a
 
 ## Error Handling
 
-- If a DataForSEO tool returns an error, report the error clearly to the user
-- If credentials are invalid, suggest running the extension installer again
+- If a DataForSEO API call or optional tool returns an error, report the error clearly to the user
+- If credentials are missing or invalid, ask the user to set `DATAFORSEO_USERNAME` or `DATAFORSEO_LOGIN` and `DATAFORSEO_PASSWORD` in the selected project `.env`
 - If a module is not enabled, note which module is needed
 
 ## Output Format