qualia-framework 2.1.0

package/framework/skills/seo-master/SKILL.md

@@ -0,0 +1,490 @@
+---
+name: seo-master
+description: >
+  Comprehensive SEO audit, optimization, and automated fixing for any web project — local codebases or live sites.
+  Covers technical SEO (Core Web Vitals, structured data, meta tags, robots.txt, sitemaps, canonical URLs, hreflang,
+  mobile-first indexing), on-page SEO (titles, descriptions, headings, keywords, internal linking, image alt text),
+  content SEO (keyword research, content gaps, topic clusters, E-E-A-T), local SEO (Google Business Profile, local schema,
+  NAP consistency), performance SEO (page speed, lazy loading, CDN, compression), crawlability (redirect chains, orphan
+  pages, crawl budget), off-page SEO (backlink analysis, social signals), and monitoring (Search Console, rank tracking,
+  competitor analysis). Generates actionable reports with severity-ranked fixes and auto-applies safe fixes to code.
+
+  USE THIS SKILL whenever the user mentions: SEO, search rankings, Google rankings, meta tags, structured data, schema markup,
+  sitemap, robots.txt, Core Web Vitals, page speed optimization, keyword research, content gaps, backlinks, internal linking,
+  search console, indexing issues, crawlability, canonical URLs, hreflang, local SEO, Google Business Profile, E-E-A-T,
+  topic clusters, on-page optimization, technical SEO audit, SEO fix, rank tracking, competitor SEO analysis, or any request
+  to improve a website's search engine visibility — even if they don't explicitly say "SEO". If someone asks "why isn't my
+  site ranking?" or "how do I get more organic traffic?", this is the skill to use.
+---
+
+# SEO Master
+
+Complete SEO analysis, optimization, and automated fixing engine. Works on local codebases (React, Next.js, HTML, any framework) and live deployed sites via Firecrawl.
+
+## How This Skill Works
+
+This skill operates in two modes depending on context:
+
+1. **Local codebase mode** — When you're in a project directory. Reads source files directly, analyzes HTML output, checks meta tags in components, validates structured data, reviews sitemap generation, and **auto-fixes** issues in the code.
+
+2. **Live site mode** — When given a URL or domain. Uses Firecrawl to crawl the site, extract page data, analyze on-page elements, check technical infrastructure, and generates a report with manual fix instructions.
+
+Both modes produce a **Priority-Ranked SEO Report** at the end.
+
+## Execution Flow
+
+Run these phases in order. Skip phases that don't apply (e.g., skip local code analysis for a site you don't have source access to).
+
+### Phase 0: Context Detection
+
+Determine the operating mode:
+
+```
+IF user provided a URL/domain AND we're not in that project's codebase:
+  → Live site mode (Firecrawl)
+IF we're inside a project directory with source code:
+  → Local codebase mode (direct file access)
+IF both (user gave URL + we have the source):
+  → Hybrid mode (best of both — crawl live + fix source)
+```
+
+Ask the user which audit scope they want:
+- **Full audit** — everything below (default)
+- **Technical only** — phases 1-2
+- **Content only** — phases 3-4
+- **Quick scan** — critical issues only, fastest
+
+### Phase 1: Technical SEO Audit
+
+#### 1.1 Crawlability & Indexing
+
+**Local mode:**
+- Check for `robots.txt` in public/static directory. Verify it doesn't block important paths.
+- Check for XML sitemap generation (look for sitemap scripts, next-sitemap config, or static sitemap.xml).
+- Verify `<link rel="canonical">` on all pages. Check for duplicates or missing canonicals.
+- Check for `noindex`/`nofollow` meta tags — flag any that shouldn't be there.
+- Scan for orphan pages (routes defined but not linked from any other page).
+- Check redirect configurations (vercel.json, next.config.js, .htaccess) for chains (A→B→C) or loops.
+
+**Live mode (Firecrawl):**
+- Crawl the site starting from homepage. Map all discovered URLs.
+- Fetch and parse robots.txt.
+- Fetch and parse sitemap.xml. Compare sitemap URLs vs crawled URLs — flag mismatches.
+- Check HTTP status codes for all pages. Flag 4xx/5xx errors.
+- Detect redirect chains by following each redirect to final destination.
+- Check canonical tags on each crawled page.
+
+**What to report:**
+| Check | Status | Details | Fix |
+|-------|--------|---------|-----|
+| robots.txt | Pass/Fail/Warning | What's blocked, what's missing | Specific fix |
+| XML Sitemap | Pass/Fail | URL count, freshness, missing pages | Generate or fix |
+| Canonical tags | Pass/Fail | Pages missing or with wrong canonical | Add/correct |
+| Redirect chains | Pass/Fail | Chain paths found | Simplify to direct |
+| Orphan pages | Warning | Unreachable routes | Add internal links |
+
+#### 1.2 Core Web Vitals & Performance
+
+**Local mode:**
+- Scan for unoptimized images (no width/height, missing lazy loading, large formats like BMP/TIFF).
+- Check for `loading="lazy"` on below-fold images.
+- Check for `fetchpriority="high"` on LCP candidate (hero image).
+- Verify font loading strategy (font-display: swap, preload for critical fonts).
+- Check for render-blocking CSS/JS in the `<head>`.
+- Look for excessive DOM depth or large component trees.
+- Check bundle splitting configuration (dynamic imports, code splitting).
+- Verify image optimization setup (next/image, vite-imagetools, sharp, etc.).
+
+**Live mode:**
+- Use Firecrawl to fetch page HTML. Analyze document structure.
+- Check for resource hints (preconnect, prefetch, preload).
+- Analyze total page weight from HTML content.
+- Check for compression headers (gzip/brotli).
+- Check cache headers on static assets.
+
+**What to report:**
+| Metric | Status | Current | Target | Fix |
+|--------|--------|---------|--------|-----|
+| Image optimization | Pass/Fail | Details | Best practice | Specific fix |
+| Font loading | Pass/Fail | Strategy used | font-display: swap | Code change |
+| Code splitting | Pass/Fail | Bundle details | Dynamic imports | Code change |
+| Resource hints | Pass/Fail | What's missing | preconnect/preload | Add tags |
+
+#### 1.3 Mobile-First & Accessibility
+
+- Check viewport meta tag (`<meta name="viewport" content="width=device-width, initial-scale=1">`).
+- Verify responsive design patterns (media queries, fluid layouts).
+- Check touch target sizes (minimum 48x48px for interactive elements).
+- Scan for horizontal scroll issues (fixed widths > viewport).
+- Check font sizes (minimum 16px body text for mobile readability).
+
+#### 1.4 HTTPS & Security Headers
+
+**Live mode:**
+- Verify HTTPS with valid certificate.
+- Check security headers: HSTS, X-Content-Type-Options, X-Frame-Options, CSP.
+- Check for mixed content (HTTP resources on HTTPS pages).
+
+**Local mode:**
+- Check deployment config for security headers (vercel.json, next.config.js headers).
+- Verify no hardcoded HTTP URLs in source code.
+
+### Phase 2: Structured Data & Meta Tags
+
+#### 2.1 Meta Tags Audit
+
+For every page/route in the project:
+
+**Check these tags exist and are optimized:**
+- `<title>` — 50-60 chars, includes primary keyword, unique per page
+- `<meta name="description">` — 150-160 chars, compelling, includes CTA, unique per page
+- `<meta name="robots">` — appropriate directives
+- `<link rel="canonical">` — self-referencing or pointing to correct canonical
+- Open Graph tags: `og:title`, `og:description`, `og:image`, `og:url`, `og:type`
+- Twitter Card tags: `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image`
+- `<meta name="viewport">` — present and correct
+
+**Common issues to flag:**
+- Duplicate titles or descriptions across pages
+- Titles too long (truncated in SERP) or too short (wasting space)
+- Missing OG images (hurts social sharing CTR)
+- Generic descriptions that don't differentiate pages
+
+**Local mode — how to find meta tags:**
+- React Helmet / react-helmet-async: search for `<Helmet>` or `<HelmetProvider>`
+- Next.js: check `metadata` exports, `generateMetadata()`, or `<Head>` components
+- Plain HTML: check `<head>` sections
+- Vue/Nuxt: check `useHead()`, `useSeoMeta()`, or `<Head>` components
+- Astro: check frontmatter or `<head>` in layouts
+- Search for SEO components: Grep for patterns like `PageSEO`, `SEO`, `Meta`, `Head`
+
+#### 2.2 Structured Data (JSON-LD)
+
+Check for and recommend structured data types based on page content:
+
+| Page Type | Recommended Schema | Priority |
+|-----------|-------------------|----------|
+| Homepage | Organization, WebSite, SearchAction | High |
+| About page | Organization, Person | Medium |
+| Service pages | Service, FAQPage, HowTo | High |
+| Blog posts | Article, BlogPosting, BreadcrumbList | High |
+| Product pages | Product, Offer, AggregateRating | Critical |
+| Contact page | LocalBusiness, ContactPoint | High |
+| FAQ sections | FAQPage | High |
+| Case studies | Article, CreativeWork | Medium |
+| Events | Event | High |
+| Recipes | Recipe | High |
+| Videos | VideoObject | Medium |
+
+**Validation checks:**
+- JSON-LD is valid JSON (no syntax errors).
+- Required properties are present per schema.org spec.
+- No deprecated properties used.
+- @context is "https://schema.org".
+- Structured data matches visible page content (no cloaking).
+
+**Auto-fix capability (local mode):**
+Generate JSON-LD scripts for pages missing structured data. Place them in the appropriate component or layout. Use existing data from the page content to populate schema fields.
+
+#### 2.3 Heading Hierarchy
+
+- Verify exactly one `<h1>` per page containing the primary keyword.
+- Check heading hierarchy (h1 → h2 → h3, no skipped levels).
+- Flag pages with no h1 or multiple h1s.
+- Check that headings contain relevant keywords naturally (not keyword-stuffed).
+
+### Phase 3: On-Page & Content SEO
+
+#### 3.1 Content Quality Analysis
+
+For each major page, evaluate:
+
+- **Word count** — Informational pages should have 1000+ words for competitive keywords. Thin content (< 300 words) gets flagged.
+- **Keyword usage** — Primary keyword in first 100 words, in h1, in at least one h2, and naturally throughout. Keyword density between 1-2% is healthy — above 3% flags stuffing.
+- **Internal linking** — Each page should link to 3-5 related pages. Check for orphan pages with zero internal links pointing to them.
+- **Image alt text** — Every `<img>` needs descriptive alt text. Flag empty `alt=""` on content images (decorative images with empty alt are OK).
+- **URL structure** — Clean, readable, keyword-containing URLs. Flag dynamic parameters, excessive depth (>3 levels), or non-descriptive slugs.
+
+#### 3.2 E-E-A-T Signals
+
+Check for signals that demonstrate Experience, Expertise, Authoritativeness, and Trustworthiness:
+
+- **Author information** — Do blog posts have named authors with bio pages?
+- **About page** — Does it clearly establish who/what the organization is?
+- **Contact information** — Is there a real address, phone, email?
+- **Credentials** — Are certifications, awards, or affiliations mentioned?
+- **Social proof** — Testimonials, reviews, case studies present?
+- **External references** — Links to authoritative sources?
+- **Content freshness** — Are dates shown? Is content regularly updated?
+- **Privacy policy / Terms** — Do they exist?
+
+#### 3.3 Content Gap Analysis
+
+If the user provides target keywords or competitors:
+
+1. Use Firecrawl/web search to analyze competitor content.
+2. Identify topics competitors cover that the user doesn't.
+3. Find keyword opportunities where competitors rank but the user doesn't.
+4. Suggest content types the user is missing (guides, comparisons, glossaries, tools).
+5. Map content to buyer journey stages (awareness → consideration → decision).
+
+#### 3.4 Topic Cluster Strategy
+
+If the site has blog/content pages:
+
+1. Identify existing topic clusters (groups of related content).
+2. Find gaps in clusters (missing supporting articles).
+3. Suggest pillar page opportunities.
+4. Recommend internal linking between cluster pages.
+5. Provide a content calendar outline for filling gaps.
+
+### Phase 4: Local SEO (if applicable)
+
+Skip this phase if the business is purely online with no physical location or service area.
+
+#### 4.1 Local Schema Markup
+
+Check for LocalBusiness or Organization schema with:
+- Business name, address, phone (NAP)
+- Opening hours
+- Geo coordinates
+- Service area (for service-area businesses)
+- Price range
+- Payment methods accepted
+
+#### 4.2 NAP Consistency
+
+- Verify NAP (Name, Address, Phone) is consistent across:
+  - Website footer/contact page
+  - Structured data
+  - Google Business Profile (if URL provided)
+- Flag any inconsistencies.
+
+#### 4.3 Local SEO Checklist
+
+| Check | Status | Action |
+|-------|--------|--------|
+| LocalBusiness schema | | Add/fix |
+| NAP on contact page | | Verify |
+| Embedded Google Map | | Add if missing |
+| Location-specific title tags | | Optimize |
+| Location pages (multi-location) | | Create if needed |
+| Local keyword targeting | | Review |
+
+### Phase 5: Off-Page SEO Analysis
+
+This phase requires live site mode (Firecrawl + web search).
+
+#### 5.1 Backlink Profile Overview
+
+Use web search to assess:
+- Estimated domain authority/strength.
+- Types of sites linking to the domain.
+- Anchor text patterns.
+- Potential toxic/spammy backlinks.
+- Competitor backlink comparison.
+
+#### 5.2 Social Signals
+
+Check for:
+- Social media profile links on the website.
+- Open Graph / Twitter Card implementation (covered in Phase 2).
+- Social sharing buttons or functionality.
+- Content shareability assessment.
+
+#### 5.3 Link Building Opportunities
+
+Based on the site's niche, suggest:
+- Guest posting targets.
+- Resource page opportunities.
+- Broken link building targets.
+- Digital PR angles.
+- Industry directory submissions.
+
+### Phase 6: Monitoring & Ongoing SEO
+
+#### 6.1 Search Console Readiness
+
+Check that the site is set up for monitoring:
+- Sitemap submitted to Search Console (check for sitemap.xml).
+- Google Analytics or equivalent tracking installed.
+- Web Vitals monitoring (check for analytics/vitals reporting endpoint).
+
+#### 6.2 SEO Infrastructure
+
+- Does the site have an analytics setup? (GA4, Plausible, Fathom, etc.)
+- Is there a Web Vitals collection endpoint?
+- Are there 404 monitoring or error tracking tools?
+- Is there a content update workflow?
+
+#### 6.3 Competitor Benchmarking
+
+If competitors provided:
+- Compare title/description patterns.
+- Compare structured data usage.
+- Compare content depth and coverage.
+- Compare technical implementation.
+- Identify competitive advantages and gaps.
+
+## Auto-Fix Engine (Local Mode Only)
+
+After the audit, offer to auto-fix issues that are safe to apply. Categorize fixes by risk:
+
+### Safe to Auto-Fix (apply without asking)
+- Add missing `alt` attributes to images (generate descriptive text from context)
+- Add `loading="lazy"` to below-fold images
+- Add `fetchpriority="high"` to hero/LCP images
+- Fix heading hierarchy (h3 → h2 where h2 is skipped)
+- Add missing viewport meta tag
+- Add `font-display: swap` to @font-face declarations
+- Add `rel="noopener noreferrer"` to external links with `target="_blank"`
+
+### Fix with Confirmation (show diff, ask user)
+- Generate/update meta titles and descriptions
+- Add or update structured data (JSON-LD)
+- Create or update robots.txt
+- Create or update sitemap generation
+- Add canonical tags
+- Add Open Graph / Twitter Card meta tags
+- Add internal links to orphan pages
+- Optimize URL slugs in route definitions
+
+### Report Only (too risky or requires human judgment)
+- Content rewrites for keyword optimization
+- Redirect implementations
+- Hreflang setup for international sites
+- Schema changes for local business info
+- Backlink strategy execution
+
+When auto-fixing, always:
+1. Show the user what will change before applying
+2. Make atomic changes (one fix per edit, easy to review)
+3. Run the project's build/type-check after fixes to verify nothing broke
+
+## Report Format
+
+After all phases, produce a structured report. Use this exact template:
+
+```
+# SEO Audit Report: [Site/Project Name]
+**Date:** [date]
+**Mode:** [Local / Live / Hybrid]
+**Scope:** [Full / Technical / Content / Quick]
+
+## SEO Score: [X/100]
+
+Calculate based on weighted categories:
+- Technical SEO (25%): [X/25]
+- Meta & Structured Data (20%): [X/20]
+- On-Page & Content (25%): [X/25]
+- Performance (15%): [X/15]
+- Local SEO (5%): [X/5] (or N/A)
+- Off-Page (10%): [X/10]
+
+## Executive Summary
+
+[3-5 sentences: biggest strength, top 3 priorities, overall assessment]
+
+## Critical Issues (Fix Immediately)
+
+[Issues that are actively hurting rankings or blocking indexing]
+
+| # | Issue | Impact | Pages Affected | Fix |
+|---|-------|--------|----------------|-----|
+
+## High Priority (Fix This Week)
+
+| # | Issue | Impact | Pages Affected | Fix |
+|---|-------|--------|----------------|-----|
+
+## Medium Priority (Fix This Month)
+
+| # | Issue | Impact | Pages Affected | Fix |
+|---|-------|--------|----------------|-----|
+
+## Low Priority (Nice to Have)
+
+| # | Issue | Impact | Pages Affected | Fix |
+|---|-------|--------|----------------|-----|
+
+## Auto-Fixed Issues
+
+[List of issues that were automatically resolved, with before/after]
+
+## Keyword Opportunities
+
+| Keyword | Difficulty | Intent | Current Status | Recommended Action |
+|---------|-----------|--------|----------------|-------------------|
+
+## Content Recommendations
+
+[Topic clusters, content gaps, content calendar suggestions]
+
+## Technical Details
+
+[Detailed findings from each phase, for reference]
+
+## Next Steps
+
+1. [Most impactful action]
+2. [Second most impactful]
+3. [Third most impactful]
+```
+
+## Framework-Specific Patterns
+
+When working in local mode, adapt your analysis to the framework:
+
+### React (Vite/CRA)
+- SEO component: look for Helmet, react-helmet-async, or custom SEO components
+- Routing: react-router — check all `<Route>` definitions for pages
+- SSR/SSG: Check if using Vite SSR plugin or if it's pure SPA (SPA = limited SEO, flag this)
+- Structured data: usually in SEO components or inline `<script type="application/ld+json">`
+
+### Next.js
+- Metadata: check `metadata` exports and `generateMetadata()` in page/layout files
+- Sitemap: check for `sitemap.ts/js` in app directory or next-sitemap config
+- robots.txt: check for `robots.ts/js` in app directory
+- Structured data: JSON-LD in page components or via metadata API
+- Images: check usage of `next/image` vs raw `<img>`
+- Dynamic routes: check `generateStaticParams()` for proper static generation
+
+### Astro
+- SEO: check `<head>` in layout components, Astro SEO integration
+- Sitemap: check for `@astrojs/sitemap` integration
+- Content collections: check for proper frontmatter with SEO fields
+
+### Vue/Nuxt
+- SEO: check `useHead()`, `useSeoMeta()`, Nuxt SEO module
+- Sitemap: check for `nuxt-simple-sitemap` or `@nuxtjs/sitemap`
+- Routing: check pages directory structure
+
+### Static HTML
+- Direct `<head>` inspection per file
+- Check for consistent template patterns across pages
+
+## Using Firecrawl for Live Analysis
+
+When in live site mode, use Firecrawl to:
+
+1. **Crawl the site** — Start from homepage, discover all linked pages
+2. **Extract page data** — Get HTML, meta tags, headings, links, images per page
+3. **Check robots.txt** — Fetch and parse directly
+4. **Check sitemap** — Fetch XML sitemap, parse URLs
+5. **Analyze competitors** — Crawl competitor sites for comparison
+6. **Research keywords** — Search for keyword data and SERP features
+
+Firecrawl returns clean markdown optimized for analysis. Use it for any URL fetch — it handles JavaScript rendering and returns structured content.
+
+## Important Principles
+
+**Prioritize by impact.** Not all SEO issues are equal. A missing h1 on the homepage is critical. A missing alt tag on a decorative footer icon is low priority. Rank everything by actual impact on rankings and traffic.
+
+**Don't over-optimize.** Keyword stuffing, excessive schema markup, and manipulative tactics hurt more than they help. The goal is to make the site genuinely useful, well-structured, and easy for search engines to understand.
+
+**Context matters.** A personal blog doesn't need LocalBusiness schema. An e-commerce site doesn't need the same content strategy as a SaaS landing page. Adapt recommendations to the actual site type and business goals.
+
+**Measure what matters.** Focus on metrics that correlate with rankings: crawlability, page speed, content quality, structured data coverage, and internal linking — not vanity metrics.
+
+See `references/structured-data.md` for complete JSON-LD templates for every schema type.
+See `references/checklist.md` for the complete 100-point SEO checklist with pass/fail criteria.

package/framework/skills/seo-master/references/checklist.md

@@ -0,0 +1,199 @@
+# 100-Point SEO Checklist
+
+Complete pass/fail checklist with scoring. Each item is worth 1 point. Total score = number of passes out of 100.
+
+## Table of Contents
+
+1. [Crawlability & Indexing (15 points)](#crawlability--indexing-15-points)
+2. [Meta Tags & Head (15 points)](#meta-tags--head-15-points)
+3. [Structured Data (10 points)](#structured-data-10-points)
+4. [Content & On-Page (20 points)](#content--on-page-20-points)
+5. [Performance & Core Web Vitals (15 points)](#performance--core-web-vitals-15-points)
+6. [Mobile & UX (10 points)](#mobile--ux-10-points)
+7. [Security & Infrastructure (5 points)](#security--infrastructure-5-points)
+8. [Local SEO (5 points)](#local-seo-5-points)
+9. [Off-Page & Social (5 points)](#off-page--social-5-points)
+
+---
+
+## Crawlability & Indexing (15 points)
+
+| # | Check | Pass Criteria | Severity |
+|---|-------|--------------|----------|
+| 1 | robots.txt exists | File present at /robots.txt | Critical |
+| 2 | robots.txt not blocking important pages | No Disallow on key content pages | Critical |
+| 3 | XML sitemap exists | sitemap.xml present and valid | Critical |
+| 4 | Sitemap in robots.txt | Sitemap directive in robots.txt | High |
+| 5 | All important pages in sitemap | Key pages included, 4xx/5xx excluded | High |
+| 6 | Canonical tags on all pages | Every page has self-referencing or correct canonical | High |
+| 7 | No duplicate canonicals | Each canonical URL is unique | Medium |
+| 8 | No redirect chains | All redirects resolve in 1 hop | Medium |
+| 9 | No redirect loops | No circular redirects detected | Critical |
+| 10 | No orphan pages | All pages reachable via internal links | Medium |
+| 11 | Clean URL structure | No query params for content, readable slugs | Medium |
+| 12 | Proper 404 handling | Custom 404 page, correct status code | Medium |
+| 13 | No noindex on important pages | Key pages are indexable | Critical |
+| 14 | Hreflang (if multilingual) | Correct lang codes, reciprocal tags | High |
+| 15 | Crawl budget efficient | No infinite parameter URLs, faceted nav controlled | Medium |
+
+## Meta Tags & Head (15 points)
+
+| # | Check | Pass Criteria | Severity |
+|---|-------|--------------|----------|
+| 16 | Title tag on every page | All pages have `<title>` | Critical |
+| 17 | Titles are unique | No duplicate titles across pages | High |
+| 18 | Titles 50-60 characters | Within optimal length range | Medium |
+| 19 | Titles include target keyword | Primary keyword in title | High |
+| 20 | Meta description on every page | All pages have meta description | High |
+| 21 | Descriptions are unique | No duplicate descriptions | Medium |
+| 22 | Descriptions 150-160 characters | Within optimal length range | Low |
+| 23 | Descriptions include CTA | Action-oriented language | Low |
+| 24 | Open Graph tags present | og:title, og:description, og:image, og:url | Medium |
+| 25 | OG image meets requirements | 1200x630px minimum, < 8MB | Medium |
+| 26 | Twitter Card tags present | twitter:card, twitter:title, twitter:description | Low |
+| 27 | Viewport meta tag | `width=device-width, initial-scale=1` | Critical |
+| 28 | Language declared | `<html lang="en">` or appropriate | Medium |
+| 29 | Charset declared | `<meta charset="utf-8">` first in head | Medium |
+| 30 | Favicon present | favicon.ico or link rel="icon" | Low |
+
+## Structured Data (10 points)
+
+| # | Check | Pass Criteria | Severity |
+|---|-------|--------------|----------|
+| 31 | Organization schema on homepage | Valid Organization JSON-LD | High |
+| 32 | WebSite schema on homepage | With SearchAction if site has search | Medium |
+| 33 | BreadcrumbList on inner pages | Correct hierarchy matching navigation | Medium |
+| 34 | Article/BlogPosting on blog posts | With author, date, publisher | High |
+| 35 | FAQPage on FAQ sections | Valid Q&A markup | Medium |
+| 36 | Service schema on service pages | With provider and description | Medium |
+| 37 | LocalBusiness (if applicable) | With NAP, hours, geo | High |
+| 38 | No JSON-LD syntax errors | All scripts parse as valid JSON | Critical |
+| 39 | Schema matches visible content | No hidden or misleading data | Critical |
+| 40 | Required properties present | Per Google's rich result requirements | High |
+
+## Content & On-Page (20 points)
+
+| # | Check | Pass Criteria | Severity |
+|---|-------|--------------|----------|
+| 41 | One H1 per page | Exactly one `<h1>` on each page | High |
+| 42 | H1 includes primary keyword | Natural keyword inclusion | High |
+| 43 | Heading hierarchy correct | h1→h2→h3 without skipping levels | Medium |
+| 44 | Headings use target keywords | Secondary keywords in h2/h3 | Medium |
+| 45 | Keyword in first 100 words | Primary keyword early in content | Medium |
+| 46 | Keyword density 1-2% | Not over-stuffed, not absent | Medium |
+| 47 | Content length adequate | 300+ words for thin pages, 1000+ for competitive keywords | Medium |
+| 48 | All images have alt text | Descriptive alt attributes on content images | High |
+| 49 | Alt text includes keywords | Where natural and relevant | Low |
+| 50 | Internal links present | 3-5 internal links per content page | High |
+| 51 | Internal link anchor text descriptive | Not "click here" or "read more" | Medium |
+| 52 | External links to authoritative sources | Links out to trusted references | Low |
+| 53 | External links have rel attributes | `noopener noreferrer` on target="_blank" | Medium |
+| 54 | No broken internal links | All internal links resolve | High |
+| 55 | No broken external links | External links return 200 | Medium |
+| 56 | Content is original | No duplicate content issues | Critical |
+| 57 | E-E-A-T: Author attribution | Blog posts have named authors | Medium |
+| 58 | E-E-A-T: About page | Clear organization/person info | Medium |
+| 59 | E-E-A-T: Contact info visible | Email, phone, or contact form | Medium |
+| 60 | E-E-A-T: Social proof | Testimonials, reviews, or case studies | Low |
+
+## Performance & Core Web Vitals (15 points)
+
+| # | Check | Pass Criteria | Severity |
+|---|-------|--------------|----------|
+| 61 | Images optimized | WebP/AVIF format, appropriate dimensions | High |
+| 62 | Images have width/height | Explicit dimensions prevent CLS | High |
+| 63 | Lazy loading on below-fold images | `loading="lazy"` attribute | Medium |
+| 64 | Hero image prioritized | `fetchpriority="high"` on LCP image | High |
+| 65 | Fonts optimized | `font-display: swap`, preloaded critical fonts | Medium |
+| 66 | No render-blocking resources | Critical CSS inlined or async loading | High |
+| 67 | Code splitting implemented | Dynamic imports for route-based splitting | Medium |
+| 68 | Bundle size reasonable | Main bundle < 200KB gzipped | Medium |
+| 69 | Compression enabled | gzip or brotli on text assets | High |
+| 70 | Cache headers set | Static assets cached with long TTL | Medium |
+| 71 | Resource hints present | preconnect for external origins | Medium |
+| 72 | No excessive DOM depth | DOM tree < 1500 nodes for mobile | Medium |
+| 73 | CSS purging/tree-shaking | Unused CSS removed | Low |
+| 74 | JavaScript tree-shaking | Dead code eliminated | Low |
+| 75 | Preconnect to image CDN | `<link rel="preconnect">` for image hosts | Medium |
+
+## Mobile & UX (10 points)
+
+| # | Check | Pass Criteria | Severity |
+|---|-------|--------------|----------|
+| 76 | Responsive design | Adapts to all screen sizes | Critical |
+| 77 | Touch targets 48x48px minimum | Interactive elements large enough | High |
+| 78 | No horizontal scrolling | Content fits viewport width | High |
+| 79 | Font size 16px+ on mobile | Body text readable without zooming | Medium |
+| 80 | No intrusive interstitials | No popups covering main content on mobile | High |
+| 81 | Content accessible without JS | Core content visible if JS fails (SSR/SSG) | Medium |
+| 82 | Smooth scrolling behavior | No janky scroll, proper scroll restoration | Low |
+| 83 | Accessible navigation | Keyboard navigable, proper ARIA | High |
+| 84 | Color contrast passes WCAG AA | 4.5:1 for text, 3:1 for large text | Medium |
+| 85 | Skip to main content link | For screen reader accessibility | Low |
+
+## Security & Infrastructure (5 points)
+
+| # | Check | Pass Criteria | Severity |
+|---|-------|--------------|----------|
+| 86 | HTTPS everywhere | Valid SSL, no mixed content | Critical |
+| 87 | HSTS header present | Strict-Transport-Security set | High |
+| 88 | Security headers configured | CSP, X-Content-Type-Options, X-Frame-Options | Medium |
+| 89 | No exposed sensitive files | No .env, .git, wp-config accessible | Critical |
+| 90 | HTTP to HTTPS redirect | All HTTP requests redirect to HTTPS | High |
+
+## Local SEO (5 points)
+
+Skip if not applicable (online-only business). Award all 5 points if N/A.
+
+| # | Check | Pass Criteria | Severity |
+|---|-------|--------------|----------|
+| 91 | NAP consistent | Same Name/Address/Phone everywhere | High |
+| 92 | LocalBusiness schema complete | All required fields populated | High |
+| 93 | Google Maps embedded | On contact page | Medium |
+| 94 | Location in title tags | City/region in key page titles | Medium |
+| 95 | Location pages (multi-location) | Unique page per location | Medium |
+
+## Off-Page & Social (5 points)
+
+| # | Check | Pass Criteria | Severity |
+|---|-------|--------------|----------|
+| 96 | Social media profiles linked | Links to active social accounts | Low |
+| 97 | OG tags produce good previews | Tested with social media debuggers | Medium |
+| 98 | Shareable content present | Blog, resources, or tools worth sharing | Low |
+| 99 | Privacy policy page | Accessible from footer | Medium |
+| 100 | Terms of service page | Accessible from footer | Low |
+
+---
+
+## Scoring Guide
+
+| Score | Rating | Assessment |
+|-------|--------|------------|
+| 90-100 | Excellent | SEO-optimized, minor improvements only |
+| 75-89 | Good | Solid foundation, some gaps to address |
+| 60-74 | Fair | Needs attention, several important issues |
+| 40-59 | Poor | Significant problems hurting rankings |
+| 0-39 | Critical | Major SEO barriers, urgent fixes needed |
+
+## Priority Matrix
+
+When reporting issues, rank by this matrix:
+
+```
+                    HIGH IMPACT
+                        |
+        CRITICAL    |    HIGH
+        (fix now)   |    (fix this week)
+   -----------------+------------------
+        MEDIUM      |    LOW
+        (fix month) |    (nice to have)
+                        |
+                    LOW IMPACT
+
+   EASY FIX ←————————————→ HARD FIX
+```
+
+- **Critical** = High impact + Easy fix (quick wins)
+- **High** = High impact + Hard fix (strategic investments)
+- **Medium** = Low impact + Easy fix (batch these)
+- **Low** = Low impact + Hard fix (backlog)