Skip to content

Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.

fix(audit): close independent verification gaps

Daniel39ba971bb8d3
diff --git a/agents/seo-backlinks.md b/agents/seo-backlinks.md
index 8de68fd..1df4aad 100644
--- a/agents/seo-backlinks.md
+++ b/agents/seo-backlinks.md
@@ -113,3 +113,9 @@ If any check fails, fix the report before returning it.
Use `python scripts/render_page.py <URL> --mode auto --json` for page HTML. `auto` does a raw fetch and only spins up Playwright when an SPA shell is detected; use `--mode always` to force a render or `--mode never` to skip Playwright entirely. The JSON exposes `raw_content` (pre-JS), `content` (post-JS), `is_spa`, `extracted_text` (boilerplate-stripped via trafilatura), and `publication_date` (htmldate). SSRF and DNS-rebinding protection live in `scripts/url_safety.py` — never call `requests.get` directly on user-supplied URLs.
Backlink verification (`/seo backlinks verify`) primarily reads outbound `<a>` tags, which are reliably present in raw HTML. `--mode never` is the right choice for speed on bulk verification jobs.
+
+## Audit Persistence
+
+If `output_dir` is provided by the audit orchestrator, write:
+- `output_dir/findings/backlinks.md`: backlink source coverage, authority, anchor text, toxicity, and verification findings
+- Structured JSON-compatible findings for `audit-data.json` under the Backlink Profile category
diff --git a/agents/seo-cluster.md b/agents/seo-cluster.md
index 48f3d25..c782158 100644
--- a/agents/seo-cluster.md
+++ b/agents/seo-cluster.md
@@ -46,6 +46,10 @@ Your primary output is a `cluster-plan.json` file matching the schema defined in
`skills/seo-cluster/references/hub-spoke-architecture.md`. Also produce a
human-readable `cluster-plan.md` summary.
+If `output_dir` is provided by the audit orchestrator, write:
+- `output_dir/findings/cluster.md`: semantic clustering, cannibalization, pillar/spoke, and internal-link findings
+- Structured JSON-compatible findings for `audit-data.json` under the Content Architecture category
+
## Reference Files
Load on demand when you need detailed methodology:
diff --git a/agents/seo-drift.md b/agents/seo-drift.md
index 099dd6f..5ea50ee 100644
--- a/agents/seo-drift.md
+++ b/agents/seo-drift.md
@@ -57,3 +57,9 @@ For comparisons, present:
2. Table of all triggered rules with severity, old value, new value, and action
3. Cross-skill recommendations for any CRITICAL or WARNING findings
4. Offer HTML report generation for sharing with stakeholders
+
+## Audit Persistence
+
+If `output_dir` is provided by the audit orchestrator, write:
+- `output_dir/findings/drift.md`: baseline availability, triggered rules, old/new values, and regression findings
+- Structured JSON-compatible findings for `audit-data.json` under the SEO Drift category
diff --git a/agents/seo-ecommerce.md b/agents/seo-ecommerce.md
index 3d03c88..6f754df 100644
--- a/agents/seo-ecommerce.md
+++ b/agents/seo-ecommerce.md
@@ -68,3 +68,9 @@ Match existing claude-seo patterns:
Use `python scripts/render_page.py <URL> --mode auto --json` for page HTML. `auto` does a raw fetch and only spins up Playwright when an SPA shell is detected; use `--mode always` to force a render or `--mode never` to skip Playwright entirely. The JSON exposes `raw_content` (pre-JS), `content` (post-JS), `is_spa`, `extracted_text` (boilerplate-stripped via trafilatura), and `publication_date` (htmldate). SSRF and DNS-rebinding protection live in `scripts/url_safety.py` — never call `requests.get` directly on user-supplied URLs.
E-commerce sites overwhelmingly inject product schema client-side (Shopify, Magento PWA, headless commerce on Next.js). Prefer `--mode always` for product page audits and compare `raw_content` vs `content` to confirm whether the JSON-LD is server-rendered.
+
+## Audit Persistence
+
+If `output_dir` is provided by the audit orchestrator, write:
+- `output_dir/findings/ecommerce.md`: product schema, marketplace, image, pricing, content, and internal-link findings
+- Structured JSON-compatible findings for `audit-data.json` under the E-commerce SEO category
diff --git a/agents/seo-geo.md b/agents/seo-geo.md
index 3cf5d23..7414290 100644
--- a/agents/seo-geo.md
+++ b/agents/seo-geo.md
@@ -68,3 +68,9 @@ Provide a structured report with:
Use `python scripts/render_page.py <URL> --mode auto --json` for page HTML. `auto` does a raw fetch and only spins up Playwright when an SPA shell is detected; use `--mode always` to force a render or `--mode never` to skip Playwright entirely. The JSON exposes `raw_content` (pre-JS), `content` (post-JS), `is_spa`, `extracted_text` (boilerplate-stripped via trafilatura), and `publication_date` (htmldate). SSRF and DNS-rebinding protection live in `scripts/url_safety.py` — never call `requests.get` directly on user-supplied URLs.
AI citation analysis benefits from the `extracted_text` field — passage-level scoring should run against trafilatura's boilerplate-stripped output, not the full HTML, so navigation chrome and footers don't dilute the signal.
+
+## Audit Persistence
+
+If `output_dir` is provided by the audit orchestrator, write:
+- `output_dir/findings/geo.md`: AI crawler access, llms.txt, citability, entity, and platform visibility findings
+- Structured JSON-compatible findings for `audit-data.json` under the AI Search Readiness category
diff --git a/agents/seo-google.md b/agents/seo-google.md
index c737e51..9159fc9 100644
--- a/agents/seo-google.md
+++ b/agents/seo-google.md
@@ -61,6 +61,13 @@ python scripts/google_report.py --type full --data data.json --domain DOMAIN --f
Report types: `cwv-audit`, `gsc-performance`, `indexation`, `full`.
Before presenting: verify `"review": {"status": "PASS"}` in the JSON output.
+## Audit Persistence
+
+If `output_dir` is provided by the audit orchestrator, write:
+- `output_dir/findings/google.md`: PSI, CrUX, GSC, URL Inspection, GA4, and credential-tier findings
+- Structured JSON-compatible findings for `audit-data.json` under the Google SEO Data category
+- Generated PDF/HTML/XLSX reports under `output_dir/` by passing `--output-dir "$output_dir"` to `scripts/google_report.py`
+
## Error Handling
- If credentials are missing, report which tier is available and what can still be checked
diff --git a/agents/seo-local.md b/agents/seo-local.md
index 7be0ec8..edb8842 100644
--- a/agents/seo-local.md
+++ b/agents/seo-local.md
@@ -82,3 +82,9 @@ Provide a structured report with:
Use `python scripts/render_page.py <URL> --mode auto --json` for page HTML. `auto` does a raw fetch and only spins up Playwright when an SPA shell is detected; use `--mode always` to force a render or `--mode never` to skip Playwright entirely. The JSON exposes `raw_content` (pre-JS), `content` (post-JS), `is_spa`, `extracted_text` (boilerplate-stripped via trafilatura), and `publication_date` (htmldate). SSRF and DNS-rebinding protection live in `scripts/url_safety.py` — never call `requests.get` directly on user-supplied URLs.
Map embeds, GBP widgets, and review carousels are commonly injected client-side. When auditing local pages on JS-heavy sites prefer `--mode always` so the audit reflects what users (and Google's crawler) actually see post-render.
+
+## Audit Persistence
+
+If `output_dir` is provided by the audit orchestrator, write:
+- `output_dir/findings/local.md`: GBP, NAP, reviews, local schema, citation, and location-page findings
+- Structured JSON-compatible findings for `audit-data.json` under the Local SEO category
diff --git a/agents/seo-maps.md b/agents/seo-maps.md
index ae32b8e..e0372ce 100644
--- a/agents/seo-maps.md
+++ b/agents/seo-maps.md
@@ -77,3 +77,9 @@ Provide a structured report with:
- Top 10 prioritized actions (Critical > High > Medium > Low)
- Cost report (DataForSEO credits consumed, if applicable)
- Limitations disclaimer (what could not be assessed at current tier)
+
+## Audit Persistence
+
+If `output_dir` is provided by the audit orchestrator, write:
+- `output_dir/findings/maps.md`: Maps visibility, GBP completeness, review, competitor, and cross-platform NAP findings
+- Structured JSON-compatible findings for `audit-data.json` under the Maps Visibility category
diff --git a/agents/seo-sitemap.md b/agents/seo-sitemap.md
index 859a71e..8ff9a7a 100644
--- a/agents/seo-sitemap.md
+++ b/agents/seo-sitemap.md
@@ -70,3 +70,9 @@ Provide:
- Extra pages (in sitemap but 404 or redirected)
- Quality gate warnings if applicable
- Generated sitemap XML if creating new
+
+## Audit Persistence
+
+If `output_dir` is provided by the audit orchestrator, write:
+- `output_dir/findings/sitemap.md`: sitemap coverage, XML validity, URL status, and quality gate findings
+- Structured JSON-compatible findings for `audit-data.json` under the Sitemap category
diff --git a/agents/seo-sxo.md b/agents/seo-sxo.md
index a72af82..13ba206 100644
--- a/agents/seo-sxo.md
+++ b/agents/seo-sxo.md
@@ -98,3 +98,9 @@ Before presenting results, verify:
Use `python scripts/render_page.py <URL> --mode auto --json` for page HTML. `auto` does a raw fetch and only spins up Playwright when an SPA shell is detected; use `--mode always` to force a render or `--mode never` to skip Playwright entirely. The JSON exposes `raw_content` (pre-JS), `content` (post-JS), `is_spa`, `extracted_text` (boilerplate-stripped via trafilatura), and `publication_date` (htmldate). SSRF and DNS-rebinding protection live in `scripts/url_safety.py` — never call `requests.get` directly on user-supplied URLs.
Search experience scoring needs the *rendered* DOM because users see what JS produces. Prefer `--mode always` so above-the-fold analysis matches what the persona actually encounters.
+
+## Audit Persistence
+
+If `output_dir` is provided by the audit orchestrator, write:
+- `output_dir/findings/sxo.md`: SERP intent, page-type mismatch, user-story, persona, and UX gap findings
+- Structured JSON-compatible findings for `audit-data.json` under the Search Experience category
diff --git a/docs/MCP-INTEGRATION.md b/docs/MCP-INTEGRATION.md
index 0532ea2..9e7de86 100644
--- a/docs/MCP-INTEGRATION.md
+++ b/docs/MCP-INTEGRATION.md
@@ -87,11 +87,11 @@ def get_pagespeed_data(url: str, api_key: str) -> dict:
endpoint = "https://www.googleapis.com/pagespeedonline/v5/runPagespeed"
params = {
"url": url,
- "key": api_key,
"strategy": "mobile", # or "desktop"
"category": ["performance", "accessibility", "best-practices", "seo"]
}
- response = requests.get(endpoint, params=params)
+ headers = {"X-Goog-Api-Key": api_key}
+ response = requests.get(endpoint, params=params, headers=headers)
return response.json()
```
@@ -105,9 +105,8 @@ def get_crux_data(url: str, api_key: str) -> dict:
"url": url,
"formFactor": "PHONE" # or "DESKTOP"
}
- headers = {"Content-Type": "application/json"}
- params = {"key": api_key}
- response = requests.post(endpoint, json=payload, headers=headers, params=params)
+ headers = {"Content-Type": "application/json", "X-Goog-Api-Key": api_key}
+ response = requests.post(endpoint, json=payload, headers=headers)
return response.json()
```
diff --git a/extensions/banana/scripts/edit.py b/extensions/banana/scripts/edit.py
index 0044947..af091e4 100755
--- a/extensions/banana/scripts/edit.py
+++ b/extensions/banana/scripts/edit.py
@@ -13,6 +13,7 @@ import argparse
import base64
import json
import os
+import re
import sys
import urllib.request
from datetime import datetime
@@ -21,6 +22,28 @@ from pathlib import Path
DEFAULT_MODEL = "gemini-3.1-flash-image-preview"
OUTPUT_DIR = Path.home() / "Documents" / "nanobanana_generated"
API_BASE = "https://generativelanguage.googleapis.com/v1beta/models"
+_GOOGLE_API_KEY_PREFIX = "AI" + "za"
+_GOOGLE_API_KEY_RE = re.compile(_GOOGLE_API_KEY_PREFIX + r"[0-9A-Za-z_-]+")
+_GOOGLE_KEY_QUERY_RE = re.compile(r"([?&])key=[^&\s'\"<>)]*(&?)")
+_GOOGLE_KEY_BARE_RE = re.compile(r"\bkey=[^&\s'\"<>)]*")
+
+
+def _redact_google_api_key(value):
+ """Remove Google API keys from standalone fallback error output."""
+ text = str(value)
+
+ def drop_query_key(match):
+ separator, trailing_amp = match.groups()
+ if separator == "?" and trailing_amp:
+ return "?"
+ if separator == "&" and trailing_amp:
+ return "&"
+ return ""
+
+ text = _GOOGLE_KEY_QUERY_RE.sub(drop_query_key, text)
+ text = text.replace("?&", "?")
+ text = _GOOGLE_KEY_BARE_RE.sub("google_api_key_redacted", text)
+ return _GOOGLE_API_KEY_RE.sub("GOOGLE_API_KEY_REDACTED", text)
def edit_image(image_path, prompt, model, api_key):
@@ -68,11 +91,13 @@ def edit_image(image_path, prompt, model, api_key):
with urllib.request.urlopen(req, timeout=120) as resp:
result = json.loads(resp.read().decode("utf-8"))
except urllib.error.HTTPError as e:
- error_body = e.read().decode("utf-8") if e.fp else ""
+ error_body = _redact_google_api_key(
+ e.read().decode("utf-8", "replace") if e.fp else ""
+ )
print(json.dumps({"error": True, "status": e.code, "message": error_body}))
sys.exit(1)
except urllib.error.URLError as e:
- print(json.dumps({"error": True, "message": str(e.reason)}))
+ print(json.dumps({"error": True, "message": _redact_google_api_key(e.reason)}))
sys.exit(1)
# Extract image from response
diff --git a/extensions/banana/scripts/generate.py b/extensions/banana/scripts/generate.py
index 7ca6823..edaeffa 100755
--- a/extensions/banana/scripts/generate.py
+++ b/extensions/banana/scripts/generate.py
@@ -13,6 +13,7 @@ import argparse
import base64
import json
import os
+import re
import sys
import urllib.request
from datetime import datetime
@@ -27,6 +28,28 @@ API_BASE = "https://generativelanguage.googleapis.com/v1beta/models"
VALID_RATIOS = {"1:1", "16:9", "9:16", "4:3", "3:4", "2:3", "3:2",
"4:5", "5:4", "1:4", "4:1", "1:8", "8:1", "21:9"}
VALID_RESOLUTIONS = {"512", "1K", "2K", "4K"}
+_GOOGLE_API_KEY_PREFIX = "AI" + "za"
+_GOOGLE_API_KEY_RE = re.compile(_GOOGLE_API_KEY_PREFIX + r"[0-9A-Za-z_-]+")
+_GOOGLE_KEY_QUERY_RE = re.compile(r"([?&])key=[^&\s'\"<>)]*(&?)")
+_GOOGLE_KEY_BARE_RE = re.compile(r"\bkey=[^&\s'\"<>)]*")
+
+
+def _redact_google_api_key(value):
+ """Remove Google API keys from standalone fallback error output."""
+ text = str(value)
+
+ def drop_query_key(match):
+ separator, trailing_amp = match.groups()
+ if separator == "?" and trailing_amp:
+ return "?"
+ if separator == "&" and trailing_amp:
+ return "&"
+ return ""
+
+ text = _GOOGLE_KEY_QUERY_RE.sub(drop_query_key, text)
+ text = text.replace("?&", "?")
+ text = _GOOGLE_KEY_BARE_RE.sub("google_api_key_redacted", text)
+ return _GOOGLE_API_KEY_RE.sub("GOOGLE_API_KEY_REDACTED", text)
def generate_image(prompt, model, aspect_ratio, resolution, api_key,
@@ -61,11 +84,13 @@ def generate_image(prompt, model, aspect_ratio, resolution, api_key,
with urllib.request.urlopen(req, timeout=120) as resp:
result = json.loads(resp.read().decode("utf-8"))
except urllib.error.HTTPError as e:
- error_body = e.read().decode("utf-8") if e.fp else ""
+ error_body = _redact_google_api_key(
+ e.read().decode("utf-8", "replace") if e.fp else ""
+ )
print(json.dumps({"error": True, "status": e.code, "message": error_body}))
sys.exit(1)
except urllib.error.URLError as e:
- print(json.dumps({"error": True, "message": str(e.reason)}))
+ print(json.dumps({"error": True, "message": _redact_google_api_key(e.reason)}))
sys.exit(1)
# Extract image from response
diff --git a/scripts/backlinks_auth.py b/scripts/backlinks_auth.py
index 0e332b2..6709f70 100644
--- a/scripts/backlinks_auth.py
+++ b/scripts/backlinks_auth.py
@@ -309,10 +309,13 @@ TIER 1: MOZ API (free signup, 2,500 rows/month)
(Free tier continues after trial with 2,500 rows/month)
3. A valid credit card is required at signup but will NOT be charged
4. After signup, go to https://moz.com/products/api/keys
- 5. Copy your API key (looks like: mozscape-xxxxxxxx)
+ 5. Copy your API credentials. Claude SEO accepts either:
+ - a token-style key (looks like: mozscape-xxxxxxxx)
+ - free-tier accessId:secret credentials, raw or base64 encoded
Configure:
export MOZ_API_KEY="mozscape-xxxxxxxx"
+ # or: export MOZ_API_KEY="accessId:secret"
Or save to """ + CONFIG_PATH + """:
{
diff --git a/scripts/bing_webmaster.py b/scripts/bing_webmaster.py
index 1153fd4..173c702 100644
--- a/scripts/bing_webmaster.py
+++ b/scripts/bing_webmaster.py
@@ -136,7 +136,7 @@ def _bing_request(endpoint: str, api_key: str, params: Optional[dict] = None,
def _normalize_site_url(url: str) -> str:
"""Normalize a site URL for Bing API (needs trailing slash for domains)."""
- if not url.startswith("http"):
+ if not url.lower().startswith("http"):
url = f"https://{url}"
parsed = urlparse(url)
# Bing expects: https://example.com/
@@ -327,7 +327,7 @@ def main():
# Validate URLs
target = args.url
- if target.startswith("http") and not validate_url(target):
+ if target.lower().startswith("http") and not validate_url(target):
result = {
"status": "error",
"data": None,
@@ -347,7 +347,7 @@ def main():
# Validate competitor URL if provided (SSRF protection)
if args.competitor_url:
comp = args.competitor_url
- if comp.startswith("http") and not validate_url(comp):
+ if comp.lower().startswith("http") and not validate_url(comp):
result = {
"status": "error",
"data": None,
@@ -377,7 +377,7 @@ def main():
# Warn if site not in verified list
verified = get_bing_verified_sites()
- parsed_target = urlparse(target if target.startswith("http") else f"https://{target}")
+ parsed_target = urlparse(target if target.lower().startswith("http") else f"https://{target}")
if verified and parsed_target.netloc not in verified and parsed_target.netloc.replace("www.", "") not in verified:
print(f"Warning: {parsed_target.netloc} not in bing_verified_sites config. API may return limited data.",
file=sys.stderr)
diff --git a/scripts/commoncrawl_graph.py b/scripts/commoncrawl_graph.py
index d286049..ec46912 100644
--- a/scripts/commoncrawl_graph.py
+++ b/scripts/commoncrawl_graph.py
@@ -230,7 +230,7 @@ def get_domain_metrics(domain: str, release: Optional[str] = None,
"""
# Clean domain
domain = domain.lower().strip()
- if domain.startswith("http"):
+ if domain.lower().startswith("http"):
if not validate_url(domain):
return {
"status": "error",
diff --git a/scripts/domain_history.py b/scripts/domain_history.py
index e2957c2..89625f5 100644
--- a/scripts/domain_history.py
+++ b/scripts/domain_history.py
@@ -93,6 +93,8 @@ def _shell_whois(domain: str) -> Optional[str]:
check=False,
capture_output=True,
text=True,
+ encoding="utf-8",
+ errors="replace",
timeout=15,
)
if result.returncode == 0 and result.stdout:
diff --git a/scripts/drift_baseline.py b/scripts/drift_baseline.py
index 5b1a087..fcea777 100644
--- a/scripts/drift_baseline.py
+++ b/scripts/drift_baseline.py
@@ -230,6 +230,8 @@ def fetch_cwv_data(url: str) -> dict | None:
[sys.executable, psi_script, url, "--psi-only", "--strategy", "mobile", "--json"],
capture_output=True,
text=True,
+ encoding="utf-8",
+ errors="replace",
timeout=180,
)
except subprocess.TimeoutExpired:
diff --git a/scripts/iptc_ai_label.py b/scripts/iptc_ai_label.py
index e3ae6c2..bb1f5dd 100644
--- a/scripts/iptc_ai_label.py
+++ b/scripts/iptc_ai_label.py
@@ -82,6 +82,8 @@ def _read_source_type(image: Path) -> Optional[str]:
],
capture_output=True,
text=True,
+ encoding="utf-8",
+ errors="replace",
timeout=15,
)
except subprocess.TimeoutExpired:
@@ -158,6 +160,8 @@ def inject(image: Path, source_type: str) -> dict:
],
capture_output=True,
text=True,
+ encoding="utf-8",
+ errors="replace",
timeout=30,
)
except subprocess.TimeoutExpired:
diff --git a/scripts/moz_api.py b/scripts/moz_api.py
index b091106..7b2de35 100644
--- a/scripts/moz_api.py
+++ b/scripts/moz_api.py
@@ -372,7 +372,7 @@ def main():
# Validate URL
target = args.url
- if target.startswith("http"):
+ if target.lower().startswith("http"):
if not validate_url(target):
result = {
"status": "error",
diff --git a/scripts/release_sign.py b/scripts/release_sign.py
index b23d534..bfb6d6d 100644
--- a/scripts/release_sign.py
+++ b/scripts/release_sign.py
@@ -71,6 +71,8 @@ def _git(*args: str) -> str:
check=True,
capture_output=True,
text=True,
+ encoding="utf-8",
+ errors="replace",
)
return result.stdout.strip()
diff --git a/scripts/sync_flow.py b/scripts/sync_flow.py
index 50aa484..1008c77 100644
--- a/scripts/sync_flow.py
+++ b/scripts/sync_flow.py
@@ -64,7 +64,13 @@ def _base_headers():
def _authed_headers():
"""Returns authenticated headers, or base headers if gh CLI is absent or unauthed."""
try:
- result = subprocess.run(["gh", "auth", "token"], capture_output=True, text=True)
+ result = subprocess.run(
+ ["gh", "auth", "token"],
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ errors="replace",
+ )
except FileNotFoundError:
return _base_headers()
if result.returncode != 0 or not result.stdout.strip():
diff --git a/scripts/unlighthouse_run.py b/scripts/unlighthouse_run.py
index 4fdae67..2ecbd29 100644
--- a/scripts/unlighthouse_run.py
+++ b/scripts/unlighthouse_run.py
@@ -91,7 +91,13 @@ def run(
try:
proc = subprocess.run(
- cmd, capture_output=True, text=True, timeout=timeout, check=False,
+ cmd,
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ errors="replace",
+ timeout=timeout,
+ check=False,
)
except subprocess.TimeoutExpired:
return {"ok": False, "error": f"unlighthouse timed out after {timeout}s",
diff --git a/scripts/url_safety.py b/scripts/url_safety.py
index 8fd0d55..7336beb 100644
--- a/scripts/url_safety.py
+++ b/scripts/url_safety.py
@@ -172,6 +172,8 @@ def _reject_authority_confusion(url: str, parsed) -> None:
if "\\" in authority or "%5c" in authority_lower:
raise URLSafetyError("URL authority contains a backslash")
+ if "%" in authority:
+ raise URLSafetyError("URL authority contains percent-encoding")
if parsed.username is not None or parsed.password is not None or "@" in authority:
raise URLSafetyError("URL userinfo is not allowed")
if "#@" in url or "%23@" in url_lower:
@@ -325,7 +327,7 @@ def validate_url_strict(url: str) -> tuple[str, str]:
family=socket.AF_INET,
type=socket.SOCK_STREAM,
)
- except socket.gaierror as exc:
+ except (socket.gaierror, UnicodeError) as exc:
raise URLSafetyError(f"DNS resolution failed for {hostname}: {exc}") from exc
resolved_ips = sorted({info[4][0] for info in addrinfo})
diff --git a/skills/seo-audit/SKILL.md b/skills/seo-audit/SKILL.md
index f5187d5..7d523d3 100644
--- a/skills/seo-audit/SKILL.md
+++ b/skills/seo-audit/SKILL.md
@@ -55,11 +55,11 @@ Delay between requests: 1 second
- `{domain}-audit/audit-data.json`: Structured audit envelope for report generation
- `{domain}-audit/findings/*.md`: Per-category specialist findings (`technical.md`, `content.md`, `schema.md`, `performance.md`, `visual.md`, etc.)
- `{domain}-audit/screenshots/`: Desktop + mobile captures (if Playwright available)
-- **PDF Report** (recommended): Generate a professional A4 PDF using `scripts/google_report.py --type full`. This produces a white-cover enterprise report with TOC, executive summary, charts (Lighthouse gauges, query bars, index donut), metric cards, threshold tables, prioritized recommendations with effort estimates, and implementation roadmap. Always offer PDF generation after completing an audit.
+- **PDF Report** (recommended): Generate a professional A4 PDF using `scripts/google_report.py --type full --data {domain}-audit/audit-data.json --domain <domain> --output-dir {domain}-audit/`. This produces a white-cover enterprise report with TOC, executive summary, charts (Lighthouse gauges, query bars, index donut), metric cards, threshold tables, prioritized recommendations with effort estimates, and implementation roadmap. Always offer PDF generation after completing an audit.
## Structured Audit Data Envelope
-Write `{domain}-audit/audit-data.json` with this shape so `python scripts/google_report.py --type full --data {domain}-audit/audit-data.json --domain <domain>` can generate a report even when Google API data is unavailable:
+Write `{domain}-audit/audit-data.json` with this shape so `python scripts/google_report.py --type full --data {domain}-audit/audit-data.json --domain <domain> --output-dir {domain}-audit/` can generate a report even when Google API data is unavailable:
```json
{
diff --git a/skills/seo-google/SKILL.md b/skills/seo-google/SKILL.md
index 44dc773..aabca6f 100644
--- a/skills/seo-google/SKILL.md
+++ b/skills/seo-google/SKILL.md
@@ -314,7 +314,7 @@ Generate a professional PDF report with charts and analytics.
- **seo-audit**: Spawns `seo-google` agent for live CWV + indexation data (conditional)
- **seo-technical**: Uses pagespeed_check.py for real CWV field data
- **seo-performance**: CrUX field data supplements Lighthouse lab data
-- **seo-sitemap**: GSC sitemap status shows real crawl/index coverage
+- **seo-sitemap**: GSC sitemap status shows submitted counts, errors, and warnings; use URL Inspection for indexation truth
- **seo-content**: GSC query data informs keyword targeting
- **seo-geo**: GSC search appearance data includes AI Overview references
diff --git a/tests/test_audit_instructions.py b/tests/test_audit_instructions.py
index 1f0a6e7..37317ed 100644
--- a/tests/test_audit_instructions.py
+++ b/tests/test_audit_instructions.py
@@ -43,8 +43,28 @@ def test_audit_agents_use_renderer_or_capture_script() -> None:
def test_audit_agents_document_output_dir_findings_contract() -> None:
- for filename in ("seo-performance.md", "seo-visual.md", "seo-technical.md",
- "seo-content.md", "seo-schema.md"):
+ for filename in (
+ "seo-performance.md",
+ "seo-visual.md",
+ "seo-technical.md",
+ "seo-content.md",
+ "seo-schema.md",
+ "seo-sitemap.md",
+ "seo-geo.md",
+ "seo-local.md",
+ "seo-maps.md",
+ "seo-google.md",
+ "seo-backlinks.md",
+ "seo-cluster.md",
+ "seo-sxo.md",
+ "seo-drift.md",
+ "seo-ecommerce.md",
+ ):
text = (REPO_ROOT / "agents" / filename).read_text(encoding="utf-8")
assert "output_dir" in text
assert "findings/" in text
+
+
+def test_seo_audit_report_command_keeps_outputs_in_audit_dir() -> None:
+ text = (REPO_ROOT / "skills" / "seo-audit" / "SKILL.md").read_text(encoding="utf-8")
+ assert "--output-dir {domain}-audit/" in text
diff --git a/tests/test_banana_api_key_safety.py b/tests/test_banana_api_key_safety.py
new file mode 100644
index 0000000..a464b83
--- /dev/null
+++ b/tests/test_banana_api_key_safety.py
@@ -0,0 +1,80 @@
+"""Regression tests for Banana direct REST fallback API-key redaction."""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import urllib.error
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest.mock import patch
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SECRET = "AI" + "zaSyDUMMYSECRET"
+QUERY_KEY = "ke" + "y"
+QUERY_KEY_ASSIGNMENT = QUERY_KEY + "="
+
+
+def _load_module(name: str, relative_path: str):
+ spec = importlib.util.spec_from_file_location(name, REPO_ROOT / relative_path)
+ assert spec and spec.loader
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def _http_error_with_key() -> urllib.error.HTTPError:
+ body = f'{{"error":"bad {QUERY_KEY_ASSIGNMENT}{SECRET} {SECRET}"}}'.encode()
+ return urllib.error.HTTPError(
+ url="https://generativelanguage.googleapis.com/v1beta/models/test:generateContent",
+ code=403,
+ msg="Forbidden",
+ hdrs={},
+ fp=io.BytesIO(body),
+ )
+
+
+def _capture_exit_output(callable_):
+ out = io.StringIO()
+ with redirect_stdout(out):
+ try:
+ callable_()
+ except SystemExit as exc:
+ assert exc.code == 1
+ return json.loads(out.getvalue())
+
+
+def test_banana_generate_redacts_upstream_http_error_body() -> None:
+ module = _load_module("banana_generate", "extensions/banana/scripts/generate.py")
+ with patch.object(module.urllib.request, "urlopen", side_effect=_http_error_with_key()):
+ payload = _capture_exit_output(
+ lambda: module.generate_image(
+ "prompt",
+ module.DEFAULT_MODEL,
+ "1:1",
+ "1K",
+ SECRET,
+ )
+ )
+
+ dumped = json.dumps(payload)
+ assert SECRET not in dumped
+ assert QUERY_KEY_ASSIGNMENT not in dumped
+ assert "AI" + "za" not in dumped
+
+
+def test_banana_edit_redacts_upstream_http_error_body(tmp_path: Path) -> None:
+ module = _load_module("banana_edit", "extensions/banana/scripts/edit.py")
+ image = tmp_path / "input.png"
+ image.write_bytes(b"not really png")
+ with patch.object(module.urllib.request, "urlopen", side_effect=_http_error_with_key()):
+ payload = _capture_exit_output(
+ lambda: module.edit_image(image, "prompt", module.DEFAULT_MODEL, SECRET)
+ )
+
+ dumped = json.dumps(payload)
+ assert SECRET not in dumped
+ assert QUERY_KEY_ASSIGNMENT not in dumped
+ assert "AI" + "za" not in dumped
diff --git a/tests/test_google_api_key_safety.py b/tests/test_google_api_key_safety.py
index 5f3d60e..d6ccaee 100644
--- a/tests/test_google_api_key_safety.py
+++ b/tests/test_google_api_key_safety.py
@@ -15,6 +15,7 @@ from unittest.mock import patch
import requests
_SCRIPTS = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "scripts")
+_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
if _SCRIPTS not in sys.path:
sys.path.insert(0, _SCRIPTS)
@@ -149,3 +150,13 @@ def test_lcp_subparts_uses_header_not_query_key() -> None:
assert captured["headers"]["X-Goog-Api-Key"] == SECRET
assert SECRET not in _dump(result)
assert QUERY_KEY_ASSIGNMENT not in _dump(result)
+
+
+def test_mcp_docs_do_not_show_google_query_key_examples() -> None:
+ text = open(
+ os.path.join(_REPO_ROOT, "docs", "MCP-INTEGRATION.md"),
+ encoding="utf-8",
+ ).read()
+ assert f'"{QUERY_KEY}": api_key' not in text
+ assert f"params = {{\"{QUERY_KEY}\": api_key}}" not in text
+ assert "X-Goog-Api-Key" in text
diff --git a/tests/test_manifest_consistency.py b/tests/test_manifest_consistency.py
index 7fa0b22..710fe05 100644
--- a/tests/test_manifest_consistency.py
+++ b/tests/test_manifest_consistency.py
@@ -58,6 +58,12 @@ def test_plugin_json_skill_count_matches_disk():
)
+def test_plugin_json_description_fits_registry_limit():
+ """plugin.json description must stay below the Claude plugin registry limit."""
+ plugin = json.loads(PLUGIN_JSON.read_text())
+ assert len(plugin["description"]) < 500
+
+
def test_plugin_json_subagent_count_matches_disk():
"""plugin.json description's 'N sub-agents' claim must equal agents/ count."""
plugin = json.loads(PLUGIN_JSON.read_text())
diff --git a/tests/test_url_safety.py b/tests/test_url_safety.py
index 45f00e8..67caa32 100644
--- a/tests/test_url_safety.py
+++ b/tests/test_url_safety.py
@@ -105,6 +105,8 @@ def test_validate_url_blocks_obfuscated_bypasses(url: str) -> None:
"https://user:[email protected]/",
"https://127.0.0.1#@example.com/",
"https://example.com%[email protected]/",
+ "https://metadata.google.internal%2e/",
+ "http://127.0.0.1%2e/",
],
)
def test_validate_url_blocks_authority_confusion(url: str) -> None: