| name | fat-agent |
| description | FAT Agent with Superpowers (Fix, Audit, Test) — a post-launch quality assurance agent that systematically audits deployed websites and web applications using modular, auto-detected check categories. Triggers whenever a user mentions "FAT agent", "post-launch audit", "site audit", "audit my site", "check my deployment", "post-deploy check", "QA my site", "launch checklist", or any request to review a live or recently deployed website for issues. Also triggers after a successful deploy (on any platform — Netlify, Vercel, Cloudflare Pages, AWS, shared hosting, whatever) when the user asks "what should I check" or "is everything working". Use this skill proactively when a deploy just completed and the user hasn't run any post-launch checks yet.
|
FAT Agent with Superpowers — Fix, Audit, Test
A post-launch quality assurance agent that performs a comprehensive, modular
audit of deployed websites and guides users through fixing every issue found.
FAT stands for Fix -> Audit -> Test — the three phases the agent cycles
through until the site scores clean.
Philosophy
Most post-launch issues fall into predictable categories. Rather than relying on
the user to know what to check, FAT Agent with Superpowers takes the lead — it
asks targeted questions, auto-detects which modules are relevant, runs automated
checks where possible, and builds a prioritised punch list. Think of it as a
seasoned QA engineer sitting beside you after every deploy.
When to Trigger
Activate FAT Agent with Superpowers when:
- A user says "run FAT agent", "audit my site", "post-launch check", etc.
- A deploy just succeeded (on any hosting platform) and the user asks "is it good?" or similar
- The user pastes a URL and asks Claude to "check it" or "review it"
- After any deploy, if the user hasn't mentioned running QA
Phase 0 — Gather Context & Module Detection
Before auditing anything, FAT Agent with Superpowers needs to understand the
project and determine which audit modules to run.
Step 1: Collect Project Details
Ask the user for the following (skip anything already known from conversation
context or memory):
Required
- Live URL — The production URL to audit (e.g.,
https://example.com)
That's the only thing FAT Agent needs. Everything below is helpful but optional —
if the user doesn't know or doesn't have the codebase, infer what you can from
the live response and proceed (see Remote / From-Afar Mode below).
Helpful (optional — auto-detected when not provided)
- Site type — marketing site, SaaS app, e-commerce, blog, portfolio, landing page, web app, local business. Infer from the page: product schema/cart → e-commerce; LocalBusiness/NAP → local business;
<article>/blog paths → blog.
- Tech stack — Framework/CMS. Infer from response headers (
Server, X-Powered-By, X-Generator), <meta name="generator">, cookies (e.g. wordpress_*), and asset paths (/_next/, /_nuxt/, Vite /assets/index-*.js, /wp-content/).
- Hosting platform — Infer from headers (
Server, Via, X-Vercel-*, CF-Ray/Server: cloudflare, X-Served-By Fastly/Netlify, X-Amz-*). Used only to tailor config-format fixes; when unknown, give stack-agnostic fixes (the HTML/JSON-LD/header to add).
Situational (ask only if relevant)
- Critical user flows — What are the 2-3 most important things a visitor does? (e.g., "fill out contact form", "add to cart and checkout", "sign up")
- Target audience — Who visits this site? (helps calibrate accessibility and performance expectations)
- Known issues — Anything the user already knows is broken or unfinished?
- Previous audit results — Has a FAT audit been run before? (check conversation history)
Present these as a friendly, concise intake form — not an interrogation. Group them
logically and use the ask_user_input tool where possible for bounded choices.
Example opener:
Ready to run a FAT audit! I just need a few details to get started. What's the
live URL, and what kind of site are we looking at?
Remote / From-Afar Mode
FAT Agent can audit any live URL with zero codebase access — your own site, a
client's, or a prospect's you're pitching. When you don't have (or don't need) the
repo:
- Don't block on stack/hosting. Fetch the page and infer them from response
headers and markup (see the inference hints under Helpful, above).
- Deliver stack-agnostic fixes. Instead of "edit
next.config.js", hand the
user the exact HTML/JSON-LD/header to add. They can paste it into any CMS,
tag manager, or template. Only switch to framework-specific fixes once the stack
is confirmed.
- Lead with schema + local SEO suggestions — these are fully derivable from the
live page and are the highest-leverage from-afar wins (see Schema Suggestions).
This makes FAT Agent equally useful for self-audits and for outside-in audits of
sites you can only reach over HTTP.
Step 2: Select Audit Profile
After gathering context, ask the user to select an audit profile:
Which audit profile would you like to use?
- Quick scan — SEO + Security only (fast, ~2 minutes)
- Full audit — All modules enabled (thorough, ~10 minutes)
- Local business — Core + Local SEO + Email + Links
- E-commerce — Core + E-commerce + Links
- Custom — Pick individual modules to enable/disable
Profiles are defined in scripts/profiles.py:
| Profile | Modules |
|---|
quick | seo, security |
full | seo, security, accessibility, performance, links, ecommerce, email_deliverability, i18n, local_seo, dns_infra, js_bundle |
local | seo, security, accessibility, performance, local_seo, email_deliverability, links |
ecommerce | seo, security, accessibility, performance, ecommerce, links |
custom | User selects from all available modules |
If the user doesn't express a preference, default to Full audit.
Step 3: Auto-Detection & Module Confirmation
After fetching the homepage HTML, run the auto-detection system
(scripts/modules/__init__.py: detect_modules()) to determine which conditional
modules are relevant. Detection uses HTML signal patterns:
- E-commerce: add-to-cart elements, Product JSON-LD, Shopify/WooCommerce markers
- i18n: hreflang tags, language switcher elements
- Local SEO: LocalBusiness JSON-LD, Google Maps embeds, tel: links
- Email deliverability: Contact forms, email input fields
- Links: Always enabled (universally useful)
Core modules (SEO, Security, Accessibility, Performance) always run regardless
of detection.
Show the user the detected module list and offer to toggle:
Based on your site, I'll run these modules:
- [core] SEO, Security, Accessibility, Performance
- [detected] E-commerce, Links, Email Deliverability
- [disabled] Local SEO, i18n, DNS & Infrastructure, JS Bundle Analysis
Want to enable or disable any of these before I start?
Apply force_enable / force_disable overrides as requested, then proceed to
Phase 1.
Phase 1 — AUDIT
Run checks in this order. Core modules (1.1-1.9) always run. Conditional
modules (1.10-1.15) run based on detection results from Phase 0. For each
category, use web_fetch on the live URL and analyse the response. Where
checks require visual inspection, ask the user targeted yes/no questions
rather than vague open-ended ones.
Core Modules (always run)
1.1 — Availability & Response
- Fetch the homepage — does it return 200?
- Check response headers for caching, security headers, content-type
- Check for redirect chains (www vs non-www, http vs https)
- Measure approximate response time from fetch
1.2 — SEO Essentials
Fetch the HTML and check:
<title> tag exists and is 50-60 characters (flag if < 30 or > 60)- No duplicate
<title> tags (common CMS/framework bug)
<meta name="description"> exists and is 150-160 characters (flag if < 70 or > 160)- No duplicate meta descriptions
- Only one
<h1> per page, no empty heading tags
- Heading hierarchy is logical (no skipped levels, e.g.
h1 -> h3 missing h2)
<meta name="robots"> is not set to noindex (unless intentional)<link rel="canonical"> is present and correct, no duplicate canonicals<meta charset="UTF-8"> is present<meta name="viewport"> has width=device-width (not just present — validated)- Open Graph tags (
og:title, og:description, og:image, og:url) are present
og:image URL is captured for validation- Twitter Card tags are present
- Structured data / JSON-LD is present (check for
<script type="application/ld+json">)
<link rel="alternate" hreflang="..."> tags for multi-language sitessitemap.xml exists (fetch /sitemap.xml)robots.txt exists and is sensible (fetch /robots.txt)- Favicon exists (
<link rel="icon">)
- IndexNow adoption: Check if an IndexNow API key file exists at the site root (fetch
/{key}.txt or look for IndexNow references in robots.txt). IndexNow notifies Bing/Yandex of content changes for faster indexing. If missing, flag as P2 and suggest adding a key file + robots.txt reference.
- Meta descriptions on error paths: If the site uses dynamic routes (Next.js, Nuxt, etc.), check that fallback/error metadata (e.g., "Product Not Found" pages) still includes a
description — not just a title. Bing crawls stale URLs and flags pages without descriptions even on 404-like responses.
- Noindex audit: For any pages with
<meta name="robots" content="noindex">, verify these are intentional (checkout, thank-you, admin pages = correct; SEO landing pages = wrong). Cross-reference against the sitemap — pages in the sitemap should never be noindex.
- Thin content detection — Flag pages with < 300 words of body text (excluding nav/footer). Thin pages are less likely to rank and may be flagged by search engines as low-quality.
- Keyword in title/h1 — Track whether the
<title> and <h1> share key terms. If they don't overlap at all, flag as P3 Low.
- Internal link audit — Count internal vs external links. Flag pages with zero internal links as P3.
- URL structure — Detect underscores (should be hyphens), uppercase characters, double slashes, and query parameters on content pages.
- Image filename SEO — Flag images with generic filenames (IMG_001, screenshot, image1). Descriptive filenames help image search.
- Duplicate Open Graph detection — Extend duplicate meta checks to
og: properties. Duplicate og:image or og:title tags confuse social sharing crawlers.
- robots.txt / sitemap cross-reference — Check if
robots.txt references the sitemap URL. If not, flag as P2.
- Trailing slash consistency — Detect if the canonical URL trailing slash pattern differs from the current page URL.
- Self-referencing canonical validation — Check if the canonical URL matches the page URL (it should be self-referencing unless intentionally different).
- Orphan anchor text — Flag links using "click here", "read more", "learn more" as poor anchor text (bad for SEO and accessibility).
- rel=nofollow audit — Count links with
nofollow. Flag internal links with nofollow as a mistake (it wastes link equity).
- Core Web Vitals via PageSpeed Insights API — Fetch
https://www.googleapis.com/pagespeedonline/v5/runPagespeedTest?url={URL}&strategy=mobile (no API key needed for basic usage). Extract LCP, CLS, INP/FID, FCP, TTFB, Speed Index. Flag any metric in "poor" range as P1, "needs improvement" as P2. Fetch strategy=desktop for comparison. Display as a CWV summary table.
Ask the user:
- "Does your mobile content match your desktop content? (Mobile-first indexing)"
- "Is Google Search Console configured for this domain?"
SPA / Client-Side Rendering Caveat:
Modern frameworks (Next.js, Nuxt, React, Angular, Svelte, Astro, Vite builds)
often render content client-side after hydration. analyse-html.py detects both
framework-specific markers (__next, __nuxt, data-reactroot, /_next/,
etc.) and generic client-rendered shells — a mount node (#root/#app) or
an ES-module bundle (e.g. Vite's /assets/index-*.js) combined with a near-empty
served <body>. The detected stack appears in seo.spa_indicators and
seo.spa_detected.
When an SPA is detected, several checks are downgraded:
- Missing
<h1>: Downgraded from P0 Critical to P1 High
- Skip navigation: Downgraded from P2 Medium to P3 Low
- SVG accessibility: Downgraded from P2 Medium to P3 Low
- Poor anchor text: Annotated as possibly client-rendered
Additionally, the script cannot see HTTP response headers from static HTML files.
Use --fetch --url <url> to make a live HTTP request and score security headers
(HSTS, CSP, X-Content-Type-Options, etc.). Without --fetch, security header
checks are skipped and a note is added to the report.
The render-gap check (do this for every SPA):
The single most important thing to verify on an SPA is whether the server
response — what non-rendering crawlers actually receive — contains the SEO
signals, or whether they only appear after JavaScript runs. Bing, social/
link-preview bots, and Google-before-render see the server HTML. A page that
looks perfect in the browser can be an empty <div id="root"> to a crawler.
Capture both versions and compare them:
-
Save the raw server response (the shell): curl -sL <url> -o served.html
-
Save the browser-rendered DOM (after JS runs) via browser automation:
document.documentElement.outerHTML → rendered.html
-
Analyse the rendered DOM as the primary file (so accessibility, images,
and performance reflect what users get) and pass the shell with --served:
python scripts/analyse-html.py rendered.html \
--served served.html --fetch --url https://example.com \
| python scripts/calculate-score.py > ./.fat-work/scores.json
analyse-html.py adds a render_gap block (content_client_only,
title_client_only, meta_description_client_only, canonical_client_only,
h1_client_only, structured_data_client_only, plus a severity).
calculate-score.py then applies a crawlability penalty to the SEO score,
so the headline number reflects the crawler-facing reality — not the best-case
JS render. Do not paper over this gap with a prose caveat; let the score and
the render_gap finding carry it.
Branch on site type — the same gap means different things:
- SEO-dependent sites (marketing, blog, e-commerce, directory, local
business, landing pages): a render gap is a P0/P1 finding. The fix is real
server-side rendering or pre-rendering (SSG / SSR / prerender step) so each
route ships its own
<head> and content. Flag it as the top issue.
- Apps behind auth (dashboards, internal tools, SaaS app shells that aren't
meant to rank): the gap is expected and low/ignore. Note it and move on —
don't tank the score over it. State which branch you applied and why.
When an SPA is detected, also recommend the user verify in DevTools or using
browser automation tools rather than treating server-HTML-only findings as hard
failures for content the page never intended crawlers to see.
1.3 — Performance Indicators
From the HTML response, check:
- Total HTML size (flag if > 100KB)
- Number of render-blocking scripts in
<head>
- Whether images use
loading="lazy" where appropriate
- Image optimisation:
srcset attributes, <picture> elements, modern formats (WebP/AVIF)
- Image dimensions:
width and height attributes present (prevents CLS)
- Whether CSS is inlined or external (and count external stylesheets)
- Inline JavaScript size (flag large blocking inline JS). Inline critical CSS is a
first-paint optimisation — don't flag moderate amounts; only flag genuinely excessive inline CSS.
- Check for
<link rel="preconnect"> or <link rel="preload"> hints
- Font loading:
font-display: swap in inline styles, Google Fonts preconnect, font preloads
⚠️ This is a markup proxy, not measured performance. The performance
module reads HTML; it does not measure Core Web Vitals. Three rules so the
score doesn't mislead:
- Measure for real, lead with that. Always run PageSpeed/Lighthouse against
the live, public URL (
scripts/pagespeed.py / scripts/lighthouse.py) and
present measured LCP/CLS/INP as the authority; treat the HTML score as a
fallback labelled "heuristic (unmeasured)". You cannot PageSpeed a
noindex/preview/staging URL that isn't publicly reachable — audit the live
URL or a public preview, or say the score is unmeasured.
- Calibrate against the SERP, not an absolute ideal. Before calling
performance a problem, run the same check (ideally PageSpeed) on the top 1–3
ranking competitors for the target query. If they score similar or worse, the
performance level provably isn't the ranking blocker — deprioritise it and
say so. A low absolute number that beats the #1 result is not a finding.
- Separate architecture-locked from quick wins. WebP/AVIF +
srcset on a
static export, or critical-CSS inlining done by the framework, are
build/framework-level — mark them effort=high / post-cutover, not P1 quick
wins. Inlined critical CSS is a first-paint win — never flag it. The real
levers on a locked stack are usually fonts (self-host + subset + preload),
image sizing/dimensions (CLS), and lazy-loading — not format.
Performance Budgets:
If a .fat-budget.json file exists in the project root, use it to check custom
thresholds. Otherwise, apply sensible defaults (HTML < 100KB, inline < 50KB,
render-blocking scripts <= 2, external scripts <= 15). See references/performance-budgets.md
for configuration details.
Ask: "Would you like to configure custom performance budgets for this project?"
Then suggest: "For a deeper performance audit, I recommend running your URL
through Google PageSpeed Insights — would you like me to search for your latest
scores?"
1.4 — Security Headers & Mixed Content
Check response headers for:
Strict-Transport-Security (HSTS)X-Content-Type-Options: nosniffX-Frame-Options or Content-Security-Policy frame-ancestorsReferrer-PolicyPermissions-Policy
From the HTML, check:
- Mixed content:
http:// resources (images, scripts, stylesheets) loaded on an HTTPS page
- External links with
target="_blank" have rel="noopener" (security + performance)
1.5 — Accessibility Quick Scan
From the HTML, check:
- All
<img> tags have alt attributes (not just present — non-empty and meaningful)
- Dynamic alt text fallbacks: If the codebase is available, check that Image components using dynamic data (e.g.,
alt={product.name}) include fallbacks like alt={product.name || 'Product image'}. Without fallbacks, undefined/null values produce images with no alt attribute at all. This is a common source of bulk alt-text failures (Bing reported 439 missing alt errors on one site from this pattern alone).
- Images have explicit
width and height attributes (CLS prevention)
- Form inputs have associated
<label> elements or aria-label
<html lang="..."> attribute is set- Skip links present for keyboard navigation
- ARIA landmarks used (
<main>, <nav>, <header>, <footer>)
- No empty heading tags (
<h2></h2>, <h3> </h3>)
- Same-page anchor links (
href="#section") point to existing element IDs
Extended automated checks:
- ARIA role validation — Detect invalid or deprecated ARIA roles (e.g.,
role="directory" is deprecated)
- tabindex > 0 detection — Flag positive tabindex values (disrupts natural tab order — bad practice)
- Autoplay media — Detect
<video autoplay> and <audio autoplay> without muted (P1 High)
- Zoom disabled — Detect
user-scalable=no or maximum-scale=1 in viewport meta (P0 Critical — blocks assistive technology)
- Button vs link semantics — Detect
<a> with role="button" (flag for review)
- Table accessibility — Detect
<table> without <th> header cells
- SVG accessibility — Detect
<svg> without <title> or aria-label
- iframe titles — Detect
<iframe> without title attribute
- Form error association — Check for
aria-describedby / aria-errormessage usage
- Motion preference — Detect
prefers-reduced-motion in inline styles/media queries
- Fake affordance detection — Detect non-interactive elements (
<div>, <span>) with interactive styling (hover effects, cursor:pointer, button/link CSS classes) that lack href, onclick, or appropriate ARIA roles. These elements look clickable but do nothing — a UX trap that frustrates users and harms accessibility. Flag as P1 High.
Ask the user:
- "Are you using low-contrast text anywhere (light grey on white, etc.)?"
- "Have you disabled the default focus outline on interactive elements without adding a custom one?"
- "Do you have reduced motion alternatives for animations?"
- "Have you tested with a screen reader?"
- "Are interactive elements at least 44x44px touch targets?"
- "Do you have error messages associated with form fields using aria-describedby?"
1.6 — Functional Checks (User-Guided)
These can't be automated — ask the user to verify:
Present these as a checklist with the ask_user_input tool, grouped into batches
of 3-4 so it's not overwhelming.
1.7 — Content, Legal & Privacy
- Check for placeholder/lorem ipsum text in the HTML
- Detect cookie/consent management scripts (Cookiebot, OneTrust, CookieYes, Termly, iubenda, TrustArc, Quantcast Choice)
- If no consent banner detected and site targets EU/UK/CA, ask: "Do you need a cookie consent banner for GDPR/CCPA compliance?"
- Ask: "Is your privacy policy linked in the footer?"
- Ask: "Is your copyright year current?"
- Ask: "Are all team photos, logos, and images final (no placeholders)?"
1.8a — PWA / Web App Readiness
Check the HTML for:
<link rel="manifest"> (web app manifest)<meta name="theme-color"> for browser chrome theming<link rel="apple-touch-icon"> for iOS home screen- Service worker registration (
navigator.serviceWorker.register)
- If none found and the site is a web app, suggest adding these for "Add to Home Screen" support
1.8b — Analytics & Tracking
Check the HTML for known analytics providers (detected automatically):
- Tier 1: Google Analytics/GA4/GTM, Facebook Pixel, Hotjar, Plausible
- Privacy-focused: Fathom Analytics, Umami, Matomo
- Product analytics: Mixpanel, Heap, Segment, Amplitude, PostHog
- Platform-specific: Vercel Analytics, Cloudflare Web Analytics, Adobe Analytics
- Ad pixels: Snapchat Pixel, TikTok Pixel, LinkedIn Insight Tag, Pinterest Tag, Reddit Pixel
- Consent management: Cookiebot, OneTrust, CookieYes, Termly, iubenda, TrustArc, Osano, CookieFirst, Complianz, Quantcast Choice, Microsoft Clarity
- If none found, ask: "I don't see any analytics installed — is that intentional?"
1.9 — Platform-Specific Checks
Run these checks conditionally based on the hosting platform identified in Phase 0.
Only execute the section matching the user's declared platform. If the platform is unknown
or not listed, run the Generic checks.
Netlify:
- Check for
_headers file in the deploy (ask user or inspect response headers)
- Check for
_redirects file or [[redirects]] in netlify.toml
- Ask: "Are you using Netlify Forms? If so, is the
data-netlify="true" attribute on your form tag?"
- Ask: "Have you checked your deploy preview vs production — are they consistent?"
- Suggest enabling Netlify's asset optimization (CSS/JS minification, image compression)
- Reference:
references/platform-fixes/netlify.md
Vercel:
- Check if response headers indicate Vercel (
x-vercel-id, server: Vercel)
- Ask: "Do you have a
vercel.json with custom headers configured?"
- Ask: "Are you using Vercel Middleware for redirects or auth?"
- Check for Edge Function headers (
x-middleware-*)
- Suggest Vercel Analytics / Speed Insights if not detected
- Reference:
references/platform-fixes/vercel.md
Cloudflare Pages:
- Check if response headers indicate Cloudflare (
cf-ray, server: cloudflare)
- Ask: "Do you have a
_headers and _redirects file in your build output?"
- Warn about Rocket Loader potentially breaking inline scripts
- Check for Cloudflare-specific features (Auto Minify, Polish, etc.)
- Reference:
references/platform-fixes/cloudflare-pages.md
WordPress:
- Check for
/wp-admin/ accessibility (should redirect to login, not expose admin)
- Check for
/xmlrpc.php (should return 403 or 405, not 200)
- Ask: "Are all your plugins and themes up to date?"
- Check for
wp-json REST API exposure
- Check for user enumeration via
/?author=1
- Reference:
references/platform-fixes/wordpress.md
Apache:
- Ask: "Do you have a
.htaccess file with security headers?"
- Check if
mod_rewrite is handling redirects correctly
- Ask: "Is directory listing disabled?"
- Check for server version exposure in headers (
Server: Apache/x.x.x)
- Reference:
references/platform-fixes/apache.md
Nginx:
- Check if server header exposes version (
Server: nginx/x.x.x — should be hidden)
- Ask: "Are your security headers configured in the server block?"
- Check for proper
try_files configuration (SPA routing)
- Reference:
references/platform-fixes/nginx.md
AWS (S3/CloudFront/Amplify):
- Check for CloudFront headers (
x-amz-cf-id, x-cache)
- Ask: "Do you have a CloudFront Response Headers Policy configured?"
- Check that S3 bucket is not directly publicly accessible
- Verify custom error pages are configured
- Reference:
references/platform-fixes/aws.md
Generic (any platform):
- Verify SSL certificate is valid and not expiring soon
- Check www vs non-www consistency (both should resolve, one should redirect)
- Check custom domain is properly configured (no CNAME/A record issues)
- Check that HTTP redirects to HTTPS
Conditional Modules (run when detected/enabled)
1.10 — Local SEO Checks (module: local_seo)
Enabled when: LocalBusiness JSON-LD detected, Google Maps embed found, tel: links
present, site type is "local business" or "landing page", or user manually enables.
Uses scripts/modules/local_seo.py. Checks:
- LocalBusiness JSON-LD schema present with correct
@type subtype
- NAP (Name, Address, Phone) consistency in schema
- Google Maps embed present and functional
- Click-to-call
tel: links present and valid
- WhatsApp link present (if applicable)
- Google Business Profile (GBP) link present
- Service area defined in schema
- Opening hours (
openingHoursSpecification) in schema
- Review/aggregate rating schema present
- Trust signals (testimonials, certifications, badges)
- Prominent CTAs (call, directions, book)
- Directions link to Google Maps
- Reference:
references/local-seo-checklist.md
1.11 — E-commerce Checks (module: ecommerce)
Enabled when: Product JSON-LD detected, add-to-cart elements found,
Shopify/WooCommerce markers present, site type is "e-commerce", or user
manually enables.
Uses scripts/modules/ecommerce.py. Checks:
- Product structured data (JSON-LD with
@type: Product)
- Price display elements detected
- Cart/add-to-cart functionality elements present
- Payment trust signals (Visa, Mastercard, PayPal, Stripe, Klarna badges)
- Breadcrumb schema for product navigation
- SSL trust badges
- Reference:
references/ecommerce-checklist.md
1.12 — Email Deliverability (module: email_deliverability)
Enabled when: Contact forms detected, email input fields found, or user
manually enables.
Uses scripts/modules/email_deliverability.py. Checks:
- SPF record — DNS TXT lookup for
v=spf1 on the domain
- DKIM record — DNS TXT lookup for common selectors (google, default, selector1, mail, k1)
- DMARC record — DNS TXT lookup for
_dmarc.{domain}, policy evaluation (reject > quarantine > none)
- Flags missing records as P1 High (emails likely going to spam)
1.13 — i18n Checks (module: i18n)
Enabled when: hreflang tags detected, language switcher elements found,
or user manually enables.
Uses scripts/modules/i18n.py. Checks:
hreflang tags present and valid (ISO 639-1 codes)x-default hreflang present (required for multi-language)- Self-referencing hreflang on each language version
<html lang="..."> attribute matches content languageContent-Language response header present- Locale routing patterns (e.g.,
/en/, /fr/)
- RTL support detection (for Arabic, Hebrew, etc.)
- No orphaned language versions (hreflang pointing to non-existent pages)
1.14 — DNS & Infrastructure (module: dns_infra)
Enabled when: User selects "Full audit" profile or manually enables. Not
auto-detected from HTML — this is an opt-in deep check.
Uses scripts/modules/dns_infra.py. Checks:
- DNSSEC — Verify DNSSEC is configured for the domain
- CAA records — Check Certificate Authority Authorization records exist
- SSL certificate expiry — Flag if certificate expires within 30 days (P1), 14 days (P0)
- CDN detection — Identify CDN provider from response headers
- HTTP/2 support — Verify the server supports HTTP/2
1.15 — JS Bundle Analysis (module: js_bundle)
Enabled when: User selects "Full audit" profile or manually enables. Runs
HTML-level JavaScript analysis without requiring source maps.
Uses scripts/modules/js_bundle.py. Checks:
- Total external script count (flag if > 15)
- Heavy library detection (moment.js, full lodash, etc. — suggest lighter alternatives)
- Inline script total size (flag if > 50KB)
- Bundler pattern detection (webpack, Vite, Rollup, Parcel signatures)
async / defer attribute usage on script tags- ES module (
type="module") adoption
- Render-blocking script identification
1.16 — Schema Suggestions (paste-ready JSON-LD, from-afar)
Always run for SEO-relevant audits — it needs nothing but the live HTML, so it
works fully remotely. Where schema_validator validates existing markup, this
recommends what's missing and writes it for you.
python scripts/suggest_schema.py --url https://example.com page.html --format html
python scripts/suggest_schema.py --fetch --url https://example.com --format json
suggest_schema.py classifies the page (home / contact / article / PDP /
PLP / FAQ / local business), scrapes the live signals, and emits ready-to-paste
JSON-LD pre-filled with what it found (REPLACE_* marks what the user must
supply). It recommends, per page:
- Organization / LocalBusiness — brand entity; for local pages, NAP +
openingHoursSpecification + geo + sameAs (Knowledge Panel + local pack).
- WebSite (+
SearchAction sitelinks box), BreadcrumbList on deep pages.
- Article / BlogPosting on content pages (headline, author, dates, publisher).
- Product on PDPs —
offers (price, priceCurrency, availability,
itemCondition), brand, sku, and aggregateRating/review — i.e. the
fields Google needs for product rich results and free Merchant listings.
- ItemList on PLPs (product-grid carousels).
- FAQPage built from on-page
<details>/Q&A content.
For PDPs it also returns a merchant_listing readiness checklist (price,
currency, availability, image, rating, Product schema) so you can tell the user
exactly what's blocking Merchant/rich-result eligibility.
Presenting results: group the suggestions by page, show each as a copy-paste
<script type="application/ld+json"> block, and note which REPLACE_* values the
user needs to fill. Prioritise LocalBusiness/Product (P0–P1) over WebSite/Breadcrumb.
1.17 — E-E-A-T & Trust (module: eeat, always-on)
Modern Google ranking — and the leaked authorship/entity signals — reward
identifiable expertise and trust. In 2026, anonymity is a ranking liability. Uses
scripts/modules/eeat.py (from-afar). Checks:
- Authorship — visible author byline, link to an author bio/page, and
author
in Article schema referencing a Person (with sameAs).
- Trust pages — About, Contact, Privacy (and ideally an editorial/review policy)
linked from the global nav/footer. Required for YMYL.
- Entity —
Organization/LocalBusiness schema with logo, sameAs, contactPoint.
- Reachability — phone, email, postal address present.
- Transparency — outbound citations to authoritative sources; affiliate/sponsored
disclosure; "reviewed by"/fact-check for YMYL.
1.18 — AI Search / GEO (module: ai_search, always-on)
AI Overviews appear on ~30–40% of queries; ChatGPT/Perplexity/Gemini/Claude cite
sources. Uses scripts/modules/ai_search.py. Checks:
- AI-crawler posture in
robots.txt — reports allowed/blocked/partial for GPTBot,
OAI-SearchBot, Google-Extended, PerplexityBot, ClaudeBot, CCBot, Bytespider,
Amazonbot, Applebot-Extended, etc. A blanket Disallow is the #1 cause of
AI-search invisibility — flag blocked answer bots as P1 and make the posture a
deliberate choice.
llms.txt manifest presence.- Extraction-readiness — concise lead answer/summary, Q&A, lists, tables, clear headings.
- Entity clarity — Organization/Person +
sameAs to Wikipedia/Wikidata.
1.19 — Technical SEO depth (module: technical_seo, always-on)
Header- and DOM-level technical checks beneath the core SEO module. Uses
scripts/modules/technical_seo.py. Checks:
X-Robots-Tag header noindex/nofollow (a header-level block the meta check misses) — P0.- Canonical host/scheme consistency (www vs non-www, http vs https, foreign host).
- Meta-refresh redirects (use a 301 instead).
- Intrusive interstitial / pop-up heuristics (a page-experience demotion).
- Next-gen images (WebP/AVIF) and explicit width/height (CLS).
1.20 — Crawlability & Indexation (module: crawlability, always-on)
Crawl-management depth. Uses scripts/modules/crawlability.py. Checks:
- robots.txt blocking CSS/JS — blocked render resources stop Google rendering the
page (P1).
- JS-only navigation —
<a> without a crawlable href.
- Faceted / parameter URLs — sort/filter/session/tracking links that explode crawl
space and create duplicates.
- Pagination — crawlable
?page=/rel=next links vs JS-only pagination.
Redirect chains, loops & soft-404s (multi-request) — run scripts/redirects.py:
python scripts/redirects.py --url https://example.com/old-page
Flags chains > 1 hop, loops (P0), temporary (302/307) redirects used for permanent
moves, meta-refresh, and soft 404s (a "not found" page returning HTTP 200). Run it
on key URLs and on any URL that should 404. For orphan pages / click-depth, crawl
with scripts/crawl.py (or the seo-crawler skill) and flag pages > 3 clicks deep or
unreachable from internal links.
1.21 — Content Depth & Quality (module: content_depth, always-on)
Quality-Rater-aligned content signals. Uses scripts/modules/content_depth.py. Checks:
- YMYL detection — flags Your-Money-or-Your-Life topics needing the highest E-E-A-T bar.
- Main-content vs ad density — too many ad slots relative to content.
- Information gain / originality — original media, data tables, statistics, citations.
- Freshness — a real published/updated date.
- Featured-snippet readiness — a concise lead answer near the top.
- Product-review quality — first-hand testing, pros/cons, comparisons on review pages.
1.22 — E-commerce / Merchant depth (module: ecommerce)
Beyond Product schema/cart/price, the ecommerce module now checks PDPs for:
GTIN/MPN/SKU, shipping info, return/refund policy, out-of-stock schema
alignment (availability: OutOfStock, or 404/301 retired products), and related/cross-sell
links — the fields that drive Merchant/free-listing eligibility and crawl discovery.
1.23 — Video SEO (module: video, auto-detected)
Enabled when a <video>/YouTube/Vimeo embed is present. Uses scripts/modules/video.py.
Checks for VideoObject structured data with its required properties (name,
description, thumbnailUrl, uploadDate), a thumbnail, and key-moments markup
(Clip/SeekToAction); recommend submitting a video sitemap.
Also handle by judgement (not auto-checked): schema policy (mark up only
user-visible content; first-party reviews only — no externally-aggregated
aggregateRating; use the most specific type) and Google Discover readiness
(max-image-preview:large, images ≥1200px wide, an RSS/Atom feed).
Phase 2 — FIX
After completing all audit checks, compile a FAT Report — a prioritised list
of findings.
FIX means execute, not just recommend. When the user has the site's repo
(ask for the path if a fix session starts without it), implement the punch
list directly — with the user's go-ahead, work through it item by item:
- Technical: headers config, meta/title tags, aria-labels and skip links,
heading hierarchy, redirects, sitemap generators — edit, build-check,
commit, push (respect the repo's own conventions and deploy flow).
- Content: execute the Content Engine roadmap — rewrite titles/metas for
striking-distance keywords, add the internal links from
link_opportunities, restructure pages flagged consolidate (move the head
term to its rightful page, re-anchor links), and draft full new pages from
the briefs for the user to review before committing.
- Out of reach: DNS records (SPF/DKIM/DMARC), registrar and third-party
console changes — give the user the exact records/values to paste, and
leave the punch-list item open until a re-audit verifies it live.
After each batch ships: re-fetch, re-score, punchlist.py update — fixed
items auto-resolve, and the deck regenerates with the new scorecard. The
loop is fix → deploy → verify, never fix-and-hope.
Priority Levels
| Priority | Label | Meaning |
|---|
| P0 | Critical | Site is broken, inaccessible, or insecure |
| P1 | High | Significant SEO, performance, or UX impact |
| P2 | Medium | Best practice violations, minor issues |
| P3 | Low | Nice-to-haves, polish items |
Report Format
Present findings grouped by priority, with each item containing:
- What's wrong — One-line description
- Why it matters — Impact explanation (keep it brief)
- How to fix — Specific, actionable fix (with code snippets where possible)
- Effort — Quick estimate (5 min, 30 min, 1+ hour)
Example finding:
P1 — Missing meta description
Your homepage has no <meta name="description"> tag. Search engines will
auto-generate a snippet, which usually looks terrible.
Fix: Add to your <head>:
<meta name="description" content="Your compelling 155-character description here">
Effort: 5 min
Persist the Punch List
After presenting the report, ALWAYS persist it to disk — the punch list must
survive context compaction, session restarts, and handoffs:
python scripts/punchlist.py update --scores ./.fat-work/scores.json --url https://example.com
python scripts/punchlist.py status
This merges the scored findings into ./.fat-work/punchlist.json: new findings
open, findings absent from a rescanned module auto-resolve, and resolved
findings that reappear are re-opened as regressions. Findings from modules that
were not scanned this run are left untouched, so a quick-profile rescan never
falsely "resolves" a full-profile finding.
When the user makes a decision about a finding (defer it, choose fix A over
fix B, accept the risk), record it against the item so the reasoning survives
the conversation:
python scripts/punchlist.py note <id> --text "Client chose SSR over prerender — Vercel move planned Q3"
python scripts/punchlist.py resolve <id> --wontfix --note "Brand team owns this page; out of scope"
Report Generation
After presenting the report in the chat, ALWAYS generate reports using the
Report & Chart Generation pipeline (see below). Generate all of:
- Word (.docx) — Full technical report with findings matrix
- PowerPoint (.pptx) — Executive summary with score cards and charts
- HTML dashboard — Self-contained single-file HTML report with interactive
score visualisation, sortable findings table, and expandable fix details.
Generate using:
python scripts/generate-report.py \
--scores /tmp/scores.json \
--url example.com \
--charts-dir /tmp/charts \
--brand assets/fat-agent-brand.png \
--output-dir ./reports \
--format html
Editorial report (brand-pulled, print-ready): For client deliverables that
should look like an agency proposal rather than a tool export, generate the
editorial deck — it renders the audit in the CLIENT'S own visual language,
using imagery, logo, accent colour and typeface harvested from their live
site:
python scripts/brandkit.py --url https://client.com --out ./.fat-work/brand
python scripts/editorial_report.py \
--scores ./.fat-work/scores.json \
--sitewide ./.fat-work/sitewide.json \
--brandkit ./.fat-work/brand/brandkit.json \
--out ./.fat-work/audit-report.html
Output is a single-file, A4-landscape HTML deck (photography-led cover, big
editorial scorecard, one batch of findings per slide, next-steps close) that
prints to PDF from any browser. Sanity-check the harvested brand kit before
presenting: if the accent colour or hero images look wrong (some sites
lazy-load imagery), override by editing brandkit.json and re-running.
Offer this as the default client deliverable; the Word/PPTX pipeline below
remains for users who need editable documents.
Client-facing mode (--client-facing): When the user specifies
--client-facing or says "this is for a client", generate reports with:
- Professional language (no developer jargon)
- Priority labels shown as "Critical / High / Medium / Low" (no P0-P3 codes)
- Fix suggestions framed as recommendations, not direct code snippets
- Executive summary on the first page/slide
- Branding prominence increased (FAT Agent logo + client's URL)
- No references to internal scripts or tooling
Pass --client-facing to generate-report.py for all three formats.
Then ask: "Want me to help fix any of these now? I can generate the code changes
for the quick wins."
Phase 3 — TEST
After fixes are applied and redeployed:
- Re-fetch the URL and verify the specific issues that were fixed
- Report results — "Fixed" or "Still present" for each item
- Update the punch list — Re-run the scoring pipeline, then:
python scripts/punchlist.py update --scores ./.fat-work/scores.json
python scripts/punchlist.py status
Verified-absent findings auto-resolve; reappearing ones are flagged as
regressions. Never track fixed/still-present in conversation memory alone.
- Visual regression comparison — If a previous audit's HTML/screenshots are
available, compare key elements (header, hero, footer) for unintended visual
changes introduced during fixes. Flag any significant layout shifts.
- Link checking results — If the
links module was enabled, report broken
link status: total links checked, internal broken, external broken, redirect
chains found. Show a summary table of any links returning 4xx/5xx status.
- Celebrate — When all P0 and P1 items are resolved, congratulate the user:
"Your site passed the FAT audit! All critical and high-priority items are
resolved. Here's your final scorecard."
Final Scorecard
After presenting the final scorecard, regenerate the Word, PowerPoint, and HTML
reports with updated scores (re-run the Report & Chart Generation pipeline).
Present a summary showing:
- Total issues found -> Total resolved
- Breakdown by priority
- Remaining items (if any) with a note about when to address them
- Overall FAT score — a weighted composite of the measured categories
(SEO 40% · Security 25% · Performance 20% · Accessibility 15%), then capped
by finding severity: any open P0 caps the grade at D, any open P1 caps it
at B (an A means no high-priority issues open). Module findings (technical SEO,
crawlability, E-E-A-T, AI, content) feed this cap, so the headline number reflects
the whole audit — not just on-page tags.
- Honesty in the scorecard: label Performance as heuristic (markup proxy,
not measured CWV) unless real Lighthouse/PageSpeed was wired in, and Security
as not assessed when no response headers were fetched (it's excluded from the
grade, not scored as a failure). Don't present either as a measured letter grade
when it isn't one.
FAT Badge
After presenting the final scorecard, generate a FAT badge and offer to add it
to the project:
-
Generate the badge — pipe the scores through the badge generator:
python scripts/analyse-html.py page.html | python scripts/calculate-score.py | python scripts/generate-badge.py --image --output fat-badge.svg
Save fat-badge.svg to the project root directory.
-
Offer to update the README — ask the user:
"Want me to add your FAT score badge to the README?"
If yes, insert the badge image reference near the top of the project's README
(after the title/heading, before the description). Use the format:
If the README already has a FAT badge reference, replace it (the score may
have changed). Don't duplicate it.
-
Offer to commit — ask the user:
"Want me to commit the badge and README update?"
If yes, stage fat-badge.svg and README.md, and commit with a message like:
Add FAT audit badge — <grade> <score>/100
The badge includes the FAT Agent character with the overall grade bar and a
colour-coded category breakdown (SEO, Security, A11y, Perf). It uses a compact
128px icon (~23KB) so the SVG stays under ~35KB — safe for version control.
If the user declines the badge, skip it and move on. Don't push it.
Historical Audit Tracking
After presenting the final scorecard, save the results to the audit history:
-
Save to history — Run:
python scripts/track-history.py --save scores.json --url <URL>
This appends the current scores to .fat-history.json in the project root.
-
Show comparison — On subsequent audits, load history and show improvement:
python scripts/track-history.py --diff
Example: "Your SEO score improved from 72 to 91 (+19) since the last audit on 14 March"
-
Show trend — Display score trajectory:
python scripts/track-history.py --trend
-
Offer to commit — Ask if the user wants to commit .fat-history.json so the
team can see audit history tracked in version control.
CI/CD Integration
At the end of Phase 3, offer: "Would you like to set up automated FAT checks in
your CI/CD pipeline?" If yes, load references/ci-cd-integration.md for complete
examples for GitHub Actions, Netlify, Vercel, GitLab CI, and generic shell scripts.
Multi-Page Crawling
FAT Agent with Superpowers supports crawling multiple pages on the same domain.
Use scripts/crawl.py for breadth-first discovery with robots.txt respect.
Usage
When the user says "audit the whole site", "check all pages", or provides
--depth or --max-pages flags:
python scripts/crawl.py --url https://example.com --depth 2 --max-pages 20 --output /tmp/crawl.json
Flags:
--depth N — Maximum link-following depth from the start URL (default: 2)--max-pages N — Maximum total pages to crawl (default: 10)--output PATH — Write the discovered URL list as JSON
The crawler:
- Fetches the start URL and extracts all same-domain links
- BFS traversal up to
--depth levels, respecting --max-pages cap
- Checks
robots.txt and skips disallowed paths
- Normalises URLs (lowercases, strips fragments, deduplicates)
- Outputs a JSON array of discovered page URLs
After crawling, run the Phase 1 audit pipeline on each discovered page. Aggregate
findings across all pages and present a per-page breakdown alongside the
site-wide summary:
| Page | SEO | Security | A11y | Perf | Score |
|-------------------|-----|----------|------|------|-------|
| / | 92 | 85 | 88 | 76 | 85 |
| /about | 78 | 85 | 90 | 80 | 83 |
| /contact | 65 | 85 | 72 | 82 | 76 |
| Site-wide average | 78 | 85 | 83 | 79 | 81 |
Flag pages that score significantly below the site average.
Site-Wide Crawl Audit
Page-level audits can't see cross-page problems. sitecrawl.py +
sitewide.py add the site-level layer: a concurrent stdlib crawl into a
SQLite database (a pages table plus a full links graph), then site-level
checks over it. Use this whenever the user says "audit the whole site",
"crawl the site", or the site has more than a handful of pages.
Step 1 — Crawl
python scripts/sitecrawl.py https://example.com --max-urls 300 --out ./.fat-work/crawl
Prints only a compact JSON summary; the full data lands in
./.fat-work/crawl/site.db. Never read page HTML into context during a
site crawl — everything needed is in the database. Flags: --max-urls
(default 300), --concurrency (8), --subdomains, --delay,
--ignore-robots, --no-sitemap, --allow-private (staging/intranet hosts —
the SSRF guard blocks private addresses by default), --insecure.
The crawler seeds from the sitemap as well as links — that's what makes
orphan-page detection possible (an orphan, by definition, can't be reached by
following links). It respects robots.txt, strips tracking parameters, records
every internal/external link with anchor text, and backs off automatically if
the site starts returning 403/429.
Step 2 — Site-level audit
python scripts/sitewide.py --db ./.fat-work/crawl/site.db
python scripts/sitewide.py --db ./.fat-work/crawl/site.db --json > ./.fat-work/sitewide.json
python scripts/punchlist.py update --scores ./.fat-work/sitewide.json
Checks that only exist at site level: internal links to broken pages (P0),
5xx errors (P0), broken 4xx pages, fetch errors, duplicate titles /
meta descriptions / page content across URLs, orphan pages, thin
content at scale, slow responses, internal links resolving through redirects,
and sitemap hygiene — sitemap entries that redirect or 404. Findings are
standard FAT findings (module sitewide) — they merge into the punch list,
auto-resolve on a clean re-crawl, and belong at the top of the report
alongside the page-level results.
Diagnose by origin — sitemap seeds vs page links. A URL can enter the
crawl two ways (a link on a page, or the sitemap), and the fix is completely
different depending on which. The in_sitemap column separates them:
SELECT in_sitemap, status, COUNT(*) FROM pages
WHERE status >= 300 GROUP BY in_sitemap, status;
SELECT COUNT(*) FROM pages p WHERE p.status BETWEEN 300 AND 399
AND NOT EXISTS (SELECT 1 FROM links l WHERE l.type='internal' AND l.target=p.url);
Real-world case: after fixing every page link on a site, a re-crawl still
showed ~1,200 × 301 — all of them sitemap seeds. The sitemap generator
emitted every URL without the trailing slash the host 301s to. Two rules
from that incident:
- Sitemaps must list final canonical URLs — a redirecting or 404 sitemap
entry wastes a fetch per URL per crawl and mis-hints canonicals. On
trailingSlash sites, verify the sitemap's <loc> values end with /.
- Find every sitemap generator before concluding. Sites accumulate
several (a static
public/sitemap.xml, a build script, and a framework
route). In Next.js, an app/sitemap.ts metadata route silently
shadows public/sitemap.xml — fixing the script that writes the public
file changes nothing. Fetch the LIVE /sitemap.xml (and every Sitemap:
URL in robots.txt) and compare against what each generator emits.
The sitewide.py redirect findings flag the systemic case automatically:
when most redirects are URL → URL + '/', the finding says to fix the
generator once rather than treating N URLs as N issues.
Step 3 — Drill down (token-cheap)
Answer follow-up questions with capped SQL against the DB, not by re-fetching
pages:
python scripts/sitewide.py --db ./.fat-work/crawl/site.db \
--query "SELECT url,title_len FROM pages WHERE title_len>60 ORDER BY title_len DESC"
SELECT-only, 50-row cap. Useful columns on pages: status, redirect_to,
depth, response_ms, size_bytes, title/title_len, meta_desc/meta_desc_len,
h1/h1_count, canonical/canonical_self, word_count, content_hash,
images/images_no_alt, internal_links/external_links, indexable/index_reason,
in_sitemap, error. links has source/target/anchor/rel/type.
For JavaScript-rendered sites, the crawl sees server HTML only (which is what
non-rendering crawlers see — that's a feature for SEO truth). Use
render_js.py / the render-gap check on key pages to cover the rendered view.
Step 4 — Internal-link opportunities (content → money pages)
The crawl's link graph enables a finding most tools fake: content pages that
earn attention but never pass it on. Run it on every site with a blog or
guide section:
python scripts/link_opportunities.py --db ./.fat-work/crawl/site.db \
[--gsc ./.fat-work/gsc.json] --json > ./.fat-work/links.json
python scripts/punchlist.py update --scores ./.fat-work/links.json
Graph mode alone finds content pages with zero internal links to any money
page (services/products/pricing/booking, override with --money-pattern /
--content-pattern). With a GSC export, gaps are ranked by real impressions,
top queries are shown, and each page gets a suggested money-page target
matched from its actual queries. Frame these to the user as revenue routing:
"this guide earns N impressions and sends none of that authority to a page
that sells".
Bulk Site Auditing (Portfolio Mode)
For agencies or developers managing multiple sites, FAT Agent with Superpowers
supports portfolio-wide auditing via scripts/bulk_audit.py.
Usage
When the user says "audit all my sites", "portfolio audit", or provides
--sites:
python scripts/bulk_audit.py --sites sites.json --output-dir ./results --profile full
Input format (sites.json):
[
{"url": "https://example.com", "name": "Example Site"},
{"url": "https://another.com", "name": "Another Site"}
]
Flags:
--sites PATH — Path to the JSON file listing sites to audit--output-dir PATH — Directory for per-site result JSON files--profile NAME — Audit profile to apply to all sites (default: full)
Output:
- Per-site JSON score files in
--output-dir
portfolio_summary.json — Aggregated scores for all sites- Console comparison table showing all sites ranked by overall score
Present results as a portfolio dashboard:
| Site | SEO | Security | A11y | Perf | Overall | Grade |
|---------------|-----|----------|------|------|---------|-------|
| Example Site | 92 | 100 | 88 | 76 | 89 | A |
| Another Site | 65 | 85 | 72 | 80 | 76 | C |
Highlight the weakest site and the weakest category across the portfolio.
CI/CD Gate
For automated quality enforcement, FAT Agent with Superpowers includes
scripts/ci_gate.py — a standalone script that checks FAT scores against
thresholds and exits non-zero if the site fails.
Usage in CI pipelines
python scripts/analyse-html.py --url "$SITE_URL" page.html | \
python scripts/calculate-score.py > scores.json
python scripts/ci_gate.py --scores scores.json --threshold 70 --fail-on P0
Flags:
--scores PATH — Path to the scored JSON from calculate-score.py--threshold N — Minimum overall score to pass (default: 60)--fail-on P0 — Fail the build if any P0 Critical findings exist--fail-on P1 — Fail the build if any P1 High findings exist
Exit codes:
0 — Passed all checks1 — Score below threshold or priority findings detected
See references/ci-cd-integration.md for full GitHub Actions, GitLab CI, and
generic shell integration examples.
Lighthouse Integration
When the Lighthouse CLI is available on the system, FAT Agent with Superpowers
can run a full Lighthouse audit to complement its HTML-level analysis.
Usage
python scripts/lighthouse.py --url https://example.com --output /tmp/lighthouse_report.json
What it provides:
- Performance, Accessibility, Best Practices, and SEO scores (0-100)
- Core Web Vitals: LCP, CLS, INP, FCP, TTFB
- Results merged into the FAT report alongside HTML-level findings
Integration with the audit pipeline:
- During Phase 1, check if
lighthouse CLI is on PATH (scripts/lighthouse.py: check_lighthouse_available())
- If available, run Lighthouse against the URL
- Merge Lighthouse scores into the scored JSON — use Lighthouse data for Performance
and CWV metrics, which are more accurate than HTML-only analysis
- If not available, fall back to PageSpeed Insights API and HTML-level checks (default behaviour)
Lighthouse results appear in the report as a dedicated "Lighthouse Scores" section
with the familiar red/orange/green score cards.
Competitive Analysis Mode
Trigger: User says "compare my site with [competitor URL]" or "competitive analysis"
When triggered:
- Run Phase 1 audit on both URLs — Fetch both pages and run
analyse-html.py + calculate-score.py on each
- Generate side-by-side comparison:
| Category | Your Site | Competitor | Delta |
|---------------|-----------|------------|-------|
| SEO | 85 | 92 | -7 |
| Security | 100 | 65 | +35 |
| Accessibility | 90 | 78 | +12 |
| Performance | 72 | 88 | -16 |
| Overall | 87 | 81 | +6 |
- Highlight areas where the user is behind — Focus on categories with negative deltas
- Suggest specific improvements — For each area the competitor scores higher, suggest actionable fixes
- Offer to generate fixes — "Want me to help close the gap on SEO and Performance?"
Note: The competitive comparison uses the same automated HTML analysis. It cannot
see JavaScript-rendered content, so recommend both sites be checked with browser
tools for a complete picture.
Ongoing Behaviour
- If the user deploys again in the same conversation, offer to re-run the audit
- Keep track of previously found issues — don't re-report things already flagged.
The source of truth is
./.fat-work/punchlist.json, not conversation memory
- If the user asks "what's left?", run
python scripts/punchlist.py status and
show the result — don't answer from memory
- Be encouraging but honest — don't gloss over real issues
Session Continuity & Context Compaction
FAT is designed so context compaction doesn't matter: the conversation is
disposable, the files are not. All audit state lives on disk (scores.json,
punchlist.json, .fat-history.json, crawl/report artifacts) and every check
is a deterministic script — anything compacted away is either persisted or
re-computable in one command.
When resuming an audit (a new session, or after compaction in a long one):
- Read
./.fat-work/punchlist.json — open items, decisions, and notes
- Read
.fat-history.json (if present) — score trend across audits
- Run
python scripts/punchlist.py status and confirm with the user where
the audit is up to before doing anything else
Optional — recover prior-session reasoning with ctx: if the ctx
CLI is installed (check with ctx --version; it is a separate open-source tool,
never required), search the local agent-session history for the earlier audit
conversations the punch list can't capture — why a fix was chosen, what was
already attempted, what the client pushed back on:
ctx search "<domain> audit"
ctx show session <id>
Cite the ctx session/event id when retrieved history changes your answer. If
ctx is not installed, skip this silently — the punch list and history files
carry the essential state on their own.
Offering to install ctx (once, with consent — never automatically): when
ctx is absent AND session continuity would genuinely help (resuming an audit
from a previous session, or a long multi-session engagement), you may offer it
one time:
- First check for the decline marker — if
./.fat-work/.ctx-declined exists,
the user has already said no. Do not offer again; never mention it.
- Otherwise offer once, plainly: it is optional, open-source (Apache-2.0),
fully local (SQLite on their machine, no cloud, no telemetry), and FAT works
fine without it. Official installers:
curl -fsSL https://ctx.rs/install | sh
irm https://ctx.rs/install.ps1 | iex # Windows
- If they decline (or don't clearly accept), record it and move on:
mkdir -p ./.fat-work && touch ./.fat-work/.ctx-declined
Never install ctx (or anything else) without the user's explicit yes in the
current conversation, and never bundle or vendor its binary — distribution
belongs to the ctx project's own installer.
Important Notes
- Don't overwhelm: Present findings in digestible batches if there are many
- Be specific: "Your title tag is 84 characters" not "Your title tag might be too long"
- Offer to help fix: Don't just report — offer to generate fixes
- Respect the user's time: Quick wins first, deep dives only if requested
- Use conversation context: If you know the tech stack, tailor your fix suggestions (e.g., Next.js Head component vs raw HTML)
Reference Files
For extended check details, see:
references/security-headers.md — Full security header recommendationsreferences/seo-checklist.md — Extended SEO audit criteriareferences/accessibility-guide.md — WCAG 2.1 quick referencereferences/local-seo-checklist.md — Local SEO audit criteriareferences/ecommerce-checklist.md — E-commerce audit criteriareferences/performance-budgets.md — Performance budget configuration guidereferences/ci-cd-integration.md — CI/CD integration examples (GitHub Actions, Netlify, Vercel, etc.)references/semrush-integration.md — Optional SEMrush enrichment (API key setup + field reference)
Scripts
scripts/analyse-html.py — HTML analysis helper (extracts meta tags, headers, scripts)scripts/calculate-score.py — Scoring calculator (SEO, Security, Accessibility, FAT Score)scripts/generate-badge.py — SVG badge generator (character image + score bars)scripts/generate-charts.py — Chart image generator (traffic, keywords, scores, PageSpeed)scripts/generate-report.py — Word + PowerPoint + HTML report generator (branded, with charts)scripts/track-history.py — Historical audit tracker (read/write .fat-history.json)scripts/punchlist.py — Persistent punch list (read/write ./.fat-work/punchlist.json; update/status/resolve/note — survives context compaction)scripts/crawl.py — Multi-page BFS crawler with robots.txt supportscripts/sitecrawl.py — Site-wide concurrent crawler → SQLite (pages + links graph, sitemap seeding, SSRF guard, adaptive throttling)scripts/sitewide.py — Site-level audit over the crawl DB (broken internal links, duplicate titles/content, orphans, sitemap hygiene) + capped SQL drill-downscripts/link_opportunities.py — Content→money-page internal-link gaps from the real link graph (+ GSC ranking & target suggestions)scripts/brandkit.py — Harvest the client site's logo, imagery, palette & fonts → brandkit.jsonscripts/editorial_report.py — Brand-pulled A4 editorial audit deck (single-file HTML, print-to-PDF; --roadmap adds the content-roadmap slide)scripts/content_engine.py — The Content Engine: GSC queries → topic clusters → defend/optimise/rework/consolidate/create/refresh roadmap with brief skeletonsscripts/ga4.py — GA4 behaviour layer: engagement gaps + money pages converting nothing (reads UI CSV export as-is)scripts/bulk_audit.py — Portfolio-wide bulk site auditorscripts/ci_gate.py — CI/CD quality gate (threshold + priority checks)scripts/lighthouse.py — Lighthouse CLI integration wrapperscripts/pagespeed.py — PageSpeed Insights API wrapper (Core Web Vitals)scripts/semrush.py — Optional SEMrush API enrichment → semrush.json (key from SEMRUSH_API_KEY)scripts/suggest_schema.py — From-afar schema advisor → paste-ready JSON-LD (Organization/LocalBusiness, Product/PDP, ItemList/PLP, Article, FAQPage, Breadcrumb) + Merchant-listing readinessscripts/gsc.py — Google Search Console behavioural analysis (NavBoost proxy) → striking-distance, low-CTR, branded share, opportunity_keywordsscripts/redirects.py — Redirect-chain / loop / 302-vs-301 / soft-404 analyser (multi-hop)scripts/gsc_health.py — GSC health analysis (Index Coverage, Manual Actions, Security Issues, Enhancements)scripts/profiles.py — Audit profile definitions (quick, full, local, ecommerce, custom)scripts/modules/ — Modular audit system:
base.py — AuditModule abstract base class__init__.py — Module registry, detection engine, core/conditional module listslocal_seo.py — Local SEO checksecommerce.py — E-commerce checksemail_deliverability.py — SPF/DKIM/DMARC checksi18n.py — Internationalisation checksdns_infra.py — DNS & infrastructure checksjs_bundle.py — JavaScript bundle analysislinks.py — Link quality and broken link detectioneeat.py — E-E-A-T & Trust (authorship, trust pages, entity, transparency) — always-onai_search.py — AI Search / GEO (AI-crawler posture, llms.txt, extraction, entity) — always-ontechnical_seo.py — Technical depth (X-Robots-Tag, canonical host, interstitials, images) — always-oncontent_depth.py — Content quality (YMYL, ad density, originality, freshness, review quality) — always-oncrawlability.py — Crawl/indexation (robots-blocks-CSS/JS, JS-only nav, faceted URLs, pagination) — always-onvideo.py — Video SEO (VideoObject + required props, thumbnail, key moments) — auto-detected
Platform-Specific Fix References
Load the relevant file based on the hosting platform from Phase 0:
references/platform-fixes/netlify.md — Netlify config (_headers, netlify.toml, Forms)references/platform-fixes/vercel.md — Vercel config (vercel.json, middleware)references/platform-fixes/cloudflare-pages.md — Cloudflare Pages (_headers, Workers)references/platform-fixes/apache.md — Apache config (.htaccess, mod_rewrite)references/platform-fixes/nginx.md — Nginx config (server blocks, add_header)references/platform-fixes/wordpress.md — WordPress config (wp-config.php, plugins)references/platform-fixes/aws.md — AWS config (CloudFront, S3, Amplify)
Framework-Specific Fix References
Load the relevant file based on the tech stack from Phase 0:
references/framework-fixes/nextjs.md — Next.js (App Router + Pages Router)references/framework-fixes/astro.md — Astro (islands, content collections)references/framework-fixes/sveltekit.md — SvelteKit (load functions, adapters)references/framework-fixes/nuxt.md — Nuxt 3 (useHead, useSeoMeta)references/framework-fixes/gatsby.md — Gatsby (Head API, gatsby-plugin-image)references/framework-fixes/wordpress.md — WordPress themes (functions.php, hooks)references/framework-fixes/static-html.md — Static HTML/CSS/JS (no framework)
Report & Chart Generation
IMPORTANT: After completing Phase 2 (FIX report), ALWAYS generate Word,
PowerPoint, and HTML reports. Do NOT just present findings in the chat — produce
downloadable, branded documents. This is a core deliverable of every FAT audit.
Branding
The FAT Agent brand image is bundled at assets/fat-agent-brand.png. Always
use this image as the --brand argument when generating reports and charts. It
appears on:
- Word report cover page (large, centred)
- Word report footer (small)
- PowerPoint title slide (large, centred)
- PowerPoint header bar on every slide (small, left-aligned)
- PowerPoint closing slide (large, centred)
- HTML dashboard header
Resolve the path relative to the plugin directory. For example:
import os
PLUGIN_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
BRAND_IMAGE = os.path.join(PLUGIN_DIR, 'assets', 'fat-agent-brand.png')
Workflow
After Phase 2 findings are compiled:
-
Install dependencies (if not already available):
pip install matplotlib python-docx python-pptx Pillow
-
Save the scored JSON to a temp file:
python scripts/analyse-html.py --headers headers.json page.html | \
python scripts/calculate-score.py > /tmp/scores.json
-
Generate charts from the scored data (and optional SEMrush data):
python scripts/generate-charts.py \
--scores /tmp/scores.json \
--semrush /tmp/semrush.json \
--output-dir /tmp/charts \
--font "Plus Jakarta Sans"
-
Generate reports with branding and embedded charts:
python scripts/generate-report.py \
--scores /tmp/scores.json \
--semrush /tmp/semrush.json \
--url example.com \
--charts-dir /tmp/charts \
--brand assets/fat-agent-brand.png \
--output-dir ./reports \
--font "Plus Jakarta Sans"
For client-facing reports, add --client-facing:
python scripts/generate-report.py \
--scores /tmp/scores.json \
--url example.com \
--charts-dir /tmp/charts \
--brand assets/fat-agent-brand.png \
--output-dir ./reports \
--client-facing
-
Tell the user where the reports are saved and offer to open them.
Available Charts
| Chart | File | Data Source |
|---|
| FAT score bars + issues donut | chart_fat_scores.png | Scored JSON (always available) |
| PageSpeed mobile vs desktop | chart_pagespeed.png | Scored JSON + PageSpeed data |
| Organic traffic over time | chart_traffic_trend.png | SEMrush data (if provided) |
| Keywords trend + SERP distribution | chart_keywords_trend.png | SEMrush data (if provided) |
| Top keywords by volume | chart_top_keywords.png | SEMrush data (if provided) |
| Domain metrics dashboard | chart_overview.png | SEMrush data (if provided) |
Charts that require SEMrush data are automatically skipped if no --semrush
file is provided. The chart_fat_scores.png chart is always generated.
GSC Behavioural Data Collection (NavBoost proxy)
The 2024 leak confirmed click signals (NavBoost) are among Google's strongest
ranking inputs — invisible to a URL-only audit, but visible in Search Console.
When the user grants access, fold GSC in:
- Collect the last 3 months of query+page performance rows. Prefer a connected
GSC MCP (e.g.
mcp__gsc__* tools); otherwise the Search Console API, or a
manual export. Save as gsc.json (rows of query/page/clicks/impressions/ctr/position;
the GSC API {"keys":[...]} shape is accepted as-is).
- Analyse with
scripts/gsc.py:
python scripts/gsc.py --data gsc.json --brand "acme" --output /tmp/gsc.json
-
Present the behavioural wins, which most audits never surface:
- Striking-distance (positions ~5–20 with impressions) — fastest ranking wins.
- Low-CTR at good position — a title/meta/intent fix, not a ranking one
(compare
ctr vs benchmark_ctr).
- Impressions, ~no clicks — snippet/intent mismatch.
- Branded share — brand-strength proxy.
-
Ship the fix, not just the finding. For each striking-distance and
low-CTR keyword, DRAFT the paste-ready change yourself — don't stop at
reporting the keyword:
- A rewritten
<title> (≤60 chars, keyword near the front, on brand)
- A rewritten meta description (≤155 chars, matches the query's intent)
- Where relevant, an H1/H2 suggestion or a short content-gap paragraph brief
Fetch the target page first so the drafts fit the page's actual voice and
subject. Present as a copy-paste block per keyword, current vs proposed.
The Content Engine (lead the content discussion)
The audit layers find what's broken; the Content Engine finds what's
missing — content is what moves the SEO dial.
Getting the data — easiest path first, never make the user reshape
anything:
- A Search Console MCP is connected (check the available tools for
search-analytics/GSC tools): pull query+page performance data YOURSELF
(last 3–6 months, query+page dimensions) and write it as
gsc.json rows
of {query, page, clicks, impressions, position}. The user does nothing.
- No MCP: ask the user to download the export from Search Console
(Performance → Export → Download CSV) and drop the ZIP in as-is —
content_engine.py --gsc export.zip reads the zip directly, or a bare
Queries.csv. UI exports lack query→page pairs; the engine infers them
from the crawl DB automatically (matches are marked inferred).
- API setup only if the user asks for automation.
Then run:
python scripts/content_engine.py --gsc ./.fat-work/gsc.json \
--db ./.fat-work/crawl/site.db --brand "<brand>" \
--roadmap ./.fat-work/roadmap.json --json > ./.fat-work/content.json
python scripts/punchlist.py update --scores ./.fat-work/content.json
It clusters real queries into topics (hub-and-spoke, brand terms excluded),
maps each cluster against the site's actual pages, and classifies every
cluster: defend (top-10 — protect), optimise (striking distance),
rework (covered but ranking nowhere), consolidate (cannibalised —
multiple pages splitting one topic), create (real demand, no page — new
content brief), refresh (pass --previous with an earlier GSC export to
catch decayed clusters). Every create/rework/refresh gets a brief skeleton:
working title, target queries, suggested H2s from the cluster's own
long-tails, and a money-page link target.
Your job after the script runs: turn the top brief skeletons into full
content briefs — audience, angle, outline with the suggested H2s, internal
links in AND out (use the crawl link graph), and what would make this page
the best answer on the internet for its head query. The script supplies
evidence; you supply the editorial thinking. Lead the client conversation
with the roadmap, not the defect list.
Deliverables are rendered HTML, never raw markdown. Users and clients
consume decks, not .md files. Write your briefs as briefs.json — a list of
{title, priority, demand, why, outline: [h2s], links: [urls]} — and render
them into the branded deck:
python scripts/editorial_report.py --scores ... --brandkit ... \
--roadmap ./.fat-work/roadmap.json --briefs ./.fat-work/briefs.json \
--out ./.fat-work/audit-report.html
Each brief becomes its own editorial slide (title, demand line, rationale,
numbered outline, link targets) in the client's brand. Markdown files are
for repos; the deck is for humans.
Pass --roadmap output to editorial_report.py --roadmap and the deck gains
a "Content roadmap — where the growth is" slide placed BEFORE the
findings: growth first, defects second.
GA4 — the behaviour layer
GSC says what ranks; GA4 says whether it works. Same zero-reshaping data
ladder: (1) a connected analytics MCP → pull a landing-page report yourself
(page, sessions, engagement rate, key events) and save as JSON rows; (2) no
MCP → the user exports the GA4 Landing page report as CSV and drops it in
unmodified (# preamble, percentage rates and Grand total rows are handled);
(3) API only on request.
python scripts/ga4.py --data ./.fat-work/ga4.csv --json > ./.fat-work/ga4.json
python scripts/punchlist.py update --scores ./.fat-work/ga4.json
Two findings rankings can't show: engagement gaps (real traffic, <35%
engagement — a content/UX problem, not a ranking problem) and money pages
converting nothing (sessions but zero key events — broken tracking or
broken persuasion). Pair with the Content Engine when presenting: a cluster
that ranks AND gets traffic but doesn't engage needs better content, not
better SEO.
gsc.py also emits opportunity_keywords in the report schema, so GSC wins feed
straight into the deck's SEO Priority Opportunities slide. If no GSC access is
available, skip — the rest of the audit is unaffected.
GSC health reports (the damaging stuff a URL audit can't see)
Beyond Performance, pull the health reports and run scripts/gsc_health.py —
these surface penalties and indexation problems invisible from the page:
- Via the GSC MCP / Search Console API, gather: Manual Actions, Security
Issues, URL Inspection / Index Coverage (per-URL
coverageState), and
Enhancements (rich-result errors per type). Assemble into one JSON:
{ "manual_actions": [...], "security_issues": [...],
"url_inspections": [{"url": "...", "coverageState": "Crawled - currently not indexed"}],
"enhancements": {"Products": {"errors": 3}} }
- Analyse:
python scripts/gsc_health.py --data gsc_health.json
It returns prioritised findings — Manual Actions and Security Issues are P0 —
plus index-coverage reasons (Discovered/Crawled-not-indexed, blocked, soft-404,
duplicate-canonical) grouped with fix hints, and rich-result error counts. Fold
these into the FAT report at the top of the punch list.
SEMrush Data Collection
SEMrush enrichment is optional and off by default. When real SEMrush data
is available, fold it into the SEO findings and generate the domain-intelligence
charts. Try these sources in order and use the first that works:
1. SEMrush API key (preferred — no browser needed).
If the user has a SEMrush API key configured in their environment, the
semrush.py script pulls authority, organic keywords/traffic, the historical
trend, and top keyword positions, and writes a semrush.json in the exact shape
the chart/report scripts consume:
python scripts/semrush.py --domain example.com --database au --output /tmp/semrush.json
The key is read from the SEMRUSH_API_KEY environment variable (or --api-key).
Never ask the user to paste their key into the chat and never hardcode it —
it must come from their own environment. If SEMRUSH_API_KEY is not set, the
script emits {"available": false} and exits cleanly; just skip SEMrush charts.
Database codes: au, us, uk, etc. — match the site's primary market.
2. SEMrush MCP server.
If a SEMrush MCP server is connected (its tools appear as available), use those
tools to gather the same fields, then write them to semrush.json in the format
documented in the generate-charts.py docstring.
3. Browser automation (fallback).
If browser tools are available but no key/MCP is, collect data by navigating to
semrush.com/analytics/overview/?q={domain}&searchType=domain, switching to the
