description: "Reference reference guide for technical audit weights and schemas" version: "1.0"

SEO Audit Reference — Scripts, Weights & Output Contract

Internal reference for /seo-audit workflow. This file contains the detailed script commands, weight tables, and output schemas. The main workflow file (seo-audit.md) references this file — do NOT duplicate content.

Audit Scripts

Run these scripts on the homepage (or primary URL). For priority/full scope, run content_scorer and onpage_auditor on each page; other scripts run once on homepage.

# Category 1: Technical SEO (17%)
python .agents/scripts/run_plugin_script.py seo-technical technical_auditor.py <url> --json

# Category 2: Content Quality (20%)
python .agents/scripts/run_plugin_script.py seo-content content_scorer.py <url> --json

# Category 3: On-Page SEO (13%)
python .agents/scripts/run_plugin_script.py seo-content onpage_auditor.py <url> --json

# Category 4: Schema / Structured Data (10%)
python .agents/scripts/run_plugin_script.py seo-schema schema_validator.py <url> --json

# Category 5: Sitemap (5%)
python .agents/scripts/run_plugin_script.py seo-sitemap sitemap_analyzer.py <domain> --json

# Category 6: Images (5%)
python .agents/scripts/run_plugin_script.py seo-images image_auditor.py <url> --json

# Category 7: Hreflang / International (5%)
python .agents/scripts/run_plugin_script.py seo-hreflang hreflang_validator.py <url> --json

# Category 8: AI Search Readiness / GEO (10%)
python .agents/scripts/run_plugin_script.py seo-geo geo_analyzer.py <url> --json

# Category 9: Link Health (5%) — crawls entire site
python .agents/scripts/run_plugin_script.py seo-technical link_auditor.py <url> --json

# Category 10: Site-Wide Analysis (5%) — crawls entire site
python .agents/scripts/run_plugin_script.py seo-technical site_analyzer.py <url> --json

# Category 11 (optional): Google APIs — CWV, CrUX, GSC
python .agents/scripts/run_plugin_script.py seo-google google_auth.py --check
# If auth OK:
python .agents/scripts/run_plugin_script.py seo-google pagespeed_check.py <url> --audit-format

Weight Table

If Google CWV unavailable → weights auto-redistribute proportionally (95% → 100%).

Goal & Industry Adjustments

Aggregator outputs actual weights used in weights_used field.

Script Output Contract

Every audit script returns this JSON structure:

{"url": "...", "category": "...", "score": 78, "max_score": 100,
 "findings": [{"id": "...", "source": "[FETCHED]", ...}],
 "summary": {"pass": N, "warn": N, "fail": N}}

Multi-Page Strategy

• Average scores across pages for Content and On-Page categories
• link_auditor.py and site_analyzer.py crawl entire site automatically (no page limit)
• Other scripts (technical, schema, sitemap, images, geo) run on homepage only
• Report per-page scores in the detailed findings section

Comparison (Delta Tracking)

When --compare flag is provided or a previous audit exists in project.json.runs[]:

python .agents/scripts/run_plugin_script.py seo-core score_aggregator.py <current_dir> --compare <previous_audit.json> --json

The aggregator outputs comparison object with:

• health_score.delta — overall score change
• category_deltas — per-category changes with trend arrows
• resolved_issues — issue IDs fixed since last audit
• new_issues — new issue IDs not in previous audit
• persistent_issues — issues present in both audits

Display delta table in report (category, previous, current, delta arrows). If no previous audit → state: "First audit — no baseline for comparison."

Project Run Entry Example

{
  "date": "2026-04-13",
  "type": "audit",
  "phase": "audited",
  "score": 67,
  "category_scores": {
    "technical": 78, "content": 62, "onpage": 71,
    "schema": 55, "ai_readiness": 48, "sitemap": 80,
    "images": 85, "hreflang": 100, "links": 72,
    "site_analysis": 89, "cwv": null
  },
  "scope": "priority",
  "pages_analyzed": 8,
  "report": "reports/audit-2026-04-13.md",
  "data": "data/audit-2026-04-13.json"
}