SEO / AEO audit

Contract

Field	Bound contract
Trigger	Improve SEO, optimize for search, fix meta tags, add structured data, or improve AEO visibility.
Authority	Read-only. No file, VCS, credential, paid, published, deployed, or remote mutation.
Side effect	None: audit report only; no files are written, no services are modified.
Done	Report lists critical/high/medium issues, includes validated JSON-LD recommendations, and provides re-verification steps using Lighthouse, PageSpeed, and Search Console.

Inputs

• URL(s) (required): The target page or site URL(s) to audit.
• Focus area (optional): Narrow the audit to one or more of: technical, page, structured-data, aeo. Default: all four.
• JSON-LD template (optional): A caller-supplied local template used to validate structured-data recommendations.

Procedure

1. Confirm URL and scope. Require at least one target URL. Parse the scope argument or default to all four areas. Done when: the URL and scope are confirmed.
2. Run technical SEO checks. Execute Lighthouse against the target URL. Parse the output for: crawlability signals, indexability, HTTP status, canonical tags, robots directives, hreflang, sitemap presence, and Core Web Vitals. Record every violation as critical, high, or medium. Done when: technical SEO violations are recorded with severity.
3. Audit on-page elements. Fetch the page HTML. Parse title tags, meta descriptions, heading hierarchy (H1-H6), image alt attributes, internal/external link distribution, and content keyword density. Flag duplicate, missing, truncated, or over-stuffed elements. Done when: on-page element violations are recorded.
4. Audit structured data. Extract all <script type="application/ld+json"> blocks from the fetched page. Validate each against the appropriate JSON-LD schema type (Article, BreadcrumbList, FAQPage, Product, Organization, LocalBusiness, HowTo, SpeakableSpecification, or others). Report malformed, missing, or conflicting markup. If JSON-LD templates are available, compare the live markup against the recommended template for each detected type. Done when: structured-data violations are recorded with corrected JSON-LD blocks.
5. Audit AEO visibility. Assess the page for answer-engine optimization signals: clear entity definitions in the first 100 words, FAQ or HowTo blocks, SpeakableSpecification in structured data, passage-level relevance, and citation eligibility signals. Do not fabricate rankings or citations. Done when: AEO visibility findings are recorded.
6. Synthesize the report. Combine findings from steps 2-5. Assign every issue a severity: critical (blocks indexing), high (major ranking factor impact), or medium (improvement opportunity). Group under the four sections. For every structured-data finding, include the corrected JSON-LD block with the corrected fields shown. Done when: the report is synthesized with all findings grouped and severity-assigned.
7. Add re-verification steps. After the findings, append a Verification section with step-by-step instructions using Lighthouse (command-line command to re-run the audit), PageSpeed Insights API (curl command to fetch the pagespeed API result), and Google Search Console (URL Inspection API steps to verify index status). Done when: the Verification section is appended.
8. Return the report. Output the complete markdown report to the user. Do not write any file. Done when: the report is returned to the user.

Failure and recovery

• No URL provided: stop. Return "error": "url_required" with the message "Audit requires a target URL."
• Page unreachable: stop. Return "error": "page_unreachable" with the URL and the response code or error text.
• Script execution failure: catch the error. Return "error": "tool_execution_failed" with the script name and error output.
• Malformed JSON-LD detected: flag as a critical finding in the report. Include the raw block and the parsing error. Do not halt the audit.
• Zero findings in a category: state "No issues detected in this category" explicitly in the report rather than omitting the section.
• Partial tool results: include whatever data the tool returned. Mark any missing fields as "status": "unavailable" in the tool output block.

Output

A markdown audit report with a header (target URL, audit timestamp, scope), four sections (Technical SEO, On-Page SEO, Structured Data, AEO Visibility) each with severity-labeled issues and fixes, validated JSON-LD code blocks for every structured-data fix, a Verification section with exact re-verification commands, and a summary table with issue count by severity.