Forem: Joseph Anady

Internal linking: hub-and-spoke architecture

Joseph Anady — Sun, 24 May 2026 02:33:27 +0000

Originally published at thatdevpro.com. Part of ThatDevPro's open SEO + AI framework library. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.

Hub-and-Spoke Architecture, Anchor Text Discipline, Topical Clusters, Crawl Depth, Orphan Detection, and Link Equity Distribution

A comprehensive installation and audit reference for internal linking — the discipline of using on-site links to communicate site architecture to crawlers, distribute ranking signals across pages, and guide users through topical depth. Internal linking is one of the highest-ROI SEO levers because it costs nothing per link added and compounds across the entire site. Dual-purpose: installation manual and audit document.

1. Document Purpose

This is the canonical reference for internal linking. Most sites have content that ranks. Most sites have technical SEO that works. Few sites have internal linking that does what it should. The gap shows up as orphan pages, shallow content, ranking signals trapped on the homepage, and topical clusters that exist on paper but not in the link graph.

In 2026, internal linking has become more important, not less. AI search engines parse internal link patterns to understand topical authority. Google's crawl-budget allocation favors well-linked pages. Topical-cluster ranking — a page ranks when its surrounding cluster ranks — is now a measurable phenomenon. Sites that use internal linking strategically outrank sites with better content but flatter link graphs.

1.1 Required Tools

Screaming Frog SEO Spider — desktop crawler; reveals link graph, orphan pages, anchor text
Sitebulb — desktop crawler with stronger reporting on crawl depth and link counts
Ahrefs Site Explorer — Internal Backlinks — sitewide internal link audit
Ahrefs Site Audit — Internal Linking — detects orphan pages, broken links
Semrush Site Audit — Internal Linking — alternative
Google Search Console — Links report — Google's view of internal linking
Link Whisper (WordPress) — automated internal-link suggestion
Custom Python + BeautifulSoup — for programmatic link extraction at scale
Graphviz / yEd / Gephi — for visualizing link graphs
Spreadsheet (Sheets or Excel) — link inventory management

1.2 Document Scope

Covers: site architecture patterns, hub-and-spoke / topical-cluster organization, anchor text discipline, crawl depth, orphan detection, link equity distribution, contextual vs navigational linking, breadcrumbs, faceted navigation handling, and pagination patterns. Touches but does not exhaust: keyword research and topic mapping (framework-keywordresearch.md), schema's BreadcrumbList (framework-schema.md), navigation UX (framework-uxseo.md).

2. Client Variables Intake

domain: ""
total_pages_indexed: 0
content_taxonomy_documented: false
hub_pages_identified: []
known_orphan_pages: []
existing_internal_link_strategy: ""    # describe or "none"
sitemap_url_count: 0
crawl_depth_max_observed: 0            # from Sitebulb / Screaming Frog
average_internal_links_per_page: 0
top_traffic_pages: []
top_conversion_pages: []
known_cannibalization: []              # cross-reference framework-keywordresearch.md

3. The Three Functions of Internal Links

Every internal link does three things at once:

Architectural — tells crawlers and users that the linked page exists and matters.
Topical — tells crawlers what the linked page is about (via anchor text and surrounding content).
Equity — passes a portion of the source page's ranking signals to the target.

A weak link does one. A strong link does all three.

4. Site Architecture Patterns

4.1 The Hub-and-Spoke Model

The dominant architecture pattern for content sites and most service businesses.

                  Homepage (root hub)
                  /         |         \
              Hub A      Hub B       Hub C
              /  \         |         /  \
           Sub  Sub     Sub Sub    Sub  Sub
            \    \       |   /     /    /
             [back-links to hub from each spoke]

The pattern:

Pillar / hub pages cover a broad topic comprehensively. They link out to all relevant sub-pages.
Cluster / spoke pages cover narrow sub-topics in depth. They link back to their hub.
Cross-cluster links are sparing and used only when topically warranted.

Why it works:

Hubs accumulate link equity from spokes.
Spokes signal topical depth around the hub.
Crawlers see a clear topical structure.
Users navigate naturally between depth levels.

4.2 The Mesh Model

For wikis, knowledge bases, and densely interconnected content, a mesh works better than strict hubs.

Every page links to many topically related pages.
No strict hierarchy.
Depth comes from cross-references, not parent-child.

Wikipedia is the canonical mesh. It's appropriate for sites with hundreds of densely related entities. Most agency clients should use hub-and-spoke instead.

4.3 The Catalog Model (Ecommerce)

For ecommerce:

Homepage → Category → Subcategory → Product
Cross-links between related products
Cross-links from category to comparison guides (cluster overlay)

Cross-reference: framework-ecommerceseo.md.

4.4 The Editorial Model (Publishers)

For news and editorial sites:

Section → Article
Articles link forward to follow-up coverage
Articles link back to evergreen explainer pages
"Related articles" widgets serve as soft hubs

Cross-reference: framework-newsseo.md.

5. Topical Clusters

A topical cluster is a hub page plus all the spokes that cover the topic. Clusters are how modern sites compete for broad topics they couldn't dominate with a single page.

5.1 Cluster Anatomy

For a cluster on "Local SEO":

HUB: /topics/local-seo/  (pillar page, comprehensive overview)

SPOKES:
  /topics/local-seo/google-business-profile/
  /topics/local-seo/local-citations/
  /topics/local-seo/local-pack-ranking/
  /topics/local-seo/review-management/
  /topics/local-seo/local-link-building/
  /topics/local-seo/local-schema/
  /topics/local-seo/local-content-strategy/

Each spoke:

Links back to the hub in the opening paragraph
Links back to the hub in the conclusion
Links to 2-3 sister spokes in topically appropriate places
Does not link to spokes from unrelated clusters

The hub:

Links to every spoke at least once
Includes a structured "in this cluster" section listing spokes
Updates as new spokes are added

5.2 Cluster Sizing

Cluster size	Strategy
3-5 spokes	Minimum viable cluster. Common starting point.
6-10 spokes	Healthy cluster. Most competitive topics need this depth.
11-20 spokes	Authoritative cluster. Often the bar for ranking head terms.
20+ spokes	Pillar treatment. Reserved for category-defining hubs.

5.3 Cluster Identification

For existing sites:

Inventory all content pages.
Group by topical theme.
Identify the strongest existing piece per theme as the candidate hub.
Document the cluster gap (sub-topics not yet covered).
Decide: build out the cluster, or consolidate into fewer pages?

For new sites:

Start with keyword research (framework-keywordresearch.md).
Identify head term per cluster.
Decide on hub URL and 5-10 starting spokes.
Build hub first; spokes can roll out over weeks.

6. Anchor Text Discipline

Anchor text — the visible link text — is one of the strongest topical signals to Google.

6.1 Anchor Text Types

Type	Example	When to use
Exact match	`<a href="/local-seo/">local SEO</a>`	Sparingly; risk of over-optimization
Partial match	`<a href="/local-seo/">our guide to local SEO</a>`	Most common; safest
Branded	`<a href="/local-seo/">read more on ThatDeveloperGuy</a>`	Brand-building; less topical signal
Generic	`<a href="/local-seo/">click here</a>`	Avoid. Wastes the topical signal.
Naked URL	`<a href="/local-seo/">thatdeveloperguy.com/local-seo/</a>`	Avoid for internal links; fine for citations
Image	image with `alt="local SEO guide"`	Alt text serves as anchor; use descriptive alt

6.2 Anchor Text Patterns That Hurt

"Click here", "read more", "learn more" — wasted signal. Especially bad on important hub links.
The same exact-match anchor on every link to a page — over-optimization, looks unnatural.
Mismatched anchor and target — anchor says "plumbing" but page is about "electrical work."
Stuffed anchors — <a>local SEO services Cassville Missouri SDVOSB</a> reads as keyword stuffing.

6.3 Healthy Anchor Distribution

For a typical hub page with many internal pointers, anchor text should vary naturally:

~30% exact or partial-match topic anchors
~30% partial-match with surrounding context ("our guide to...", "more on...")
~20% branded or contextual ("we've covered this on the blog", "see our process")
~20% incidental (in-prose mentions where the anchor reflects the surrounding sentence)

This distribution emerges naturally from good editorial writing. It rarely emerges from mass-produced internal-link automation.

7. Crawl Depth

Crawl depth is the number of clicks from the homepage to a given page. It is one of the strongest predictors of which pages Google indexes and ranks.

7.1 Targets

Site size	Maximum acceptable crawl depth
Small (under 100 pages)	3 clicks
Medium (100-1,000 pages)	4 clicks
Large (1,000-10,000 pages)	5 clicks
Massive (10,000+ pages)	6 clicks (with strong sitemap support)

Pages buried deeper rarely accumulate link equity, rarely get crawled frequently, and rarely rank.

7.2 Crawl Depth vs URL Path Depth

These are different. URL path depth (/a/b/c/d/page/ = depth 5) is unrelated to crawl depth (clicks from homepage). A page at /a/b/c/d/page/ can be crawl-depth 2 if linked from the homepage. A page at /page/ can be crawl-depth 6 if buried behind paginated archives.

Optimize for crawl depth. URL depth doesn't matter to crawlers.

7.3 Reducing Crawl Depth

Common pages buried too deep:

Old blog posts — accessible only via paginated archives at /page/2/, /page/3/, etc.
Product variants — buried under category → subcategory → product → variant
Deep category pages — buried under multi-level taxonomies
Tag archives — typically dead ends

Fixes:

Add hub pages that link directly to important deep content
Create "Best of" / "Most popular" sections on the homepage or category pages
Link from new content to high-value old content
Build cluster hubs that surface deep content
Use breadcrumbs (counts toward crawl depth from any breadcrumb-equipped page)

8. Orphan Pages

An orphan page is one with zero internal links pointing to it. Orphans:

Do not get crawled (or are crawled rarely)
Do not accumulate ranking signals
Often do not rank at all

8.1 Detection

Screaming Frog method:

Crawl the site
Crawl Analysis → Configure → enable "Crawl Analysis"
Run Crawl Analysis after main crawl completes
Reports → Orphan Pages

Sitebulb method: Auto-detects in standard reports.

Ahrefs / Semrush: Site audit reports orphans.

XML sitemap cross-reference: Compare sitemap URLs against URLs found via crawl. Difference set = orphans.

8.2 Resolution

For each orphan, decide:

Should this page exist? If not, 410 it.
If yes, where should it be linked from? Identify the natural parent in the site structure.
Add at least 3 inbound internal links before considering the orphan resolved.

8.3 Prevention

Editorial workflow: never publish a page without identifying at least 2-3 places to link to it from.
Hub-and-spoke discipline: every spoke is added to its hub when published.
Internal-linking review at publish: spend 5 minutes after every publish placing inbound links.

9. The Link Equity Lens

Link equity (informally "link juice") is the ranking-signal capital a page accumulates from internal and external links. Internal linking redistributes equity within the site.

9.1 PageRank Distribution Logic (Conceptual)

Every page has some equity. It distributes equity to all the pages it links to (divided by the number of outgoing links). The pages that receive the most equity rank best.

Implications:

The homepage has the most equity (highest external inbound).
Every link from the homepage divides its equity by the number of outbound links.
Hub pages accumulate equity by being linked from many sources within the site.
A page with many outbound links passes less equity per link.

9.2 The 100-Link Heuristic

Google indicated decades ago that 100 links per page was a soft maximum. The modern reality: there is no hard limit, but pages with 200+ outbound links pass diluted equity.

For a typical content page, target:

3-7 contextual outbound links to other site pages
Plus navigation links (header, footer, breadcrumbs)
Plus footer links

A page with 50+ outbound links should be questioned.

9.3 nofollow on Internal Links

Don't nofollow internal links unless there's a specific reason (e.g., blocking infinite-spawn faceted URLs from crawl). Old SEO advice to nofollow login or registration links is outdated — Google handles those fine without intervention.

9.4 Strategic Equity Concentration

Identify the 5-10 pages on the site that should rank highest (commercial pages, top-converting pages, hub pages). For these, intentionally:

Link from the homepage prominently
Link from every related blog post
Link from major content hubs
Use varied descriptive anchor text

Equity flow is editable through linking decisions.

10. Navigation Linking

The header, footer, and sidebar are the "navigation layer" — links that appear on every page (or every page in a section).

10.1 Header Navigation

Should contain links to:

Top-level commercial pages (Services, Pricing, Contact)
Top-level content hubs (Blog, Resources)
The single highest-priority CTA

Should NOT contain:

Every section the site has (mega-menus only when truly needed)
Promotional / temporary content
Deep pages that should rank organically (concentrating equity on every page is wasted)

10.2 Footer Navigation

A natural place for:

Sitemap-style links to important pages
Trust signals (about, contact, privacy, terms)
Service pages organized logically
Brand and credential links

The footer "supplies" link equity to a wider page set than the header. Use this deliberately.

10.3 Mega-Menus

Mega-menus (multi-column dropdowns with dozens of links) work well for ecommerce and large content sites — but the link count from every page is significant. For smaller sites, mega-menus dilute rather than help.

10.4 Breadcrumbs

Breadcrumbs add internal links (parent and grandparent pages) to every non-homepage. They:

Reduce crawl depth (every breadcrumb-enabled page is closer to root)
Add BreadcrumbList schema (cross-reference: framework-schema.md)
Improve user navigation
Display in SERPs as a navigation aid

Implement on every non-homepage. Always.

11. Contextual Linking

Contextual links are in-prose links within editorial content. They are the strongest internal links because:

Surrounding content reinforces the topical signal
Anchor text is naturally varied
They appear in the part of the page Google weighs most heavily

11.1 The Editorial Discipline

Every editorial publish should include 3-5 contextual links to other pages on the site. These should appear:

Once in the introduction (link forward to related topic)
1-2 times in the body (link to specific related sub-topics)
Once in the conclusion (link to the next logical step)

This is not link manipulation. This is good editorial practice.

11.2 The "Updated Old Posts" Pattern

When publishing new content:

Identify 3-5 old posts that should now reference the new content.
Add contextual links from those posts to the new one.
Update the old posts' dateModified.

This is one of the highest-ROI SEO activities. Costs 15 minutes per publish; compounds across the site.

11.3 The "Linked Mentions" Audit

Spot-check old content quarterly. For every brand, product, or topic mention in old posts, verify it links to the appropriate destination page. Mentions without links are wasted internal-linking opportunities.

12. Faceted Navigation

Faceted navigation is the filter/sort UI common on ecommerce and listing sites. It generates URLs combinatorially:

/category/?color=red&size=m&brand=acme

12.1 The Crawl Budget Problem

A faceted system with 5 facets and 5 options each generates 5^5 = 3,125 URL variations. With 10 facets, the count explodes. Crawlers can spend their entire budget on faceted URLs.

12.2 Strategies

Block facet parameters in robots.txt:

Disallow: /*?color=
Disallow: /*?size=
Disallow: /*?sort=

Canonical to parameterless version:

Each faceted URL canonicals to the unfiltered category page.

noindex on facet combinations:

<meta name="robots" content="noindex, follow"> on faceted URLs. They get crawled but not indexed.

Whitelist facet combinations that should rank:

Some facet combinations are valuable landing pages ("red running shoes"). Whitelist these as canonical, indexable, and present in the sitemap. Block the rest.

12.3 Internal Linking with Facets

Faceted URLs should not be linked from elsewhere on the site (don't pass equity into pages you don't index).
Whitelisted facet pages get treated as normal landing pages — link to them from category pages.

Cross-reference: framework-ecommerceseo.md.

13. Pagination

Paginated archives (/page/2/, /page/3/) need careful handling.

13.1 The rel=next/prev Pattern (Deprecated)

Google deprecated rel=next/prev as a ranking signal in 2019. The link tags can still be present but Google ignores them.

13.2 Modern Pagination Patterns

Pattern 1: Self-canonical paginated pages

Every paginated page self-canonicals (page 2 canonicals to itself). All paginated pages may be indexed. Best when each page has substantively different content.

Pattern 2: Canonical to page 1

Page 2, 3, 4 canonical to page 1. Only page 1 is indexed. Best when paginated pages are mostly listing pagination with no unique value.

Pattern 3: noindex paginated pages

Page 2+ are noindex,follow. They pass internal links but don't appear in search. Best when you want crawl access but no SERP presence.

13.3 Internal Linking with Pagination

Provide direct links to important deep content from elsewhere on the site rather than relying on pagination as the only access path.
For long archives, add "Browse by year" or "Browse by category" overlays that link directly to specific posts without pagination.
Don't rely on infinite-scroll-only patterns; ensure crawler can reach all content via traditional links.

14. Linking Hygiene

14.1 Broken Links

Internal 4xx links waste crawl budget, frustrate users, and signal site neglect. Audit:

Screaming Frog → Internal → Status code filter for 4xx
Sitebulb → Internal Links report
Ahrefs Site Audit → Broken Internal Links report

Fix:

Update the link to point to the new canonical URL
301-redirect the broken target if it should still exist
410 the broken target if it shouldn't

14.2 Redirect Chains in Internal Links

An internal link pointing to a URL that 301-redirects: the link should be updated to point to the final destination directly. Why:

Saves crawler an extra hop
Eliminates dependency on the 301 staying in place
Marginally improves user perceived performance

Find with Screaming Frog → Redirect chain report.

14.3 Cross-Domain Internal Links

Sites that span multiple domains (multibrand portfolios, microsite networks) treat cross-domain links as external for SEO purposes. There is no internal link equity flow between separate domains, even if they're owned by the same entity.

For multibrand operations, decide deliberately:

Single domain with subfolders (/brand-a/, /brand-b/) — true internal linking, shared equity
Subdomains (brand-a.example.com, brand-b.example.com) — partially shared, weaker
Separate domains — no internal-link equity flow

Cross-reference: framework-multibrand.md (when built).

15. Audit Mode

#	Criterion	Pass/Fail
IL1	Site has documented topical taxonomy / cluster strategy
IL2	Hub pages identified for each major topic
IL3	Each spoke page links back to its hub at least twice
IL4	Each hub page links to all its spokes
IL5	Cross-cluster links used sparingly and topically
IL6	Crawl depth report shows zero pages over depth 3 (small sites) / 5 (large sites)
IL7	Zero orphan pages detected (Screaming Frog Crawl Analysis)
IL8	Anchor text varies naturally; no exact-match overuse
IL9	Anchor text contains zero "click here" / "read more" without context
IL10	Breadcrumbs implemented on every non-homepage with BreadcrumbList schema
IL11	Header navigation focused on top commercial + content hubs only
IL12	Footer provides supplemental link layer to important pages
IL13	Average outbound internal links per content page between 5 and 30
IL14	Zero broken internal links (4xx)
IL15	Zero internal links pointing to redirect chains
IL16	Faceted navigation strategy documented (block / canonical / whitelist)
IL17	Pagination strategy documented (self-canonical / canonical-to-1 / noindex)
IL18	Top 10 commercial pages each have 20+ inbound internal links
IL19	Top traffic pages link to conversion pages contextually
IL20	Editorial workflow includes inbound-link placement step
IL21	"Updated old posts" pattern practiced when new content publishes
IL22	nofollow not used on internal links (no exceptions, or documented exceptions)
IL23	Cluster gap analysis completed in last 90 days
IL24	Internal link audit run in last 30 days
IL25	Cross-domain links treated correctly per multibrand strategy

Score: 25. World-class: 23+/25.

16. Common Mistakes

No clear hub pages. Every page is at the same level; nothing accumulates topical authority.
Spokes that don't link back to the hub. Cluster signal lost.
"Click here" / "read more" anchors. Wastes the topical signal on every internal link.
Orphan pages. Indexed but invisible to the link graph.
Crawl depth over 5. Important pages buried.
Broken internal links unfixed. Cumulative crawl budget waste.
Internal links to redirect chains. Same — extra hop.
Mega-menu on a small site. Diluting equity on every page.
Faceted URLs without robots / canonical strategy. Crawl budget exploded by combinatorial parameters.
No breadcrumbs. Free internal-linking layer ignored.
Editorial publishes new content without inbound link placement. Page launches as orphan.
Old content never updated. Anchors mention things that should now link to newer pages.
Anchor text identical on every internal link to a page. Looks manipulated; sometimes triggers algorithmic suppression.
Footer linking to every page on the site. Equity diluted; signals devalued.
Treating cross-domain links as internal. Equity does not flow.
Infinite-scroll archives with no traditional link path. Pages discoverable only by JS-rendered scroll events.
JavaScript-only navigation. Some crawlers see it; others don't.
Cross-cluster spoke-to-spoke linking everywhere. Weakens cluster boundaries.

17. Maintenance

Weekly:

Spot-check newly published content for inbound and outbound links
Verify new content added to relevant hub page

Monthly:

Sitewide broken-link scan (Screaming Frog or alternative)
Orphan-page report review
New publish "Updated old posts" pass
Anchor-text spot audit on top 10 pages

Quarterly:

Comprehensive internal-link audit
Crawl depth review (Sitebulb)
Cluster gap analysis
Hub page link inventory refresh
Faceted navigation audit (if applicable)
Pagination strategy review

Annually:

Full link graph visualization (Gephi / yEd)
Cluster structure review against keyword research
Site architecture review (do hubs still match priorities?)
Multibrand cross-domain linking review (if applicable)

18. Companion Documents

framework-keywordresearch.md — Topic clusters depend on keyword research
framework-schema.md — BreadcrumbList implementation
framework-technicalseo.md — Crawl depth, faceted URL handling, pagination
framework-ecommerceseo.md — Faceted navigation deep dive
framework-newsseo.md — Editorial linking patterns
framework-uxseo.md — Navigation UX patterns supporting SEO
framework-hcs.md — Topical depth as a Helpful Content signal
framework-eeat.md — Topical authority as an Expertise signal
framework-pageexperience.md — Navigation tap-target sizing

Document version: 1.0
Last updated: 2026-05-05
Owner: Joseph W. Anady — ThatDeveloperGuy — SDVOSB

Source

Canonical: https://www.thatdevpro.com/insights/framework-internallinking/

ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Engine Optimization service · Contact

Mobile SEO + mobile-first indexing

Joseph Anady — Sun, 24 May 2026 02:32:57 +0000

Originally published at thatdevpro.com. Part of ThatDevPro's open SEO + AI framework library. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.

Mobile First Indexing, Mobile Core Web Vitals, Touch Patterns, Foldable Devices, Apple Intelligence on iOS 19, Mobile Crawler Behavior, and Self Hosted Mobile Testing

A comprehensive installation and audit reference for mobile SEO in 2026. Mobile is no longer a special case or a secondary surface. Per StatCounter Global Stats April 2026 data (rolling 30 day sample across 3.1 million tracked sites), mobile generates 67.4 percent of global web traffic, tablets contribute another 1.9 percent, and desktop has dropped to 30.7 percent. AI search assistants on mobile (ChatGPT iOS app, Perplexity iOS and Android, Google AI Mode mobile interface, Apple Intelligence Spotlight Web) are launched from mobile devices 82.1 percent of the time per Similarweb Q1 2026 mobile app analytics. Mobile is the primary surface for both classic search and AI search. Dual purpose: installation manual and audit document.

Cross stack implementation note: the code samples in this framework are written in plain HTML for clarity. For React, Vue, Svelte, Next.js, Nuxt, SvelteKit, Astro, Hugo, 11ty, Remix, WordPress, Shopify, and Webflow equivalents of every pattern below, see framework-cross-stack-implementation.md. For pure client rendered SPAs (no SSR/SSG) see framework-react.md. For Tailwind specific concerns (purge, dynamic classes, dark mode CLS, focus accessibility) see framework-tailwind.md.

1. Document Purpose

This is the canonical 2026 reference for mobile SEO. Where framework-pageexperience.md covers Core Web Vitals as a cross device discipline, this document covers the mobile specific layer: foldable posture queries, iOS 19 Apple Intelligence registration, Googlebot Smartphone behavior in server logs, mobile schema cards, and the touch patterns that distinguish a thumb workable site from a desktop port. Where framework-localseo.md covers local search business, this document covers the mobile click to call, click to map, click to text patterns local search depends on. Where framework-aso.md covers App Store and Play Store optimization, this document covers the mobile web surface and the seams where mobile web meets native (App Intents, App Links, Universal Links, Smart Banners).

Mobile is not a special case in 2026. The conversation has shifted from "make sure the desktop site works on mobile" to "design for mobile first and progressively enhance for desktop". From "mobile Core Web Vitals must pass" to "mobile Core Web Vitals must pass under realistic field conditions including 5G uplink congestion, foldable layout changes, and AI assistant rendering paths".

What is unchanged: responsive design remains the canonical pattern. Separate m.example.com sites are a discontinued pattern. AMP is obsolete. Mobile parity with desktop is a hard requirement for indexation. Touch targets must be tap workable.

What is new in 2026: container queries replace media queries at the component level. Foldable devices require CSS posture queries (device-posture: folded and device-posture: continuous). Apple Intelligence on iOS 19 (shipped September 2025, point release 19.2 January 2026) indexes mobile web content through Spotlight Web and surfaces it through Siri. App Intents for app deep linking benefit mobile web sites with companion apps. Googlebot Smartphone has been the only Googlebot user agent for fresh crawls since 2023. AI crawlers (OAI SearchBot, PerplexityBot, ClaudeBot, Bingbot in AI mode) are all mobile aware.

1.1 Three Operating Modes

Mode A, Install Mode. Build mobile first infrastructure on a new or existing site. Follow Sections 2 through 14 in order.

Mode B, Audit Mode. Evaluate an existing site for mobile SEO posture. Skip to Section 14.

Mode C, Hybrid Mode. Audit first, then install for failing items.

1.2 Required Tools

Google Search Console URL Inspection tool (the canonical replacement for the deprecated Mobile Friendly Test)
Chrome DevTools Device Mode for lab simulation
Playwright with mobile emulation profiles (devices['iPhone 15 Pro'], devices['Pixel 8'], devices['Galaxy S24 Ultra'])
Real device pool: at minimum one current iPhone, one current Pixel or Galaxy, one foldable, one tablet
A self hosted Selenium Grid for headless cross device testing on a Debian or Ubuntu host
Server log access for crawler verification (nginx access.log or equivalent)
A self hosted RUM endpoint for field data collection (web-vitals JS library posting to your own nginx logging endpoint)

1.3 Relationship to Neighboring Frameworks

Concern	Framework
Core Web Vitals across devices	framework-pageexperience.md
HTTP/3, nginx tuning, TLS, crawler access	framework-technicalseo.md
Touch and screen reader accessibility (WCAG 2.2)	framework-accessibility.md
App Store and Play Store optimization	framework-aso.md
Local pack, Apple Maps, Google Maps cards	framework-localseo.md
UX foundations, IA, task flow	framework-uxseo.md
LocalBusiness, MobileApplication, SpeakableSpecification	framework-schema.md
Siri, Apple Intelligence, ChatGPT Voice, Google Assistant	framework-voicesearch.md
AI citation surfaces (ChatGPT, Claude, Perplexity, Copilot)	framework-aicitations.md
Google AI Overviews and AI Mode	framework-aioverviews.md
Image search, lens search, mobile camera search	framework-multimodalsearch.md

2. Client Variables Intake

# MOBILE SEO FRAMEWORK CLIENT VARIABLES

# --- Site Identity ---
business_name: ""
primary_domain: ""
nginx_host_path: ""                    # /var/www/sites/[domain]/
companion_app_ios_bundle_id: ""
companion_app_android_package_id: ""

# --- Mobile Traffic Baseline ---
mobile_traffic_percent_ga4: 0          # GA4 last 90 days
mobile_organic_clicks_last_28_days: 0  # GSC mobile filter
mobile_organic_impressions_last_28_days: 0

# --- Mobile Core Web Vitals Field Data ---
mobile_lcp_p75_ms: 0
mobile_inp_p75_ms: 0
mobile_cls_p75: 0
mobile_ttfb_p75_ms: 0

# --- Responsive Posture ---
viewport_meta_present: false
viewport_meta_user_scalable_disabled: false   # red flag if true
responsive_pattern: ""                 # responsive | separate_m_dot | dynamic_serving | amp_paired
container_queries_in_use: false
posture_queries_in_use: false
breakpoints_in_css: []                 # [320, 480, 768, 1024, 1280, 1920]

# --- Touch Posture ---
minimum_tap_target_px: 0
pinch_zoom_enabled: false
hover_only_interactions_count: 0

# --- Mobile First Indexing Status ---
gsc_url_inspection_crawled_as: ""      # "Googlebot smartphone" expected
mobile_parity_with_desktop: false
mobile_schema_parity_with_desktop: false

# --- AMP Posture ---
amp_pages_present: false
amp_sunset_planned: true               # default; AMP is obsolete

# --- Apple Intelligence Posture ---
ios_app_intents_registered: false
applinks_apple_app_site_association_present: false
apple_smart_app_banner_present: false

# --- Android App Linking Posture ---
android_app_links_assetlinks_json_present: false
android_intent_filters_configured: false

# --- Foldable Device Posture ---
foldable_design_considered: false
safe_area_inset_css_in_use: false

# --- Self Hosted Mobile Testing ---
playwright_mobile_suite_present: false
selenium_grid_self_hosted: false
real_device_pool_size: 0

3. Mobile First Indexing Status 2026

3.1 What Mobile First Indexing Means in 2026

Google completed the migration to mobile first indexing for the entire web by October 2023. There is no longer a "switching schedule". Every site Googlebot crawls is crawled primarily as Googlebot Smartphone. The desktop user agent persists for legacy verification only.

Operationally:

Mobile rendering is the canonical rendering for indexation.
Content, schema, and internal links present only on desktop do not contribute to ranking or discovery.
Mobile Core Web Vitals are the only Core Web Vitals that affect ranking.
Mobile usability issues block indexation, not just rank.

3.2 Verifying Current Crawl Perspective

The Mobile Friendly Test tool at search.google.com/test/mobile-friendly was deprecated in late 2024. Its functionality has been folded into Google Search Console URL Inspection. To verify how Google currently crawls a URL:

Open Google Search Console for the property.
Enter the URL in the top URL inspection bar.
Wait for the inspection result.
Open the "Coverage" section.
Read the "Crawled as" field. Expected value: "Googlebot smartphone".
If the value reads "Googlebot" without the "smartphone" qualifier, the URL is on the legacy desktop crawl path. This is rare in 2026 and indicates either a mobile rendering failure or a site explicitly excluded from mobile first indexing.
Click "Test live URL" to confirm the current rendering reflects the live mobile state.
Open the "Screenshot" tab to verify the rendered mobile viewport matches intent.
Open the "More info" > "JavaScript console messages" to verify no JavaScript errors block mobile rendering.

3.3 Legacy Desktop Only Pages

Pattern	Impact	Fix
m.example.com returns desktop HTML	Googlebot Smartphone retrieves desktop content	Migrate to responsive; 301 the m subdomain to the apex
Dynamic serving returns desktop to mobile UA	Mobile rendering broken; indexation incomplete	Migrate to responsive; remove user agent switching
AMP only mobile path	Mobile depends on deprecated runtime	Sunset AMP; serve responsive HTML on a single canonical URL
Desktop only intermediate redirect	Indexation diverges from user experience	Remove redirect; serve full content on canonical URL
Geo blocked mobile carrier routing	Googlebot Smartphone routes through blocked ranges	Whitelist Googlebot IP ranges from the published list

3.4 Parity Requirements

Mobile first indexing demands strict parity between mobile and desktop renderings:

Primary heading, body copy, and content tokens present in both.
Schema markup present in both (the most common parity failure: schema injected via desktop only GTM, or schema rendered into a sidebar with display: none on mobile).
Internal links present in both. Mobile navigation must contain the same destination set as desktop megamenus.
Images present in both with the same alt text.
Canonical tag, Open Graph, meta description, and hreflang annotations identical.

Audit by fetching the URL twice with the Googlebot Smartphone and Googlebot Desktop user agents and diffing:

GBS="Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (compatible; Googlebot/2.1)"
GBD="Mozilla/5.0 AppleWebKit/537.36 (compatible; Googlebot/2.1)"

curl -s -A "$GBS" "https://example.com/page" > /tmp/mobile.html
curl -s -A "$GBD" "https://example.com/page" > /tmp/desktop.html

diff <(grep -oE '<h[1-6][^>]*>[^<]*</h[1-6]>' /tmp/mobile.html) \
     <(grep -oE '<h[1-6][^>]*>[^<]*</h[1-6]>' /tmp/desktop.html)

4. Responsive Design Patterns

4.1 The Canonical Pattern

Responsive design with a fluid grid, mobile first CSS, and progressive enhancement remains the canonical pattern. A single HTML document with a single set of URLs serves every viewport from a 320 pixel narrow phone to a 1920 pixel wide desktop monitor and beyond.

The opening rule, present on every HTML document:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

The viewport-fit=cover directive opts the page into the iOS Safari and modern Android safe area inset model, which matters for foldables and for devices with notches or punch hole cameras. Without it, the layout sits inside a letterboxed inner viewport on devices with non rectangular screens.

Do not set user-scalable=no. Do not set maximum-scale=1. Both block pinch zoom, which is an accessibility requirement under WCAG 2.2 SC 1.4.4 Resize Text. Modern Lighthouse audits flag both as accessibility failures.

4.2 Mobile First CSS

Mobile first CSS means the base styles target the smallest viewport (320 pixels wide) and media queries progressively enhance for larger viewports:

/* Base: 320px and up, mobile portrait */
.container { padding: 1rem; }
.button {
  display: block;
  width: 100%;
  padding: 1rem;
  font-size: 1rem;
  min-height: 48px;
}
.nav { flex-direction: column; }

@media (min-width: 480px) { .container { padding: 1.25rem; } }

@media (min-width: 768px) {
  .container { padding: 2rem; max-width: 720px; margin: 0 auto; }
  .button { display: inline-flex; width: auto; padding: 0.75rem 2rem; }
  .nav { flex-direction: row; }
}

@media (min-width: 1024px) { .container { max-width: 960px; } }
@media (min-width: 1280px) { .container { max-width: 1200px; } }
@media (min-width: 1920px) { .container { max-width: 1440px; } }

Mobile loads the smallest stylesheet first. Larger viewports load the same base plus the overrides for their width. On a 320 pixel phone the browser parses zero media query bodies. On a 1920 pixel monitor it parses all five.

4.3 Container Queries

Container queries became broadly supported in 2024 and are the default 2026 pattern for component level responsive behavior. Where media queries respond to viewport width, container queries respond to the container the component is rendered inside, which lets a single card component adapt correctly whether it lives in a 320 pixel sidebar or a 960 pixel main column.

.card-grid {
  container-type: inline-size;
  container-name: card-grid;
}

.card {
  display: flex;
  flex-direction: column;
}

@container card-grid (min-width: 480px) {
  .card {
    flex-direction: row;
    align-items: center;
  }

  .card-image {
    width: 33%;
  }

  .card-body {
    width: 67%;
    padding-left: 1rem;
  }
}

Component reuse becomes correct: the same card renders narrow inside a narrow container and wide inside a wide container, regardless of viewport size. Media queries continue to handle page level layout. Container queries handle component level layout.

4.4 Common Responsive Failures

Failure	Cause	Fix
Horizontal scroll	Element wider than viewport (table, iframe, code block, unsized image)	`img, video, iframe, table, pre { max-width: 100%; height: auto; }`
Fixed pixel widths	Widths in px rather than %, rem, or container units	Use `max-width` and `clamp()` patterns
Text under 16px	Body font 14px or smaller	iOS Safari auto zooms on form focus and triggers CLS; minimum 16px
Hover only interactions	Menu reveal requires `:hover`	Pair with `:focus` and tap toggle; or `<details>`
Break at 360 to 375 px	iPhone SE (375), folded Z Fold cover (~360)	Test at 320, 360, 375 viewports
Intrusive interstitial	Modal dominating mobile first paint	Cookie or signup overlays under 30 percent viewport on mobile, or gesture triggered (Google Mobile Interstitial penalty active since 2017)
Popup close target too small	Close X under 48 by 48	48 by 48 minimum on every dismiss control

5. Mobile Core Web Vitals

5.1 The Thresholds in 2026

The Core Web Vitals thresholds remain unchanged since the INP migration in March 2024:

Metric	Good	Needs Improvement	Poor
LCP (Largest Contentful Paint)	<= 2.5 s	2.5 to 4.0 s	> 4.0 s
INP (Interaction to Next Paint)	<= 200 ms	200 to 500 ms	> 500 ms
CLS (Cumulative Layout Shift)	<= 0.1	0.1 to 0.25	> 0.25

Thresholds are measured at the 75th percentile of real user data for mobile and desktop separately. Google ranks mobile vitals against mobile users only. A page must clear 75 percent for the "Good" classification.

5.2 Why Mobile Vitals Are Harder Than Desktop Vitals

The mobile field versus lab data divergence is wider than desktop's:

Network variance. 5G uplink TTFB ranges from 80 ms (cell line of sight) to 2400 ms (cell handoff). Desktop ethernet rarely varies by more than 50 ms.
Device variance. Lighthouse's "mid range mobile device" simulation is a Moto G4 era proxy. The actual 2026 mid range device is a $200 to $400 phone with thermal throttling. Lab measurements underestimate real INP by 40 to 80 percent on lower end devices, per HTTPArchive 2024 web performance report (1.3 million URLs sampled).
HTTP/3 effects. Per HTTPArchive 2024, sites serving HTTP/3 see a 200 to 400 ms p75 mobile TTFB improvement versus HTTP/2 on the same hosting.
Battery and thermal state. A phone in low power mode runs the CPU at reduced clock speed. Lighthouse lab runs do not model this.

Lab data is a sanity check, not a pass. Field data from CrUX or self hosted RUM is the ground truth.

5.3 Mobile LCP Levers

Target: under 2.5 seconds at p75 mobile.

Lever	Target	Fix
TTFB	Under 600 ms p75 mobile	Serve from same continent; cache static HTML at nginx; avoid client side rendering of hero; HTTP/3 enabled
Hero image	Under 100 KB compressed	AVIF or WebP; sized to viewport breakpoint (not a 4000 pixel image on a 375 pixel viewport); `fetchpriority="high"`; never lazy loaded
Font loading	Swap before LCP	`font-display: swap`; preload critical weights; `size-adjust` to match fallback metrics
Render blocking	Zero blocking CSS above the fold	Inline critical CSS; defer non critical via `media="print" onload` pattern; defer JS unless it generates above the fold content
Third party scripts	Zero in critical path	GA4, GTM, chat widgets, social embeds with `defer` or after `onload`; self host fonts where license permits

5.4 Mobile INP Levers

Target: under 200 milliseconds at p75 mobile.

Lever	Target	Fix
JS budget	Under 250 KB executed before interaction	Code split routes; tree shake; audit with `webpack-bundle-analyzer`
Long tasks	No task over 50 ms on main thread	Break into chunks with `scheduler.yield()` or `setTimeout(0)`; move heavy work to a Web Worker
Click handlers	Return control within 50 ms	Update UI optimistically; reconcile asynchronously; avoid layout thrash (reading `offsetHeight` after writing style)
React re-render scope	No tree wide re-render on state change	`React.memo`; `useCallback` for handlers passed to memoized children; virtualize long lists with `react-window`
Third party tag execution	Not blocking interaction	`type="module"` or `defer`; sandbox heavy widgets in a same origin iframe

5.5 Mobile CLS Levers

Target: under 0.1 at p75 mobile.

Lever	Rule	Pattern
Image dimensions	Every image declares width and height (or `aspect-ratio`)	`<img src="/img/hero.avif" width="1200" height="800" alt="..." fetchpriority="high">`
Embed dimensions	Every iframe declares dimensions or aspect-ratio	`.video-wrapper { aspect-ratio: 16 / 9; }`
Font swap shift	Fallback font metrics match loaded font	`size-adjust`, `ascent-override`, `descent-override` on `@font-face`
Cookie banner shift	Banner does not push content	Fixed overlay at bottom; no document flow space reserved
Late loaded above fold content	No content injected above existing content after first paint	Reserve placeholder space; replace in place

6. Touch and Interaction Patterns

6.1 Tap Target Sizing

WCAG 2.2 SC 2.5.8 Target Size (Minimum) became a Level AA conformance requirement in October 2023. AA minimum is 24 by 24 CSS pixels; AAA is 44 by 44. Apple HIG recommends 44 by 44 points; Google Material and Lighthouse recommend 48 by 48 dp. The practical 2026 target is 48 by 48 CSS pixels for all primary tap targets, which clears every standard and is comfortable on the average adult thumb (which contacts a ~45 by 45 pixel zone on a typical phone).

.btn,
.link-button,
nav a,
.tap-target {
  min-height: 48px;
  min-width: 48px;
  padding: 12px 20px;
  display: inline-flex;
  align-items: center;
  justify-content: center;
}

/* Tap targets must have spacing between them */
.btn + .btn {
  margin-left: 8px;
}

nav li + li {
  margin-top: 4px;
}

The 8 pixel minimum spacing matters: two adjacent buttons that are each 48 by 48 but share an edge form a 96 pixel wide pair that thumbs sometimes mis tap. Eight pixels of margin (or padding) between them ends mis tap behavior.

6.2 Thumb Zone Navigation

The thumb of the average smartphone user reaches comfortably across the bottom two thirds of a vertical phone display. Anything in the top third requires a hand shift or a thumb stretch. The 2026 pattern anchors primary navigation and primary CTAs in the bottom third of the viewport where possible.

Pattern	When	Note
Sticky CTA bar at viewport bottom	Single primary action per page (book, call, buy)	Use `position: sticky; bottom: 0` with `env(safe-area-inset-bottom)` padding; avoid blocking content
Bottom tab bar	3 to 5 primary destinations	Always thumb reachable; familiar app model
Hamburger that opens a bottom drawer	Many destinations	Maintains hamburger discoverability while putting menu items in thumb zone
Native pull to refresh	Listing pages, feeds	Do not override with custom scroll handlers

6.3 Gestures and Accessibility

Gesture interactions (swipe, pinch, long press, double tap) must always be paired with a non gesture alternative. WCAG 2.2 SC 2.5.1 Pointer Gestures requires any function operated through a multipoint or path based gesture be operable through a single point activation as well.

Gesture	Alternative Required
Swipe to advance carousel	Previous and next buttons; dot indicator
Pinch to zoom image	Tap to open full screen with zoom button (never disable native pinch zoom)
Long press context menu	Visible three dot menu button
Double tap to like	Single tap also likes

6.4 Visual Feedback

Every tap must produce visible feedback within 100 milliseconds. The most common 2026 failure is over reliance on JavaScript state for visual feedback: the button waits for the click handler to complete and then updates, producing a 200 to 600 millisecond gap with no feedback. The user taps again, then a third time, then the page processes all three taps and the user has triggered the action three times.

.btn {
  transition: transform 0.05s ease, background-color 0.1s ease;
}

.btn:active {
  transform: scale(0.97);
  background-color: var(--brand-dark);
}

.btn:focus-visible {
  outline: 2px solid var(--brand);
  outline-offset: 2px;
}

The :active state fires synchronously on touchstart; the browser repaints before the click handler runs. Users feel the response before the JavaScript has a chance to be slow.

7. Foldable Device Considerations

7.1 The Foldable Device Population in 2026

Foldable devices (Samsung Galaxy Z Fold and Z Flip, OPPO Find N, Google Pixel Fold, Honor Magic V, Xiaomi Mix Fold) have grown from 0.7 percent of global smartphone shipments in 2022 to 5.2 percent in Q1 2026 per IDC's Worldwide Quarterly Mobile Phone Tracker (March 2026 release). They are concentrated in premium audiences: foldable users index 2.4 times higher on mobile commerce conversion per Shopify's 2026 mobile commerce report (sample: 1.1 million Shopify merchants).

Three folding patterns matter:

Book fold (Galaxy Z Fold, Pixel Fold, Find N): cover ~360 to 414 pixels wide folded, ~720 to 850 pixels wide unfolded.
Clamshell fold (Galaxy Z Flip, Find N Flip): cover 360 pixels wide, internal display 720 pixels wide tall.
Tri fold (Huawei Mate X3, expected Samsung 2026): three panels with two creases, multi posture layout.

7.2 CSS Posture Queries

The CSS Device Posture API and @media (device-posture: folded) media query reached broad support across Chromium based browsers in 2024 and Safari iOS 18 in 2025. The 2026 pattern is to detect posture and layout in response:

/* Default: continuous (flat) posture */
.article-layout {
  display: block;
}

/* Folded posture: device is partially folded (laptop mode) */
@media (device-posture: folded) {
  .article-layout {
    display: grid;
    grid-template-columns: 1fr 1fr;
  }

  .article-image {
    grid-column: 1;
  }

  .article-text {
    grid-column: 2;
  }
}

Combined with viewport segments, this lets a folded device render an image on the top half panel and body text on the bottom half panel without overlapping the fold crease.

7.3 Safe Area Insets

Foldable devices, devices with notches, devices with under display cameras, and devices with rounded corners all require the safe area inset CSS environment variables:

.header {
  padding-top: env(safe-area-inset-top, 0);
}

.footer,
.bottom-nav {
  padding-bottom: env(safe-area-inset-bottom, 0);
}

.sidebar {
  padding-left: env(safe-area-inset-left, 0);
  padding-right: env(safe-area-inset-right, 0);
}

The env() fallback (second argument) is critical: devices without inset reporting return zero, and the layout reads correctly on every device.

7.4 The Dual Screen Layout Breakpoint

Unfolded book fold devices report a viewport width in the 720 to 850 pixel range. This sits exactly at the conventional tablet breakpoint. The 2026 best practice is to design the 768 pixel breakpoint with foldable layouts in mind:

@media (min-width: 768px) {
  .reading-pane {
    display: grid;
    grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
    gap: 2rem;
  }
}

/* Pair with posture query for explicit dual screen layout */
@media (min-width: 768px) and (device-posture: folded) {
  .reading-pane {
    gap: 4rem; /* extra gap to clear the fold crease */
  }
}

8. Apple Intelligence on iOS 19

8.1 What Apple Intelligence Does on iOS 19

Apple Intelligence shipped on iOS 18 in fall 2024 and reached production maturity with iOS 19 in fall 2025 (point release 19.2 January 2026). Three touchpoints matter for mobile SEO:

Spotlight Web indexes web content on Apple servers and surfaces results in the Spotlight search bar (pull down on Home Screen) and Safari's address bar suggestions. Spotlight Web is populated by Applebot and Applebot-Extended.
Siri routes general knowledge questions to ChatGPT (via the user opt in OpenAI integration shipped with iOS 18.2) or to Apple's own foundation model. When Siri answers from a web source it cites the source and offers an "Open in Safari" affordance.
App Intents let an app expose typed actions that Siri, Spotlight, and the Apple Intelligence panel can invoke. For a mobile website with a companion app, registering App Intents that map to web URLs lets Apple Intelligence deep link directly into the app from Spotlight or Siri, falling back to the web page if the app is not installed.

8.2 Registering App Intents

App Intents are declared in Swift on iOS. The mobile SEO relevant piece is the URL mapping: an App Intent that performs a "show product" action exposes both an app URL scheme and an https URL on the marketing site. Apple Intelligence prefers the app URL if the app is installed and falls back to the web URL otherwise.

Universal Links configuration requires a single file at /.well-known/apple-app-site-association:

{
  "applinks": {
    "apps": [],
    "details": [{
      "appIDs": ["TEAMID.com.example.YourApp"],
      "components": [
        { "/": "/products/*", "comment": "Product detail pages" },
        { "/": "/articles/*", "comment": "Article pages" },
        { "/": "/contact", "comment": "Contact page" }
      ]
    }]
  },
  "webcredentials": { "apps": ["TEAMID.com.example.YourApp"] }
}

Served from the apex domain over HTTPS with Content-Type: application/json and no file extension:

location = /.well-known/apple-app-site-association {
  default_type application/json;
  alias /var/www/sites/example.com/.well-known/apple-app-site-association;
}

When a user taps https://example.com/products/widget from Siri, Spotlight, Messages, or Mail, iOS checks the apple-app-site-association file, sees the /products/* pattern, and opens the app. If the app is not installed, Safari opens the URL.

8.3 Applebot Extended for Apple Intelligence Training

Apple's training crawler is Applebot-Extended, distinct from Applebot (Siri and Spotlight). The two have separate opt out semantics. To allow both: Allow: / under each user agent block. To opt out of training only while keeping Siri and Spotlight presence: User-agent: Applebot-Extended + Disallow: /. For most marketing sites, allow Applebot-Extended: training contributes to model awareness of your brand and content.

8.4 Smart App Banner

The Smart App Banner is the small "Open in App" banner Safari shows at the top of mobile pages when a paired iOS app exists. It is a simple meta tag:

<meta name="apple-itunes-app" content="app-id=123456789, app-argument=https://example.com/products/widget">

The app-argument value is the URL passed into the app when the user taps "Open". This lets a single web URL deep link into the corresponding app screen.

8.5 Android App Links

The Android equivalent is the assetlinks.json file served from /.well-known/assetlinks.json:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.yourapp",
      "sha256_cert_fingerprints": ["..."]
    }
  }
]

nginx:

location = /.well-known/assetlinks.json {
  default_type application/json;
  alias /var/www/sites/example.com/.well-known/assetlinks.json;
}

Combined with <intent-filter> declarations in the Android manifest, this enables App Links: tapping a web URL on an Android device with the app installed opens the app directly.

9. AMP Status 2026

9.1 AMP Is Obsolete

Google dropped the AMP requirement for the Top Stories carousel in June 2021. Google retired the AMP page experience signal in 2022. AMP cache hosting on google.com/amp/s/... URLs has been deprioritized since 2023. The AMP project has not received material updates since 2023.

In 2026, AMP is a finished pattern. New sites should not implement AMP. Existing AMP pages should be sunset by 301 redirect to the canonical responsive version. Mobile responsive pages built to the patterns in this framework outperform AMP on Core Web Vitals and earn the same Top Stories eligibility without the AMP runtime.

9.2 Sunsetting AMP

For sites still serving AMP pages, the sunset procedure:

Inventory. List all AMP URLs from GSC /amp/ paths, sitemap, and internal links with rel="amphtml".
Redirect. 301 redirect each AMP URL to its canonical responsive URL. nginx: location ~ ^/amp/(.*)$ { return 301 /$1; }.
Remove <link rel="amphtml"> tags from canonical pages.
Update sitemap.xml to remove AMP URLs; resubmit in GSC.
Request recrawl of high traffic canonical pages in GSC URL Inspection.
Decommission the runtime. Remove AMP script tags, AMP build pipelines, amp-* custom elements from the codebase.

9.3 What Replaces AMP

The 2026 stack that earns the speed and eligibility AMP once provided:

Mobile responsive HTML with the patterns in Section 4.
Mobile Core Web Vitals targets from Section 5.
HTTP/3 enabled in nginx (Section 13).
Critical CSS inlined; non critical CSS deferred.
Hero image preloaded; below the fold lazy loaded.
JavaScript deferred or async; under 250 KB executed before interaction.
News articles include Article or NewsArticle schema with datePublished, dateModified, author, headline, and image.

Top Stories eligibility no longer requires AMP. It requires the site to be a Google News approved publisher (via the Google Publisher Center) and the article to meet Top Stories quality signals.

10. Mobile Page Speed

10.1 The Above the Fold Render Budget

The 2026 mobile above the fold budget for a marketing site:

HTML document under 30 KB compressed.
Critical CSS inlined, under 14 KB inside <style>.
JavaScript executed before interaction under 250 KB compressed.
Hero image under 100 KB compressed.
Custom fonts under 50 KB total (two weights, woff2).
Total above the fold transfer under 500 KB.

The 14 KB inline CSS number derives from the initial TCP congestion window: 14 KB fits in the first round trip of a fresh TCP connection. CSS inlined inside the HTML document inside the first 14 KB renders without a second network request.

10.2 Image Optimization for Mobile

Format priority: AVIF primary, WebP fallback, JPEG (progressive) or PNG (icons) legacy fallback. Responsive images use srcset and sizes:

<img src="/img/hero-800w.avif"
     srcset="/img/hero-400w.avif 400w,
             /img/hero-800w.avif 800w,
             /img/hero-1200w.avif 1200w,
             /img/hero-1600w.avif 1600w"
     sizes="(min-width: 1024px) 1200px, 100vw"
     width="1200" height="800"
     alt="..."
     fetchpriority="high">

srcset width descriptors handle device pixel ratio automatically; avoid manual 1x and 2x suffix logic (legacy pattern). Hero images use loading="eager" (default); below the fold images use loading="lazy". Add decoding="async" to non critical images so the browser may decode off the main thread.

10.3 HTTP/3 Performance

HTTP/3 over QUIC reduces handshake round trips on lossy mobile connections. Per HTTPArchive's 2024 Web Almanac performance chapter (analysis sample: 8.9 million origins), sites serving HTTP/3 see a 200 to 400 millisecond improvement in mobile TTFB at the 75th percentile versus HTTP/2 on the same hosting. The improvement is larger on cellular connections with packet loss and smaller on wifi with low loss.

nginx 1.25 and later supports HTTP/3 natively. The configuration enables both HTTP/2 (over TCP+TLS) and HTTP/3 (over QUIC+TLS) on the same port. Section 13 walks through the configuration on Bubbles.

10.4 Lazy Loading

Native lazy loading via the loading="lazy" attribute is broadly supported across mobile browsers in 2026. It does not require a JavaScript library. The browser decides when to load based on viewport proximity heuristics.

Rules:

Hero image: never lazy load. loading="eager" (default) or omitted.
Above the fold images: never lazy load.
Below the fold images: always lazy load.
Iframes: lazy load with loading="lazy" on the <iframe> tag.
Background images set via CSS: lazy loading does not apply; the browser loads when the element is in the render tree. To lazy load CSS background images, use a JavaScript IntersectionObserver pattern.

10.5 Service Workers and Offline

Service workers cache critical assets aggressively and serve them on subsequent visits without a network round trip. For high return visit sites, service workers reduce repeat visit LCP by 800 to 1200 milliseconds at the 75th percentile.

The Workbox library ships well tested cache strategies. A typical mobile marketing site uses cache first for static assets and network first for HTML:

// sw.js
import { precacheAndRoute } from 'workbox-precaching';
import { registerRoute } from 'workbox-routing';
import { CacheFirst, NetworkFirst } from 'workbox-strategies';

precacheAndRoute(self.__WB_MANIFEST);

registerRoute(
  ({ request }) => ['style', 'script', 'font', 'image'].includes(request.destination),
  new CacheFirst({ cacheName: 'static-assets' })
);

registerRoute(
  ({ request }) => request.mode === 'navigate',
  new NetworkFirst({ cacheName: 'pages' })
);

Service workers must be served from HTTPS. Scope is constrained to the path they are served from (/sw.js controls the entire origin; /app/sw.js controls only /app/).

11. Mobile Crawler Behavior

11.1 The Crawler User Agents in 2026

Crawler	UA token	Role	DNS verification
Googlebot Smartphone	`Googlebot/2.1` + `Mobile`	Primary Google mobile first indexing crawler	reverse DNS to googlebot.com or google.com
Bingbot Mobile	`bingbot/2.0` + `Mobile`	Bing search and Copilot	reverse DNS to search.msn.com
Applebot	`Applebot/`	Siri and Spotlight Web	reverse DNS to applebot.apple.com
Applebot-Extended	`Applebot-Extended`	Apple Intelligence training	same as Applebot
OAI-SearchBot	`OAI-SearchBot/1.0`	OpenAI search index (ChatGPT search)	n/a
ChatGPT-User	`ChatGPT-User/1.0`	ChatGPT real time fetch (user initiated)	n/a
GPTBot	`GPTBot`	OpenAI training	n/a
PerplexityBot	`PerplexityBot/1.0`	Perplexity index	n/a
Perplexity-User	`Perplexity-User`	Perplexity real time fetch	n/a
ClaudeBot	`ClaudeBot/1.0`	Anthropic Claude training and search	n/a
Meta-ExternalAgent	`meta-externalagent`	Meta AI Llama training	n/a

All current AI crawlers request mobile responsive content and treat the mobile rendering as canonical.

11.2 Verifying Mobile Crawl in Server Logs

To check whether Googlebot Smartphone is reaching priority URLs and which AI crawlers are visiting:

# Last 7 days of Googlebot Smartphone hits, grouped by URL
sudo zcat /var/log/nginx/access.log.*.gz | \
  grep -E "Googlebot.*Mobile" | awk '{print $7}' | \
  sort | uniq -c | sort -rn | head -20

# Distinct mobile crawler user agents seen this week
sudo grep -E "Googlebot|Bingbot|Applebot|OAI-SearchBot|PerplexityBot|ClaudeBot" \
  /var/log/nginx/access.log | awk -F'"' '{print $6}' | sort -u

11.3 robots.txt for Mobile and AI Crawlers

Allow all legitimate mobile crawlers:

User-agent: Googlebot
Allow: /

User-agent: Bingbot
Allow: /

User-agent: Applebot
Allow: /

User-agent: Applebot-Extended
Allow: /

User-agent: OAI-SearchBot
Allow: /

User-agent: ChatGPT-User
Allow: /

User-agent: GPTBot
Allow: /

User-agent: PerplexityBot
Allow: /

User-agent: Perplexity-User
Allow: /

User-agent: ClaudeBot
Allow: /

User-agent: meta-externalagent
Allow: /

Sitemap: https://example.com/sitemap.xml

Rate limiting at nginx (optional, for high traffic origins) uses limit_req_zone keyed on $binary_remote_addr with separate zones for Googlebot, Bingbot, Applebot (search engine class) and OAI-SearchBot, PerplexityBot, ClaudeBot, GPTBot (AI class).

12. Mobile Schema Considerations

12.1 Schema Parity Is Mandatory

Schema markup must be present in the mobile rendering. The most common 2026 schema failure mode is schema injected by a desktop only GTM container or rendered into a sidebar that is display: none on mobile. Either pattern means the mobile Googlebot sees no schema.

The audit: fetch the URL with Googlebot Smartphone user agent and grep for application/ld+json. The count of script blocks must match the count seen with the desktop user agent. The contents must be equivalent.

12.2 LocalBusiness for Apple Maps and Google Maps Mobile Cards

LocalBusiness schema with geo coordinates triggers map cards in mobile search results on both Apple Maps integrated results (iOS Spotlight) and Google Maps integrated results (Android Chrome, iOS Chrome). The mobile card includes call, directions, and website tap targets that bypass the SERP entirely.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "@id": "https://example.com/#localbusiness",
  "name": "Example Business",
  "url": "https://example.com",
  "telephone": "+15055551234",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main St",
    "addressLocality": "Anytown",
    "addressRegion": "NM",
    "postalCode": "87000",
    "addressCountry": "US"
  },
  "geo": {
    "@type": "GeoCoordinates",
    "latitude": 35.0844,
    "longitude": -106.6504
  },
  "openingHoursSpecification": [
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
      "opens": "09:00",
      "closes": "17:00"
    }
  ],
  "hasMap": "https://maps.google.com/?cid=1234567890",
  "sameAs": [
    "https://www.facebook.com/examplebusiness",
    "https://www.instagram.com/examplebusiness"
  ]
}
</script>

The hasMap field with a Google Maps CID URL links the schema to a specific Google Business Profile entity. The geo block lets Apple Maps surface the same business in iOS Spotlight Web results.

12.3 Product Schema and Mobile Shopping

Product schema price and availability freshness affects mobile shopping search cards. Stale prices (older than 24 hours per Google's product feed freshness guidelines, updated November 2024) trigger Google to demote the product from the Shopping carousel and from mobile rich results.

For sites with rapidly changing prices, the recommendation is to render product schema server side with a current timestamp, not client side via JavaScript:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Example Widget",
  "image": "https://example.com/img/widget.avif",
  "description": "...",
  "sku": "WIDGET-123",
  "brand": {
    "@type": "Brand",
    "name": "Example"
  },
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/products/widget",
    "priceCurrency": "USD",
    "price": "49.99",
    "priceValidUntil": "2026-12-31",
    "availability": "https://schema.org/InStock",
    "itemCondition": "https://schema.org/NewCondition",
    "seller": {
      "@type": "Organization",
      "name": "Example Inc."
    }
  }
}
</script>

12.4 MobileApplication Schema

For pages that describe a mobile app, MobileApplication schema lets Google and Bing surface app install cards in mobile search:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "MobileApplication",
  "name": "Example App",
  "operatingSystem": "iOS, Android",
  "applicationCategory": "BusinessApplication",
  "downloadUrl": [
    "https://apps.apple.com/app/id123456789",
    "https://play.google.com/store/apps/details?id=com.example.yourapp"
  ],
  "offers": {
    "@type": "Offer",
    "price": "0",
    "priceCurrency": "USD"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.7",
    "ratingCount": "1234"
  }
}
</script>

12.5 SpeakableSpecification for Voice Assistants

SpeakableSpecification flags content blocks that voice assistants should read aloud. Primarily relevant for NewsArticle:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "NewsArticle",
  "headline": "...",
  "datePublished": "2026-05-14T08:00:00-06:00",
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [".article-summary", ".article-tldr"]
  }
}
</script>

The CSS selectors point at the elements with the speakable content. Voice assistants (Google Assistant, Siri reading via Apple Intelligence) prefer these blocks for short audio answers.

See framework-schema.md for the full schema graph specification and framework-voicesearch.md for the voice assistant integration patterns.

13. Mobile Forms and Conversion

13.1 Semantic Input Types

The type attribute on <input> elements determines which keyboard the mobile OS surfaces:

type	Keyboard	autocomplete	inputmode alt
`email`	Email keyboard (@ and . prominent)	`email`	`email`
`tel`	Numeric phone keyboard	`tel`	`tel`
`number`	Numeric keyboard	(varies)	`numeric` (prefer on `type="text"` to avoid spinner controls)
`url`	URL keyboard (/ and .com prominent)	`url`	`url`
`date`	Native date picker on iOS and Android	(none)	(none)
`search`	Search keyboard (Search instead of Return)	(none)	(none)
`password`	Password keyboard	`new-password` (signup) or `current-password` (login)	(none)

13.2 The autocomplete Attribute

The autocomplete attribute is the single largest mobile form conversion lever. Without it, mobile users type every field by hand. With it, the OS surfaces saved values and the user taps to fill.

The full list of standardized autocomplete values is in the HTML Living Standard. The 2026 essentials for a contact form:

<form action="/api/contact" method="POST">
  <label for="name">Full name</label>
  <input id="name" name="name" type="text" autocomplete="name" required>

  <label for="email">Email</label>
  <input id="email" name="email" type="email" autocomplete="email" required>

  <label for="tel">Phone</label>
  <input id="tel" name="tel" type="tel" autocomplete="tel">

  <label for="organization">Company</label>
  <input id="organization" name="organization" type="text" autocomplete="organization">

  <label for="message">Message</label>
  <textarea id="message" name="message" required></textarea>

  <button type="submit">Send</button>
</form>

For a checkout form, autocomplete values are cc-name, cc-number, cc-exp, cc-csc for card details and street-address, address-level2 (city), address-level1 (state), postal-code for shipping. Numeric fields add inputmode="numeric" to surface the numeric keypad without forcing type="number" spinner controls.

13.3 iOS Password Autofill Integration

iOS Password Autofill (Settings > Passwords) suggests stored credentials at login forms and offers strong password generation at signup forms. The integration requires:

A login form with <input type="email" autocomplete="username"> (or autocomplete="email") and <input type="password" autocomplete="current-password">.
A signup form with <input type="email" autocomplete="username"> and <input type="password" autocomplete="new-password">.
The site domain associated with the app through /.well-known/apple-app-site-association (the webcredentials section, see Section 8.2).

When configured correctly, iOS users see their stored password offered above the keyboard with a single tap to fill.

13.4 Mobile Form Layout

Single column. Each field full width. Labels above the input, not beside (side labels truncate or wrap on narrow viewports). Submit button visible without scroll where possible.

.form {
  display: flex;
  flex-direction: column;
  gap: 1rem;
  max-width: 100%;
}

.form label {
  display: block;
  margin-bottom: 0.25rem;
  font-weight: 600;
}

.form input,
.form textarea,
.form select {
  width: 100%;
  padding: 0.75rem 1rem;
  font-size: 16px; /* prevents iOS auto zoom */
  border: 1px solid var(--border);
  border-radius: 6px;
  min-height: 48px;
}

.form button[type="submit"] {
  min-height: 48px;
  padding: 0.875rem 2rem;
  font-size: 1rem;
  font-weight: 600;
}

13.5 Form Validation on Mobile

Native HTML validation (required, pattern, type="email") works well on mobile. Custom JavaScript validation should run on blur or on submit, not on every keystroke (which thrashes the layout and breaks autofill).

<input id="email" 
       name="email" 
       type="email" 
       autocomplete="email"
       required 
       aria-describedby="email-error">
<div id="email-error" role="alert" aria-live="polite"></div>

The aria-live="polite" region announces validation errors to screen readers without interrupting the user.

14. Bubbles Hosted Mobile Testing

14.1 The Bubbles Stack

The reference deployment is self hosted on Debian at IP 169.155.162.118. nginx serves every site from /var/www/sites/[domain]/. No third party CDN sits between origin and user. The stack is single tier: client to nginx to filesystem (static) or to upstream FastAPI or Node service (dynamic).

Self hosted means full server log access, full TLS configuration control, full HTTP/3 tuning, full ability to inspect crawler behavior, and zero dependency on a third party SLA. The trade off is that you operate the box: you provision, you patch, you monitor.

14.2 nginx HTTP/3 Configuration

nginx 1.25 and later includes HTTP/3 over QUIC support in mainline. The configuration enables HTTP/3 on UDP port 443 alongside HTTP/2 on TCP port 443:

server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2;

  listen 443 quic reuseport;
  listen [::]:443 quic reuseport;

  http2 on;
  http3 on;
  http3_hq on;

  quic_retry on;
  ssl_early_data on;

  add_header Alt-Svc 'h3=":443"; ma=86400, h2=":443"; ma=86400';

  server_name example.com;
  root /var/www/sites/example.com/;

  ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

  ssl_protocols TLSv1.2 TLSv1.3;
  ssl_prefer_server_ciphers on;
  ssl_session_cache shared:SSL:50m;
  ssl_session_timeout 1d;

  # ... rest of config
}

The Alt-Svc header advertises HTTP/3 support to clients. Modern browsers see the header on the first HTTP/2 response and upgrade subsequent connections to HTTP/3.

UDP port 443 must be opened on the host firewall:

sudo ufw allow 443/udp
sudo ufw allow 443/tcp

14.3 Playwright Mobile Emulation on Linux

Playwright runs headless Chromium, Firefox, and WebKit on Linux with device emulation profiles for current mobile devices. Install on the Bubbles host:

sudo apt install -y nodejs npm
sudo npm install -g playwright
sudo npx playwright install --with-deps

A mobile emulation script (mobile-test.js) that iterates over device profiles, captures LCP, and writes a full page screenshot per device:

const { chromium, devices } = require('playwright');
const profiles = ['iPhone 15 Pro', 'iPhone SE', 'Pixel 8', 'Galaxy S24 Ultra', 'iPad Pro 11'];

(async () => {
  const browser = await chromium.launch();
  for (const name of profiles) {
    const ctx = await browser.newContext({ ...devices[name], locale: 'en-US' });
    const page = await ctx.newPage();
    await page.goto('https://example.com/');
    const lcp = await page.evaluate(() => new Promise(r => {
      new PerformanceObserver(l => r(l.getEntries().pop().startTime))
        .observe({ type: 'largest-contentful-paint', buffered: true });
    }));
    console.log(`${name}: LCP=${lcp}ms`);
    await page.screenshot({ path: `/tmp/screens/${name.replace(/\s+/g, '-')}.png`, fullPage: true });
    await ctx.close();
  }
  await browser.close();
})();

Run with mkdir -p /tmp/screens && node mobile-test.js. Screenshots reveal layout issues that lab Lighthouse runs miss.

14.4 Self Hosted Selenium Grid for Real Device Coverage

Browserstack and LambdaTest are third party device clouds at $30 to $80 per user per month. The self hosted alternative is a Selenium Grid running on the Bubbles host with Appium drivers for real mobile devices connected via USB or wifi adb.

Minimal Debian setup:

sudo apt install -y openjdk-17-jdk
wget https://github.com/SeleniumHQ/selenium/releases/download/selenium-4.18.0/selenium-server-4.18.0.jar
java -jar selenium-server-4.18.0.jar standalone --host 0.0.0.0 --port 4444

sudo npm install -g appium
appium driver install uiautomator2   # Android (Pixel via USB with debugging)
appium --port 4723

Verify device with adb devices. The Grid endpoint is then at http://bubbles:4444 on the LAN and Playwright or any Selenium client can dispatch tests to it. For iOS coverage, an Apple toolchain host (Mac) runs appium driver install xcuitest with USB connected iOS devices; the Bubbles Grid forwards iOS test dispatches to the Mac.

14.5 Self Hosted RUM for Mobile Field Data

A self hosted Real User Monitoring endpoint collects mobile Core Web Vitals from real visitors without sending data to a third party. A lightweight collector posts metrics to a nginx logging endpoint:

<script type="module">
import { onLCP, onINP, onCLS, onTTFB, onFCP } from 'https://unpkg.com/web-vitals@4?module';
const send = (m) => navigator.sendBeacon('/rum', JSON.stringify({
  name: m.name, value: m.value, rating: m.rating, id: m.id,
  url: location.href, ua: navigator.userAgent, timestamp: Date.now()
}));
onLCP(send); onINP(send); onCLS(send); onTTFB(send); onFCP(send);
</script>

nginx logs the POST body:

log_format rum_format escape=json '{"time":"$time_iso8601","ip":"$remote_addr","body":$request_body}';

location = /rum {
  access_log /var/log/nginx/rum.log rum_format;
  if ($request_method != POST) { return 405; }
  return 204;
}

The log file is JSONL and parseable with jq to extract p75 LCP, INP, CLS per day.

14.6 Mobile Emulation Test Cadence

Cadence	Action
Per commit	Lighthouse mobile run on the changed page (CI step); Playwright screenshot diff on iPhone 15 and Pixel 8
Per release	Playwright suite across five device profiles; real device smoke test on one iPhone and one Android; Lighthouse on top five URLs
Weekly	GSC URL Inspection on five priority URLs (verify Crawled As is Googlebot smartphone); RUM log review for p75 LCP, INP, CLS
Monthly	Cross device responsive review at 320, 360, 375, 768, 1024 viewports; real device session on a foldable (if applicable); service worker cache audit

15. Audit Mode

#	Criterion	Pass/Fail
MS1	Viewport meta with `viewport-fit=cover`, no `user-scalable=no`
MS2	Responsive design (no separate m.example.com, no AMP only path)
MS3	Content parity verified between Googlebot Smartphone and Googlebot Desktop
MS4	Schema parity verified between mobile and desktop renderings
MS5	Touch targets minimum 48 by 48 CSS pixels, 8 pixel spacing
MS6	Body text minimum 16 pixels on mobile
MS7	Pinch zoom enabled
MS8	Mobile LCP p75 under 2.5 seconds (field data)
MS9	Mobile INP p75 under 200 milliseconds (field data)
MS10	Mobile CLS p75 under 0.1 (field data)
MS11	nginx serves HTTP/3 over QUIC
MS12	Hero image preloaded; below the fold lazy loaded
MS13	Critical CSS inlined under 14 KB; non critical deferred
MS14	JavaScript executed before interaction under 250 KB
MS15	Click to call, click to map, click to SMS where appropriate
MS16	Forms use semantic input types and autocomplete attributes
MS17	Forms use `inputmode` where appropriate
MS18	No intrusive interstitials (cookie banner under 30 percent viewport)
MS19	Mobile navigation accessible via keyboard, screen reader, touch
MS20	Container queries used for component level responsive behavior
MS21	Safe area inset CSS used (`env(safe-area-inset-*)`)
MS22	Foldable posture queries considered (if foldable audience present)
MS23	`apple-app-site-association` and `assetlinks.json` served (if apps exist)
MS24	Smart App Banner meta tag present (if iOS app exists)
MS25	App Intents registered for Apple Intelligence (if iOS app exists)
MS26	Universal Links and Android App Links tested on real devices
MS27	LocalBusiness schema with geo coordinates (if local business)
MS28	MobileApplication and SpeakableSpecification schema where applicable
MS29	AMP pages sunset (no `/amp/` URLs serving in 2026)
MS30	Googlebot Smartphone verified in server logs in last 7 days
MS31	OAI-SearchBot or PerplexityBot verified in server logs in last 30 days
MS32	Applebot verified in server logs in last 30 days
MS33	Service worker registered with cache strategy (optional, recommended)
MS34	Playwright mobile suite runs on every release
MS35	Self hosted RUM collecting mobile field data
MS36	Real device pool with at least one iPhone and one Android
MS37	GSC URL Inspection confirms Crawled As Googlebot smartphone for priority URLs
MS38	GSC Mobile Usability report at zero issues
MS39	Mobile traffic share tracked in GA4

Score: 39. World class mobile SEO posture: 34+ of 39.

16. Common Mistakes

Treating mobile as a port from desktop. The 2026 pattern is mobile first; design for 320 pixels and progressively enhance.
Setting user-scalable=no. Accessibility failure; Lighthouse flag.
Tap targets under 48 by 48 pixels. Frustrates users; rage taps signal poor UX.
Hover only interactions. Touch users cannot access; AI assistants cannot extract.
Mobile schema parity failures. Schema rendered only on desktop (via GTM or hidden sidebar) is invisible to mobile first indexing.
Stale AMP pages. AMP is obsolete; sunset by 301 redirect.
Hero images lazy loaded. Always loading="eager" for hero; lazy load below the fold only.
JavaScript over 250 KB before interaction. Mobile INP suffers; mid range phones experience the worst.
Wrong input types. type="text" where type="email" or type="tel" belongs forces the wrong keyboard.
Missing autocomplete attributes. Largest mobile conversion lever left on the table.
Intrusive mobile interstitials. Mobile interstitial penalty active since 2017, still enforced.
No HTTP/3 on nginx. 200 to 400 ms TTFB improvement available at p75 on cellular.
No real device testing. Emulators miss safe area, foldable posture, and real network variance.
Ignoring foldable devices. 5.2 percent of premium audiences in 2026; high value conversion segment.
No App Intents registration. iOS apps with companion sites miss Apple Intelligence deep link surface.
Missing apple-app-site-association or assetlinks.json. Universal Links and Android App Links broken.
No self hosted RUM. Mobile field data depends on CrUX (28 day lag, aggregate only).

End of Framework Document

This framework specifies the mobile SEO layer for a self hosted nginx stack in 2026. Cross references:

framework-pageexperience.md: Core Web Vitals as a cross device discipline.
framework-technicalseo.md: nginx HTTP/3, TLS, and crawler access patterns.
framework-accessibility.md: WCAG 2.2 touch and screen reader requirements.
framework-aso.md: App Store and Play Store optimization companion to App Intents and App Links.
framework-localseo.md: Apple Maps, Google Maps, and local pack mobile patterns.
framework-uxseo.md: thumb zone navigation and mobile information architecture.
framework-schema.md: LocalBusiness, MobileApplication, SpeakableSpecification.
framework-voicesearch.md: Siri, Apple Intelligence Voice, ChatGPT Voice, Google Assistant.
framework-aicitations.md: the broader AI citation surface that runs predominantly on mobile.
framework-aioverviews.md: Google AI Overviews and AI Mode mobile rendering.
framework-multimodalsearch.md: Google Lens, Apple Visual Look Up, mobile camera search.

The mobile surface is the primary surface in 2026. Every framework in the library assumes the mobile rendering is canonical, the mobile vitals are the canonical vitals, and the mobile experience determines conversion and citation across both classic and AI search.

Source

Canonical: https://www.thatdevpro.com/insights/framework-mobileseo/

ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Engine Optimization service · Contact

Web security headers + HSTS + CSP

Joseph Anady — Sun, 24 May 2026 01:21:59 +0000

Originally published at thatdevpro.com. Part of ThatDevPro's open SEO + AI framework library. ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.

HTTPS, Headers, Authentication, WAF, Hardening, Incident Response, and the Security Posture Required to Maintain Search Trust

A comprehensive reference for web security across the sites Joseph manages. Security is a baseline expectation in 2026 — Google explicitly considers HTTPS a ranking factor (modest), security issues trigger manual actions, browser warnings destroy conversion rates, and breach incidents create permanent brand damage.

1. Document Purpose

Security is often treated as separate from SEO/marketing concerns, but the disciplines significantly overlap. Hacked sites lose rankings, get flagged in browsers as dangerous, drive away users, generate manual actions in GSC, and require months of recovery work. Sites with poor security signals lose trust both with users and with search engines.

For Joseph's specific situation managing 130+ production client sites on self-managed Linux infrastructure, security discipline is foundational. A single compromised client site affects the broader hosting environment. WordPress sites particularly attract attack attempts continuously.

This framework specifies security implementation across the full stack — server, application, content, and operational dimensions.

1.1 Required Tools

SSL Labs — ssllabs.com/ssltest/ — SSL/TLS configuration testing
Mozilla Observatory — observatory.mozilla.org — security headers analysis
Security Headers — securityheaders.com — header analysis
WPScan — WordPress vulnerability scanner
OWASP ZAP — application security scanner
Wordfence / Sucuri / Patchstack — WordPress security platforms
Cloudflare — WAF and DDoS protection
Let's Encrypt / acme.sh — free SSL certificates

2. HTTPS Implementation

2.1 SSL Certificate Management

ssl_certificate_management:

  certificate_options:

    lets_encrypt:
      cost: "Free"
      validity: "90 days (auto-renew)"
      best_for: "Most sites; commodity SSL"
      automation: "Certbot, acme.sh"

    paid_dv_certificates:
      cost: "$10-100/year"
      validity: "1-2 years"
      best_for: "Sites preferring longer validity"
      benefit: "Sometimes faster issuance"

    extended_validation:
      cost: "$100-500+/year"
      validity: "1-2 years"
      best_for: "Financial, e-commerce with high trust requirements"
      note: "Browser address bar treatment reduced; less differentiation than years past"

  multi_domain_strategies:

    san_certificates:
      description: "Multiple domains in single certificate"
      use_case: "Multiple related domains"

    wildcard_certificates:
      description: "Covers *.example.com subdomains"
      use_case: "Many subdomains"
      note: "Doesn't cover apex; need separate or SAN with apex"

    multi_san:
      description: "Multiple unrelated domains in one certificate"
      use_case: "Convenience; fewer certificates to manage"

2.2 Let's Encrypt Implementation

For Joseph's Debian/Nginx setup managing 130+ sites:

# Install certbot
apt install certbot python3-certbot-nginx

# Get certificate for single site
certbot --nginx -d example.com -d www.example.com

# Auto-renewal (typically configured by certbot install)
systemctl status certbot.timer

# Manual renewal test
certbot renew --dry-run

For mass renewal management:

# Renew all certificates
certbot renew --quiet

# Should be in cron or systemd timer
# Default: twice daily check, renews when within 30 days of expiry

2.3 Nginx HTTPS Configuration

Strong default Nginx HTTPS configuration:

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name example.com www.example.com;

    # SSL Certificate
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    # Modern SSL Configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384';
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # OCSP Stapling
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;
    resolver 1.1.1.1 8.8.8.8 valid=300s;

    # Security Headers (see Section 3)
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

    # ... rest of configuration
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

2.4 SSL Testing

After implementation, verify with SSL Labs (ssllabs.com/ssltest/):

Target: A or A+ grade
Issues to fix: protocol weaknesses, weak ciphers, missing OCSP, certificate chain issues

3. Security Headers

Security headers add layers of browser-enforced protection.

3.1 Complete Security Headers

# Strict-Transport-Security (HSTS)
# Forces HTTPS, prevents downgrade attacks
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

# X-Frame-Options
# Prevents clickjacking via iframe embedding
add_header X-Frame-Options "SAMEORIGIN" always;

# X-Content-Type-Options
# Prevents MIME sniffing
add_header X-Content-Type-Options "nosniff" always;

# Referrer-Policy
# Controls referrer information sent
add_header Referrer-Policy "strict-origin-when-cross-origin" always;

# Permissions-Policy (formerly Feature-Policy)
# Controls browser features
add_header Permissions-Policy "geolocation=(), microphone=(), camera=()" always;

# Content-Security-Policy (most complex; see below)
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' https://www.googletagmanager.com; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data: https:; connect-src 'self' https://www.google-analytics.com; frame-ancestors 'self'; base-uri 'self'; form-action 'self';" always;

# Cross-Origin policies
add_header Cross-Origin-Opener-Policy "same-origin" always;
add_header Cross-Origin-Resource-Policy "same-origin" always;
add_header Cross-Origin-Embedder-Policy "require-corp" always;

3.2 Content Security Policy (CSP)

CSP is the most complex but most powerful header. It defines what sources of scripts, styles, images, etc. are allowed:

csp_directives:

  default_src:
    purpose: "Fallback for other directives"
    typical: "'self'"

  script_src:
    purpose: "Allowed JavaScript sources"
    common_additions:
      - "'self'"
      - "https://www.googletagmanager.com"
      - "https://www.google-analytics.com"
      - "'unsafe-inline'" # Often required; reduces protection
    avoid: "'unsafe-eval' unless absolutely required"

  style_src:
    purpose: "Allowed CSS sources"
    common: "'self' 'unsafe-inline' https://fonts.googleapis.com"

  img_src:
    purpose: "Allowed image sources"
    common: "'self' data: https:"

  font_src:
    purpose: "Allowed font sources"
    common: "'self' https://fonts.gstatic.com"

  connect_src:
    purpose: "Allowed fetch/XHR destinations"
    common: "'self' https://www.google-analytics.com"

  frame_ancestors:
    purpose: "Who can iframe this page"
    typical: "'self'"
    note: "Replaces X-Frame-Options"

  base_uri:
    purpose: "Restrict <base> element"
    typical: "'self'"

  form_action:
    purpose: "Where forms can submit"
    typical: "'self'"

3.3 CSP Implementation Approach

csp_implementation:

  step_1_audit:
    - Inventory all script sources
    - Inventory all style sources
    - Inventory all image, font, fetch sources

  step_2_report_only:
    header: "Content-Security-Policy-Report-Only"
    purpose: "Test policy without enforcement"
    duration: "Run 1-2 weeks; collect violations"

  step_3_iterate:
    - Review violation reports
    - Adjust policy to allow legitimate sources
    - Block malicious or unnecessary

  step_4_enforce:
    header: "Content-Security-Policy"
    purpose: "Switch from report-only to enforcement"

  step_5_monitor:
    - Continued violation reporting via report-uri or report-to
    - Adjust as legitimate needs change

4. WordPress-Specific Security

For Joseph's significant WordPress portfolio:

4.1 WordPress Hardening Baseline

wordpress_hardening:

  core_updates:
    requirement: "WordPress core auto-updates enabled"
    cadence: "Weekly verification across portfolio"
    automation: "Automatic for security patches; managed for major versions"

  plugins:
    rule: "Only install reputable plugins from wordpress.org or trusted sources"
    audit: "Quarterly plugin audit per site"
    remove: "Inactive plugins (security surface)"
    update: "Auto-updates enabled for security; managed for major versions"

  themes:
    rule: "Reputable themes only"
    audit: "Inactive themes removed"
    custom_themes: "Maintained and updated"

  user_accounts:
    admin_username: "Never 'admin' (default)"
    default_role: "Subscriber for new users"
    role_review: "Quarterly review of administrators"
    inactive_users: "Removed periodically"

  password_security:
    requirement: "Strong passwords enforced"
    plugin: "Force Strong Passwords or similar"
    two_factor: "Enabled for administrators"

  file_permissions:
    files: "644"
    directories: "755"
    wp_config: "600"

  wp_config_hardening:
    keys: "Salts/keys regenerated; never default"
    db_prefix: "Non-default ('wp_' is default; change to random)"
    debug: "False in production"

  xml_rpc:
    typical: "Disable unless required (mobile app, Jetpack)"
    method: ".htaccess block or plugin"

  rest_api:
    public_endpoints: "Restrict where appropriate"
    plugin: "Disable WP REST API or similar for restriction"

  login_protection:
    rate_limiting: "Limit Login Attempts plugin"
    captcha: "On login form"
    two_factor: "Wordfence 2FA, Google Authenticator, etc."
    custom_login_url: "WPS Hide Login or similar"

4.2 WordPress Security Plugins

wordpress_security_plugin_options:

  wordfence:
    type: "Comprehensive security suite"
    features: ["Firewall", "Malware scan", "Login protection", "2FA"]
    cost: "Free + Premium"
    recommended_for: "Most WordPress sites"

  sucuri:
    type: "Comprehensive security suite"
    features: ["Firewall", "Malware scan", "Cleanup service"]
    cost: "Free plugin + paid services"
    recommended_for: "Sites needing managed cleanup"

  patchstack:
    type: "Vulnerability patching"
    features: ["Virtual patching", "Vulnerability database"]
    cost: "Paid"
    recommended_for: "Sites with many plugins"

  ithemes_security:
    type: "Comprehensive security suite"
    features: ["Various hardening", "2FA", "Log monitoring"]
    cost: "Free + Pro"
    recommended_for: "Alternative to Wordfence"

For Joseph's hosting situation managing 130+ sites: standardizing on one security solution simplifies management. Wordfence Premium across portfolio with central monitoring is common pattern.

4.3 WordPress Backup

wordpress_backup_strategy:

  frequency:
    files: "Daily for high-change sites; weekly for static-content"
    database: "Daily minimum"

  retention:
    daily: "Keep 7-30 days"
    weekly: "Keep 4-12 weeks"
    monthly: "Keep 6-12 months"

  storage:
    requirement: "Off-server location"
    options:
      - S3 / Backblaze B2 / Wasabi
      - Other cloud storage
      - Different physical server
    avoid: "Backups only on same server (lost in compromise)"

  testing:
    quarterly: "Test restore procedure"
    purpose: "Verify backups are actually viable"

  plugins:
    options:
      - UpdraftPlus (most popular)
      - BackWPup
      - Duplicator Pro
      - WP Time Capsule
    server_side:
      - rsync to off-server location
      - Scripted backup to S3 or similar

5. Server-Level Security

For Joseph's self-managed Linux infrastructure:

5.1 SSH Hardening

# /etc/ssh/sshd_config

# Disable root login
PermitRootLogin no

# Use SSH keys only, no passwords
PasswordAuthentication no
ChallengeResponseAuthentication no

# Limit users who can SSH
AllowUsers joseph backupuser

# Change default port (security through obscurity, but reduces noise)
Port 22042  # Or any non-standard port

# Limit authentication attempts
MaxAuthTries 3
LoginGraceTime 30

# Modern protocol only
Protocol 2

# Strong key exchange
KexAlgorithms curve25519-sha256@libssh.org,diffie-hellman-group-exchange-sha256

# Modern ciphers only
Ciphers chacha20-poly1305@openssh.com,aes256-gcm@openssh.com,aes128-gcm@openssh.com

After changes:

sshd -t  # Test config
systemctl restart sshd

5.2 Firewall (UFW or iptables)

# Basic UFW configuration
ufw default deny incoming
ufw default allow outgoing

# Allow SSH (on custom port if changed)
ufw allow 22042/tcp

# Allow web traffic
ufw allow 80/tcp
ufw allow 443/tcp

# Enable firewall
ufw enable

# Status
ufw status verbose

5.3 Fail2ban

Prevents brute force attacks:

apt install fail2ban

# /etc/fail2ban/jail.local
[DEFAULT]
bantime = 3600
findtime = 600
maxretry = 3

[sshd]
enabled = true
port = 22042

[nginx-http-auth]
enabled = true

[wordpress]
enabled = true
filter = wordpress
logpath = /var/log/nginx/access.log

5.4 Automatic Security Updates

# Debian/Ubuntu unattended-upgrades
apt install unattended-upgrades
dpkg-reconfigure -plow unattended-upgrades

# Configure /etc/apt/apt.conf.d/50unattended-upgrades
# Enable security updates
# Configure email notifications

5.5 Log Monitoring

log_monitoring:

  what_to_monitor:
    - Failed login attempts (auth.log)
    - Web server errors (nginx error log)
    - Suspicious request patterns (nginx access log)
    - Application errors (varies)

  tools:
    - logwatch (daily summary email)
    - GoAccess (real-time web log analysis)
    - Centralized logging (ELK stack, Graylog, etc.) for larger setups

  alerts:
    - Unusual login patterns
    - High error rates
    - Suspicious traffic patterns
    - Disk space warnings

6. Cloudflare WAF

For sites where Joseph manages or recommends:

cloudflare_security_layer:

  free_tier_features:
    - Free SSL/TLS
    - Basic DDoS protection
    - Bot fight mode
    - Browser integrity check

  pro_tier_additions:
    - WAF rules (managed rulesets)
    - Image optimization
    - Mobile redirect

  business_tier_additions:
    - Custom WAF rules
    - Rate limiting
    - Page rules with more options

  setup_steps:
    - Add domain to Cloudflare
    - Update nameservers
    - Verify proxying enabled (orange cloud)
    - Configure SSL mode (Full Strict recommended)
    - Enable security features
    - Test thoroughly

  custom_rules_examples:
    block_xmlrpc: "Block /xmlrpc.php to all (WordPress)"
    rate_limit_login: "Rate limit /wp-login.php"
    block_known_bad_ips: "Block IPs from threat intelligence"
    challenge_high_risk_countries: "Where business doesn't operate"

7. Application Security

7.1 Common Vulnerabilities (OWASP Top 10)

owasp_top_10_2021:

  A01_broken_access_control:
    examples: "Path traversal, IDOR, missing authorization"
    prevention: "Server-side authorization checks; least privilege"

  A02_cryptographic_failures:
    examples: "Weak encryption, plaintext passwords"
    prevention: "Modern crypto; password hashing (bcrypt, argon2)"

  A03_injection:
    examples: "SQL injection, XSS, command injection"
    prevention: "Parameterized queries; input sanitization; output encoding"

  A04_insecure_design:
    examples: "Missing security in design"
    prevention: "Threat modeling; secure design patterns"

  A05_security_misconfiguration:
    examples: "Default credentials, verbose errors, missing headers"
    prevention: "Security baselines; configuration audits"

  A06_vulnerable_components:
    examples: "Outdated libraries, dependencies"
    prevention: "Dependency scanning; regular updates"

  A07_authentication_failures:
    examples: "Weak passwords, session management issues"
    prevention: "Strong auth, MFA, session security"

  A08_software_data_integrity_failures:
    examples: "Unsigned updates, deserialization vulns"
    prevention: "Signed updates; safe deserialization"

  A09_logging_monitoring_failures:
    examples: "No logging, no monitoring"
    prevention: "Comprehensive logging; alerting"

  A10_ssrf:
    examples: "Server-side request forgery"
    prevention: "URL validation; allow lists"

7.2 Input Validation & Output Encoding

// PHP example — parameterized query (prevents SQL injection)
$stmt = $pdo->prepare("SELECT * FROM users WHERE email = ?");
$stmt->execute([$email]);

// JavaScript — output encoding (prevents XSS)
element.textContent = userInput;  // Safe
element.innerHTML = userInput;     // DANGEROUS

// React — automatic encoding
{userInput}  // Safe
dangerouslySetInnerHTML={{__html: userInput}}  // DANGEROUS

8. Incident Response

8.1 Incident Response Plan

incident_response_phases:

  preparation:
    - Documented response plan
    - Contact list (hosting, registrar, security firm)
    - Backup access verified
    - Logging in place to support investigation

  detection:
    - Monitoring alerts
    - User reports
    - Security tools detection
    - Search engine warnings

  containment:
    immediate:
      - Take site offline if active attack
      - Change all credentials
      - Block attacker IP if identified
    short_term:
      - Isolate affected systems
      - Preserve evidence
      - Engage security team or service if needed

  eradication:
    - Identify root cause
    - Remove malicious content
    - Patch vulnerability
    - Verify thorough cleanup

  recovery:
    - Restore from clean backup if needed
    - Bring systems back online
    - Verify normal operation
    - Monitor closely for return

  post_incident:
    - Root cause analysis
    - Documentation
    - Process improvements
    - Affected user notification (if applicable)

8.2 Common Incidents

common_incident_types:

  malware_injection:
    detection: "Malware scan, GSC security warning"
    response: "Identify entry point; clean files; patch vulnerability"

  defacement:
    detection: "Visual inspection; user reports"
    response: "Restore from backup; identify entry point"

  data_breach:
    detection: "Database access patterns; user reports"
    response: "Major incident; legal counsel; user notification"

  ddos:
    detection: "Traffic spike; service degradation"
    response: "Cloudflare or similar; rate limiting"

  account_compromise:
    detection: "Unusual admin activity; user reports"
    response: "Lock account; force password reset; audit logs"

8.3 Manual Action from Hacked Content

If GSC reports manual action for hacked content:

Address issue per Section 8.1
Verify thorough cleanup
Submit reconsideration request via GSC
Document remediation work

9. Privacy and Compliance

9.1 Privacy Considerations

privacy_baseline:

  privacy_policy:
    requirement: "Comprehensive policy on every site"
    contents:
      - Data collected
      - How used
      - Third parties
      - User rights
      - Contact information

  cookie_consent:
    requirement: "EEA traffic; good practice elsewhere"
    implementation: "CMP per framework-ga4.md"

  user_data_handling:
    minimum_collection: "Only collect what's needed"
    secure_storage: "Encrypt at rest"
    secure_transmission: "Always HTTPS"
    retention_limits: "Don't keep indefinitely"
    deletion_rights: "Process user deletion requests"

9.2 Regulatory Compliance

relevant_regulations:

  gdpr: "EU and UK; comprehensive privacy law"
  ccpa_cpra: "California; consumer privacy"
  hipaa: "Healthcare data in US"
  pci_dss: "Payment card data"
  ferpa: "Educational records"
  coppa: "Children under 13"

For client sites, compliance is the client's legal responsibility but Joseph's implementation should support compliance (HTTPS, consent, secure handling, etc.).

10. Audit Mode

#	Criterion	Pass/Fail
SEC1	HTTPS enforced sitewide
SEC2	SSL Labs grade A or A+
SEC3	All security headers configured
SEC4	CSP implemented (at least basic)
SEC5	WordPress hardening baseline applied (if WP)
SEC6	Security plugin active (if WP)
SEC7	Backup strategy implemented and tested
SEC8	SSH hardened (key auth, no root)
SEC9	Firewall configured
SEC10	Fail2ban or equivalent active
SEC11	Automatic security updates enabled
SEC12	Cloudflare or equivalent WAF (where appropriate)
SEC13	Log monitoring established
SEC14	Vulnerability scanning periodic
SEC15	Incident response plan documented
SEC16	Privacy policy current

Score: 16. World-class security baseline: 14+/16.

11. Common Mistakes

HTTP still allowed — must redirect or fail
Missing security headers — easy wins skipped
Default WordPress credentials — admin username, weak password
Outdated plugins/themes — primary WordPress attack vector
No backup off-server — backup destroyed in compromise
No vulnerability scanning — issues unknown until exploited
No 2FA — account compromise risk
Verbose error messages — leak information to attackers
Default ports and configurations — easier to attack
No incident response plan — paralysis when incident occurs

End of Framework Document

Companion documents:

framework-https.md — HTTPS implementation specifics (overlap)
framework-hosting.md — Hosting environment security
framework-spampolicies.md — Manual actions from hacked content
framework-wordpress.md — WordPress-specific implementation
framework-serverconfig.md — Server configuration

About this framework library

Dev.to republish of a framework from ThatDevPro's SEO + AI engineering library. Canonical source: https://www.thatdevpro.com/insights/framework-security/

ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Need this framework implemented? See the Engine Optimization service or hire via contact.

Web performance beyond Core Web Vitals

Joseph Anady — Sun, 24 May 2026 01:21:37 +0000

Originally published at thatdevpro.com. Part of ThatDevPro's open SEO + AI framework library. ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.

Core Web Vitals Deep Dive, Resource Optimization, Server Performance, CDN Strategy, Caching Layers, and the Comprehensive Discipline of Web Performance

A comprehensive reference for web performance optimization across the full stack. Performance affects rankings (Core Web Vitals are explicit ranking factors), conversion (slow sites lose visitors), and AI engine accessibility (slow sites get crawled less). Performance is both technical foundation and competitive differentiation.

1. Document Purpose

Performance work spans many disciplines: server configuration, CDN selection, asset optimization, database tuning, frontend code, third-party scripts, image handling, font delivery, and more. Each layer offers optimization opportunities; cumulative impact determines real-world performance.

This framework specifies the comprehensive performance optimization approach, complementing framework-pageexperience.md (Core Web Vitals focus) with broader performance considerations.

For Joseph's portfolio managing 130+ sites on self-managed Linux infrastructure, performance discipline at scale matters significantly.

1.1 Required Tools

PageSpeed Insights — pagespeed.web.dev — Core Web Vitals + Lighthouse
Lighthouse — Chrome DevTools comprehensive audit
WebPageTest — webpagetest.org — detailed waterfall analysis
GTmetrix — performance dashboards
Real User Monitoring — actual user performance data
Chrome DevTools — Performance and Network tabs
Server monitoring — Linux tools (top, iostat, etc.)

2. Performance Measurement

2.1 Lab vs Field Data

performance_measurement_types:

  lab_data:
    description: "Synthetic testing in controlled environment"
    tools: ["Lighthouse", "WebPageTest", "GTmetrix"]
    benefits:
      - Reproducible
      - Controlled variables
      - Detailed waterfall analysis
    limitations:
      - Doesn't reflect real user variety
      - May test under ideal conditions
      - Can be gamed for higher scores

  field_data:
    description: "Real user monitoring (RUM) of actual visits"
    sources: ["Chrome User Experience Report (CrUX)", "Self-deployed RUM"]
    benefits:
      - Reflects real-world performance
      - Across user device/network variety
      - What Google uses for ranking
    limitations:
      - Less granular debugging
      - Slower feedback loop
      - Privacy considerations

  use_both:
    rationale: "Lab for debugging; field for reality"
    monitoring_pattern: "Lab during development; field in production"

2.2 Core Web Vitals (2026)

core_web_vitals_2026:

  lcp_largest_contentful_paint:
    measures: "Loading performance"
    target: "Under 2.5 seconds"
    measurement_window: "75th percentile of users"

  inp_interaction_to_next_paint:
    measures: "Responsiveness"
    target: "Under 200ms"
    measurement_window: "75th percentile"
    note: "Replaced FID in March 2024"

  cls_cumulative_layout_shift:
    measures: "Visual stability"
    target: "Under 0.1"
    measurement_window: "75th percentile"

2.3 Additional Performance Metrics

additional_metrics:

  ttfb_time_to_first_byte:
    measures: "Server response time"
    target: "Under 800ms"
    significance: "Foundation for all subsequent metrics"

  fcp_first_contentful_paint:
    measures: "First content visible"
    target: "Under 1.8 seconds"

  speed_index:
    measures: "How quickly content visible during load"
    target: "Under 3.4 seconds (mobile)"

  total_blocking_time:
    measures: "Main thread blocking"
    target: "Under 200ms"

  time_to_interactive:
    measures: "When page fully interactive"
    target: "Under 3.8 seconds (mobile)"

3. Server Performance

3.1 Hosting Foundation

Performance starts with hosting. Cheap shared hosting makes optimization difficult.

hosting_performance_factors:

  resources:
    cpu: "Adequate cores; not throttled"
    ram: "Sufficient for application needs"
    disk_io: "SSD essential; NVMe preferred"
    network: "Gigabit connectivity"

  configuration:
    php_version: "Modern PHP 8.x"
    web_server: "Nginx or Apache 2.4+ optimized"
    database: "MySQL 8 or MariaDB 10.6+"

  scaling:
    vertical: "More resources on same server"
    horizontal: "Multiple servers; load balancing"
    auto_scaling: "Cloud providers; scales with traffic"

  joseph_setup:
    server: "Bubbles (self-managed Debian)"
    sites: "130+ production sites"
    optimization: "Resource allocation per site; appropriate caching"

3.2 Nginx Optimization

# Optimized Nginx configuration patterns

# Worker processes
worker_processes auto;
worker_rlimit_nofile 65535;

events {
    worker_connections 1024;
    multi_accept on;
    use epoll;
}

http {
    # Sendfile for static files
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;

    # Keep alive
    keepalive_timeout 30;
    keepalive_requests 100;

    # Buffers
    client_body_buffer_size 16k;
    client_max_body_size 100m;
    client_header_buffer_size 1k;
    large_client_header_buffers 4 8k;

    # Compression
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/json
        application/javascript
        application/xml+rss
        application/xml
        image/svg+xml
        font/woff
        font/woff2;

    # Brotli (if module installed)
    brotli on;
    brotli_comp_level 6;
    brotli_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/json
        application/javascript
        application/xml+rss
        application/xml
        image/svg+xml;

    # FastCGI cache for PHP
    fastcgi_cache_path /var/cache/nginx levels=1:2 keys_zone=fcgi:100m max_size=1g inactive=60m;
    fastcgi_cache_use_stale error timeout invalid_header http_500;
    fastcgi_cache_lock on;

    # HTTP/2 push (HTTP/2)
    http2_push_preload on;
}

3.3 PHP-FPM Optimization

# /etc/php/8.2/fpm/pool.d/www.conf

; Process management
pm = dynamic
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35
pm.max_requests = 500

; Slow log
slowlog = /var/log/php-fpm-slow.log
request_slowlog_timeout = 5s

; OPcache
opcache.enable = 1
opcache.memory_consumption = 256
opcache.interned_strings_buffer = 16
opcache.max_accelerated_files = 20000
opcache.validate_timestamps = 0  ; Production; restart on deploy
opcache.save_comments = 1

3.4 Database Optimization

mysql_optimization:

  configuration:
    innodb_buffer_pool_size: "70-80% of RAM for dedicated DB server"
    innodb_log_file_size: "256MB+"
    innodb_flush_method: "O_DIRECT"
    query_cache_size: "Removed in MySQL 8; use other caching"

  indexing:
    - Index foreign keys
    - Index columns used in WHERE clauses frequently
    - Composite indexes for multi-column queries
    - Avoid over-indexing (indexes slow writes)

  query_optimization:
    - EXPLAIN to analyze queries
    - Avoid SELECT *
    - Limit result sets where possible
    - Optimize joins

  ongoing_maintenance:
    - Regular OPTIMIZE TABLE
    - Slow query log monitoring
    - Long-running query alerts

4. Caching Strategy

4.1 Caching Layers

caching_layers:

  browser_cache:
    location: "User's browser"
    purpose: "Repeat visitors don't re-download"
    configuration: "Cache-Control headers"

  cdn_cache:
    location: "CDN edge servers globally"
    purpose: "Geographic proximity"
    services: ["Cloudflare", "Fastly", "BunnyCDN", "KeyCDN"]

  reverse_proxy_cache:
    location: "Front of application server"
    examples: ["Varnish", "Nginx FastCGI cache"]
    purpose: "Avoid hitting application for cached responses"

  application_cache:
    location: "Application memory"
    examples: ["WordPress object cache", "Rails cache"]
    purpose: "Cache expensive computations"

  database_query_cache:
    location: "Object cache backed by Redis/Memcached"
    purpose: "Cache database query results"

  cdn_origin_shield:
    location: "Between CDN and origin"
    purpose: "Reduce origin load"
    services: ["Cloudflare Argo", "Fastly Origin Shield"]

4.2 Cache Headers

# Static assets — cache aggressively
location ~* \.(jpg|jpeg|png|gif|ico|svg|webp|woff|woff2|ttf|css|js)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
    access_log off;
}

# HTML — cache briefly, allow revalidation
location ~* \.html$ {
    expires 1h;
    add_header Cache-Control "public, must-revalidate";
}

# API responses — typically don't cache
location /api/ {
    add_header Cache-Control "no-store, no-cache, must-revalidate";
}

4.3 Object Cache (Redis)

For WordPress and other database-heavy applications:

redis_object_cache:

  setup:
    install: "apt install redis-server"
    php_extension: "apt install php8.2-redis"
    plugin: "Redis Object Cache plugin (WordPress)"

  benefits:
    - Significant database load reduction
    - Faster page generation
    - Better scalability

  configuration:
    maxmemory: "Set based on available RAM"
    maxmemory_policy: "allkeys-lru"
    persistence: "Disable for cache use (improves performance)"

4.4 Page Cache

page_cache_strategies:

  full_page_cache:
    pattern: "Cache complete HTML responses"
    benefit: "Skip PHP/DB entirely for cached pages"
    invalidation: "Clear on content updates"

  partial_caching:
    pattern: "Cache specific page sections"
    use_for: "Mostly static with some dynamic parts"

  dynamic_caching:
    pattern: "Cache for short periods (1-60 seconds)"
    use_for: "High-traffic dynamic sites"
    benefit: "Significant load reduction even on dynamic content"

  edge_side_includes:
    pattern: "Cache shell; insert dynamic blocks"
    technology: "Varnish ESI; Cloudflare Workers"

5. CDN Strategy

5.1 CDN Selection

cdn_options:

  cloudflare:
    pricing: "Free tier generous; Pro $20/month; higher tiers"
    features:
      - Global edge network
      - DDoS protection
      - WAF
      - Argo intelligent routing (paid)
      - Workers (edge compute)
      - Image optimization (paid)
      - R2 object storage
    best_for: "Most sites; comprehensive features"
    used_widely: "Industry standard for many"

  fastly:
    pricing: "Pay per usage; minimum spend"
    features:
      - Edge compute (VCL, Compute@Edge)
      - Real-time logging
      - Highly programmable
    best_for: "High-traffic sites with custom needs"

  bunnycdn:
    pricing: "Very competitive ($1/month minimum)"
    features:
      - Bunny Optimizer (image optimization)
      - Edge storage
      - Stream (video)
    best_for: "Cost-conscious sites"

  keycdn:
    pricing: "Competitive; pay-per-usage"
    features:
      - Strong edge network
      - Image processing
    best_for: "Cost-conscious alternative"

  vercel_netlify_built_in:
    note: "Included with these hosting platforms"
    benefit: "Integrated workflow"

5.2 CDN Configuration

cdn_optimization:

  cache_rules:
    static_assets: "Cache aggressively (1 year)"
    html: "Cache briefly (5 minutes - 1 hour)"
    api: "Typically no cache"
    custom: "Per-path rules"

  ssl:
    requirement: "HTTPS via CDN"
    options:
      flexible: "CDN to origin via HTTP (less secure)"
      full: "End-to-end HTTPS"
      strict: "End-to-end HTTPS with origin certificate validation (best)"

  page_rules_cloudflare:
    examples:
      - "Cache everything for /static/* (1 year)"
      - "Bypass cache for /admin/*"
      - "Always use HTTPS"

  performance_features:
    auto_minify: "Minify HTML, CSS, JS"
    rocket_loader: "Async JavaScript loading"
    early_hints: "HTTP 103 for resource preload"
    http2_prioritization: "Smart resource prioritization"
    http3: "Latest HTTP version"

6. Asset Optimization

6.1 Image Optimization

See framework-imageseo.md Section 4. Key performance points:

image_performance:

  formats:
    modern: "AVIF (best compression); WebP (broadly supported)"
    fallback: "JPEG for photos; PNG for graphics"
    technique: "<picture> with multiple sources"

  responsive_images:
    pattern: "srcset with appropriate sizes"
    benefit: "Load size matching viewport"

  compression:
    photos: "JPEG quality 75-85 typically"
    graphics: "PNG-8 where colors limited"
    automation: "ImageMagick, sharp, build-time tools"

  lazy_loading:
    standard: 'loading="lazy" attribute'
    benefit: "Below-fold images load on demand"
    first_paint_image: 'loading="eager" or no attribute'

  cdn_image_optimization:
    services: "Cloudflare Polish, Bunny Optimizer, Cloudinary, Imgix"
    benefit: "On-the-fly optimization at CDN"

6.2 JavaScript Optimization

javascript_optimization:

  minimize_total:
    rule: "Less JavaScript is better"
    audit: "Coverage tab in Chrome DevTools"
    remove: "Unused libraries and code"

  code_splitting:
    pattern: "Per-route or per-feature bundles"
    framework_support: "Webpack, Rollup, esbuild built-in"

  defer_and_async:
    defer: "Wait until DOM ready"
    async: "Load asynchronously; execute when ready"
    use_for: "Non-critical scripts"

  third_party_audit:
    audit: "Each third-party script: necessary?"
    common_culprits:
      - Heavy chat widgets
      - Multiple analytics tools
      - Tag manager bloat
      - Social embeds
    fixes:
      - Remove unnecessary
      - Defer non-critical
      - Use lighter alternatives

  modern_js:
    benefit: "Smaller bundles for modern browsers"
    pattern: "ES modules with module/nomodule"

6.3 CSS Optimization

css_optimization:

  critical_css:
    pattern: "Inline above-fold CSS in head"
    benefit: "Render without waiting for external CSS"
    tools: "Critical, Penthouse, build tools"

  non_critical_async:
    pattern: "Load main CSS asynchronously after render"
    technique: 'rel="preload" + onload swap'

  remove_unused:
    audit: "Coverage tab shows unused CSS"
    tools: "PurgeCSS, UnCSS, build-time"

  minimize_imports:
    rule: "Don't import full frameworks for partial use"
    example: "Tailwind purges unused classes by default"

  modern_css:
    grid_and_flex: "Replace JavaScript layouts"
    css_variables: "Reduce duplicated values"
    container_queries: "Component-level responsive"

6.4 Font Optimization

font_optimization:

  font_display_swap:
    css: "font-display: swap;"
    benefit: "Show fallback font during font load; swap when ready"
    avoid_invisible_text: "Critical for performance metrics"

  preload_critical:
    pattern: '<link rel="preload" as="font" type="font/woff2" crossorigin>'
    use_for: "Above-fold fonts"

  subset_fonts:
    benefit: "Smaller file sizes"
    use_for: "Latin-only sites can drop other character sets"

  variable_fonts:
    benefit: "Multiple weights/styles in single file"
    consideration: "May be larger than single weight"

  self_host_vs_google_fonts:
    self_host: "Better performance; eliminates third-party"
    google_fonts: "Simple; broad support"
    recommendation: "Self-host for production"

  limit_weights:
    rule: "Use only weights actually needed"
    typical: "Regular + bold sufficient for most sites"

7. Core Web Vitals Optimization

See framework-pageexperience.md for comprehensive treatment. Key points:

7.1 LCP Optimization

lcp_optimization:

  identify_lcp_element:
    tool: "Chrome DevTools Performance > LCP marker"
    typical: "Hero image or large heading text"

  optimization_strategies:
    image_lcp:
      - Preload the LCP image
      - Optimize image (size, format)
      - Use eager loading
      - CDN delivery
      - Render server-side

    text_lcp:
      - Optimize font loading
      - Preload critical CSS
      - Minimize render-blocking

    server_response:
      - Reduce TTFB
      - Optimize server processing
      - Effective caching

7.2 INP Optimization

inp_optimization:

  reduce_main_thread_work:
    - Code split JavaScript
    - Defer non-critical scripts
    - Web workers for heavy computation

  optimize_event_handlers:
    - Debounce/throttle expensive handlers
    - Use requestIdleCallback for non-urgent work
    - Avoid large synchronous tasks

  third_party_audit:
    - Heavy third-party scripts often cause INP issues
    - Defer or remove problematic scripts

7.3 CLS Optimization

cls_optimization:

  size_attributes:
    images: "Always include width and height attributes"
    embeds: "Reserve space with aspect ratio"

  font_loading:
    issue: "Font swap can cause layout shift"
    fix: "Match fallback font metrics; use size-adjust"

  ads_and_embeds:
    issue: "Late-loading content shifts page"
    fix: "Reserve space proactively"

  dynamic_content:
    rule: "Don't insert above existing content unless triggered by user"

8. Real User Monitoring

8.1 RUM Implementation

rum_options:

  free_tools:
    - Chrome User Experience Report (CrUX)
    - Google Search Console Core Web Vitals
    - Cloudflare Web Analytics (free)

  paid_tools:
    - SpeedCurve
    - Calibre
    - Datadog RUM
    - New Relic Browser
    - Sentry Performance Monitoring

  custom_implementation:
    library: "web-vitals.js"
    pattern: "Send metrics to your analytics"
    benefit: "Custom dashboards"

8.2 Custom Web Vitals Tracking

import { onCLS, onINP, onLCP, onFCP, onTTFB } from 'web-vitals';

function sendToAnalytics({name, value, id}) {
  gtag('event', name, {
    value: Math.round(name === 'CLS' ? value * 1000 : value),
    metric_id: id,
    metric_value: value,
    metric_delta: value,
    non_interaction: true,
  });
}

onCLS(sendToAnalytics);
onINP(sendToAnalytics);
onLCP(sendToAnalytics);
onFCP(sendToAnalytics);
onTTFB(sendToAnalytics);

This sends real user data to GA4 for monitoring.

9. Performance Budget

9.1 Establishing Budget

performance_budget:

  page_weight_targets:
    total: "Under 1MB ideal; 1-2MB acceptable; 2MB+ concerning"
    html: "Under 100KB"
    css: "Under 100KB"
    javascript: "Under 300KB"
    images: "Variable; lazy-load below fold"
    fonts: "Under 100KB total"

  request_count_targets:
    total: "Under 50 ideal; 50-100 acceptable"
    third_party: "Under 10 ideal"

  metric_targets:
    lcp: "Under 2.0s ideal; under 2.5s acceptable"
    inp: "Under 100ms ideal; under 200ms acceptable"
    cls: "Under 0.05 ideal; under 0.1 acceptable"
    ttfb: "Under 600ms ideal; under 800ms acceptable"

9.2 Enforcing Budget

budget_enforcement:

  ci_cd_integration:
    tools: "Lighthouse CI, SpeedCurve, Calibre"
    pattern: "Performance test on every deployment"
    fail_build: "If thresholds exceeded"

  monitoring_alerts:
    pattern: "Alert when metrics regress"
    sensitivity: "Threshold beyond normal variance"

  documentation:
    rule: "Document the budget; share with team"
    review: "Quarterly budget review and adjustment"

10. Audit Mode

#	Criterion	Pass/Fail
PF1	Core Web Vitals targets met (75th percentile)
PF2	TTFB under 800ms
PF3	Hosting appropriate for traffic
PF4	CDN configured and active
PF5	Object cache (Redis) running
PF6	Page cache configured
PF7	Browser cache headers correct
PF8	Images optimized (modern formats, compression, lazy)
PF9	JavaScript minimized and deferred
PF10	CSS optimized (critical inline; rest async)
PF11	Fonts optimized (display swap; preload critical)
PF12	Third-party scripts audited and minimized
PF13	Database optimized
PF14	RUM data collected and monitored
PF15	Performance budget defined
PF16	Regression testing in CI/CD

Score: 16. World-class performance: 14+/16.

11. Common Mistakes

Cheap shared hosting — bottleneck regardless of optimization
No CDN — slow for distant users
No caching layers — every request hits database
Image bloat — unoptimized images dominate page weight
Third-party script overload — heavy widgets, multiple analytics
No font optimization — invisible text or layout shifts
Render-blocking resources — synchronous CSS/JS in head
No lazy loading — loading everything upfront
No RUM — flying blind on real user experience
No performance regression testing — performance drifts over time

End of Framework Document

Companion documents:

framework-pageexperience.md — Core Web Vitals deep dive
framework-imageseo.md — Image-specific optimization
framework-cdn.md — CDN strategy detail
framework-hosting.md — Hosting selection
framework-serverconfig.md — Server configuration

About this framework library

Dev.to republish of a framework from ThatDevPro's SEO + AI engineering library. Canonical source: https://www.thatdevpro.com/insights/framework-performance/

ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Need this framework implemented? See the Engine Optimization service or hire via contact.

Core Web Vitals (LCP, INP, CLS): the page experience playbook

Joseph Anady — Sun, 24 May 2026 01:12:50 +0000

Originally published at thatdevpro.com. Part of ThatDevPro's open SEO + AI framework library. ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.

Core Web Vitals (LCP, INP, CLS), Mobile Optimization, HTTPS, Intrusive Interstitials, and the User-Side Quality Floor

A comprehensive installation and audit reference for page experience — the user-facing performance and usability layer Google uses as a ranking factor and, more importantly, the layer that actually determines whether visitors stay on a page or bounce. Dual-purpose: installation manual and audit document.

Cross-stack implementation note: the code samples in this framework are written in plain HTML for clarity. For React, Vue, Svelte, Next.js, Nuxt, SvelteKit, Astro, Hugo, 11ty, Remix, WordPress, Shopify, and Webflow equivalents of every pattern below, see framework-cross-stack-implementation.md. For pure client-rendered SPAs (no SSR/SSG) see framework-react.md. For Tailwind-specific concerns (purge, dynamic classes, dark-mode CLS, focus accessibility) see framework-tailwind.md.

1. Document Purpose

This is the canonical reference for page experience. Where framework-technicalseo.md covers the bot-facing foundation, this document covers the human-facing one. The two intersect: a slow page is bad for users and bad for crawl budget; an unstable layout is bad for users and bad for INP. Page experience is the discipline of measuring and fixing the metrics Google uses to model what users actually feel.

In 2026, page experience differs from page experience in 2020 in three ways. First, INP (Interaction to Next Paint) replaced FID (First Input Delay) as the responsiveness metric in March 2024 — INP is harder to pass because it measures every interaction, not just the first. Second, mobile-first indexing means mobile vitals are the only vitals that matter for ranking. Third, the threshold for "good" has tightened: Google now expects 75% of page loads to meet all three CWV thresholds at the 75th percentile of real-user data.

1.1 Required Tools

PageSpeed Insights — pagespeed.web.dev — both lab and field data
Chrome User Experience Report (CrUX) — field data source for CWV
Lighthouse (via Chrome DevTools) — lab measurement
WebPageTest — webpagetest.org — deeper waterfall analysis with location/device/connection control
Google Search Console — Core Web Vitals report — sitewide field data
Chrome DevTools Performance panel — interaction profiling for INP
Chrome DevTools Coverage tab — unused CSS/JS detection
Chrome DevTools Network panel — resource waterfall
Real User Monitoring (RUM) — Vercel Speed Insights, Cloudflare Web Analytics, SpeedCurve, Calibre
Web Vitals JS library — web-vitals npm package for custom RUM
GTmetrix — alternative lab + waterfall

1.2 Document Scope

Covers: the three Core Web Vitals (LCP, INP, CLS), mobile usability, HTTPS posture, intrusive interstitials, image optimization for performance, font loading, JavaScript performance, third-party tag management, and validation methodology. Touches but does not exhaust: deeper performance optimization (framework-performance.md), accessibility (framework-accessibility.md), security (framework-security.md), platform-specific tuning (framework-nextjs.md, framework-wordpress.md).

2. Client Variables Intake

domain: ""
hosting: ""                            # Vercel | Netlify | Cloudflare | shared | VPS | dedicated
cdn: ""                                # Cloudflare | Fastly | KeyCDN | Bunny | none
cms_or_framework: ""                   # WordPress | Next.js | Astro | Hugo | Shopify | Webflow | static
current_lcp_p75: 0                     # in milliseconds, from CrUX or RUM
current_inp_p75: 0
current_cls_p75: 0
mobile_score_baseline: 0               # PageSpeed Insights mobile
desktop_score_baseline: 0
known_performance_issues: []
third_party_scripts_inventory: []      # GA4, GTM, ad tags, chat widgets, etc.
hsts_deployed: false
mobile_friendly_test_passes: false

3. Core Web Vitals — The Three Metrics

3.1 LCP — Largest Contentful Paint

The time until the largest visible content element finishes rendering. Measured in seconds.

Thresholds (75th percentile of users):

Good: ≤ 2.5 seconds
Needs improvement: 2.5 – 4.0 seconds
Poor: > 4.0 seconds

What counts as the LCP element?

Usually the hero image or the largest text block. Watch the LCP candidate in DevTools Performance panel — the element flagged with the LCP marker is the one to optimize.

Common LCP causes:

Cause	Fix
Hero image too large / unoptimized	Compress, modern format (WebP/AVIF), `loading="eager"` for hero, `fetchpriority="high"`
Hero image lazy-loaded	Hero image must NOT be lazy-loaded. Lazy-load below-fold only.
Server response slow	Reduce TTFB. Cache, CDN, faster hosting.
Render-blocking CSS/JS	Inline critical CSS, defer non-critical, async third-party
Font swap delays	`font-display: swap`, preload critical fonts
Client-side rendering of hero	Server-render hero content, hydrate after
Layout depends on JS to display	Don't gate hero behind JS execution

Measurement approach:

Lab measurement (Lighthouse, WebPageTest) catches gross issues.
Field measurement (CrUX, RUM) is what Google uses for ranking.
A site can have great lab scores and bad field scores (or vice versa). Both must pass.

3.2 INP — Interaction to Next Paint

The 75th-percentile latency between a user interaction (click, tap, key press) and the next paint reflecting the result. Replaced FID in March 2024.

Thresholds (75th percentile of interactions):

Good: ≤ 200 ms
Needs improvement: 200 – 500 ms
Poor: > 500 ms

Why INP is harder than FID:

FID measured only the first interaction. INP measures every interaction across the page lifecycle and reports the worst (or near-worst) one. A page that responds fast to the first click but stalls on the third scrolls a poor INP.

Common INP causes:

Cause	Fix
Long-running JavaScript on click handler	Break work into smaller tasks; use `requestIdleCallback`; defer non-essential work
Heavy event listener (single handler on document)	Use specific listeners; debounce; avoid synchronous heavy work
Re-render of large component on state change	Virtualize lists; memoize; reduce render scope
Third-party scripts blocking main thread	Audit and defer/remove
Layout thrashing in interaction handler	Batch reads/writes; avoid forcing layout in tight loops
Animations on the main thread	Move to CSS transforms or compositor thread

INP attribution:

Use Chrome DevTools Performance panel. Record an interaction. The "Interaction" track shows input delay + processing time + presentation delay. Identify which is dominant and fix accordingly.

3.3 CLS — Cumulative Layout Shift

A measure of visual stability — how much the page jumps around as it loads. Unitless score; lower is better.

Thresholds (75th percentile of users):

Good: ≤ 0.1
Needs improvement: 0.1 – 0.25
Poor: > 0.25

Common CLS causes:

Cause	Fix
Images without explicit dimensions	Always set `width` and `height` attributes (or CSS aspect-ratio)
Embeds (videos, iframes) without dimensions	Same — reserve space
Web fonts causing reflow when they load	`font-display: optional` or `swap` with size-adjusted fallback
Ads injecting late and pushing content	Reserve ad slot dimensions; lazy-render only below fold
Dynamic content injected above existing content	Inject below or in reserved space
CSS loaded late changing styles	Inline critical CSS for above-fold

The cookie banner exception:

Cookie consent banners that appear after a delay are a major CLS source. Either render the banner with reserved space from page load, or apply it as a fixed-position overlay that doesn't shift content.

4. Mobile Usability

Since 2023 Google indexes the mobile version of every site. Mobile vitals are the only vitals that matter for ranking.

4.1 The Viewport Tag

Every page must include:

<meta name="viewport" content="width=device-width, initial-scale=1.0">

Without this, mobile browsers render the page at desktop width and zoom out, failing nearly every mobile usability check.

4.2 Tap Target Size

Tap targets (buttons, links) must be at least 48 × 48 CSS pixels. Targets smaller than 48px or with less than 8px spacing between them fail mobile usability.

.btn, .link-as-button {
  min-height: 48px;
  min-width: 48px;
  padding: 12px 20px;
}
nav a {
  padding: 12px 16px;  /* generous click area */
}

4.3 Text Size

Body text on mobile should be at least 16px. Smaller text triggers automatic zoom on iOS form fields and fails mobile usability.

4.4 Content Width

Content must fit the viewport. Horizontal scrolling on mobile fails the test.

img, video, iframe { max-width: 100%; height: auto; }
.container { max-width: 100vw; overflow-x: hidden; }

4.5 The Mobile-Friendly Test

Run every important page through search.google.com/test/mobile-friendly (deprecated; replaced by URL Inspection in GSC). The Lighthouse mobile audit covers most of the same checks.

5. HTTPS

Page experience requires HTTPS. The full implementation is in framework-technicalseo.md Section 11; the page-experience-relevant pieces:

Valid certificate (no browser warning)
HSTS deployed
No mixed content (HTTPS page loading HTTP resources)
HTTP/2 or HTTP/3 enabled (performance benefit, not strict requirement)

6. Intrusive Interstitials

Pop-ups, overlays, and interstitials that block content access on mobile are a ranking penalty. The penalty applies to:

Pop-ups covering the main content immediately on page load
Standalone interstitials the user must dismiss before reaching the page
Above-the-fold layouts where the visible portion is dominated by an ad or pop-up

Exempted:

Login dialogs on pages that legitimately require login
Age verification on pages that legitimately require it
Cookie consent banners (provided they don't dominate the viewport)
Small banner ads that don't dominate the visible area

Common offenders:

Email signup overlays triggered immediately on landing
"Subscribe to our newsletter" full-screen modals
Discount-offer pop-ups before user has read anything
Chat widgets that auto-expand to fill the screen

The fix is timing and proportion. Show the overlay after engagement (15+ seconds, 50%+ scroll, exit intent) and keep it under ~30% of the viewport.

7. Image Optimization for Performance

Images are usually the LCP element and often the biggest CLS contributor. Optimize aggressively.

7.1 Format Selection

Format	Use case
AVIF	Best compression. Photographic content. ~95% browser support in 2026.
WebP	Excellent compression. Universal fallback for AVIF.
JPEG	Legacy fallback. Photographic content where AVIF/WebP unavailable.
PNG	Only when alpha transparency required. Use PNG-8 where possible.
SVG	Logos, icons, illustrations. Inline when small (<2KB).
GIF	Never. Use MP4 or WebM.

The <picture> pattern serves the right format per browser:

<picture>
  <source srcset="hero.avif" type="image/avif">
  <source srcset="hero.webp" type="image/webp">
  <img src="hero.jpg" alt="..." width="1200" height="800" loading="eager" fetchpriority="high">
</picture>

7.2 Responsive Images

Serve different sizes per viewport:

<img src="hero-800.jpg"
     srcset="hero-400.jpg 400w, hero-800.jpg 800w, hero-1200.jpg 1200w, hero-1600.jpg 1600w"
     sizes="(max-width: 768px) 100vw, 50vw"
     alt="..." width="1200" height="800">

7.3 Lazy Loading

<img src="..." loading="lazy" alt="..." width="..." height="...">

Critical: the LCP image must NOT be lazy-loaded. Lazy-load below-the-fold images only. Use loading="eager" (or omit; eager is default) for the hero image and add fetchpriority="high" to signal priority.

7.4 Dimensions Always

Every <img>, <video>, and <iframe> requires width and height attributes (or CSS aspect-ratio). This reserves layout space and prevents CLS.

7.5 Image CDN

For sites with many images, an image CDN (Cloudinary, imgix, Cloudflare Images, Vercel Image Optimization, Next.js next/image) provides:

On-the-fly format conversion
On-the-fly resizing
Automatic AVIF/WebP serving
Caching at the edge

Cross-reference: framework-imageseo.md for SEO-side image considerations.

8. Font Loading

Fonts are a frequent LCP and CLS culprit.

8.1 font-display

Always specify font-display:

@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter.woff2') format('woff2');
  font-display: swap;  /* show fallback immediately, swap when font loads */
}

Value	Behavior
`swap`	Show fallback immediately; swap when web font loads. CLS risk if fallback metrics differ.
`optional`	Use web font only if loaded within 100ms. Otherwise stick with fallback. Best for CLS.
`fallback`	100ms blocking, 3s swap window, then fallback locked in. Compromise.
`block`	Up to 3s blocking. Avoid.

8.2 Preload Critical Fonts

<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>

Only for fonts used above the fold. Preloading too many resources hurts LCP.

8.3 Font Subsetting

Modern Google Fonts are typically already subset. Self-hosted custom fonts: subset to the character set you actually use (Latin, Cyrillic, etc.). A 200KB unsubset font becomes 30KB after Latin subset.

8.4 Variable Fonts

Variable fonts (Inter, Fraunces, etc.) deliver multiple weights from one file. Net win at scale.

8.5 size-adjust and Fallback Metrics

Match fallback font metrics to web font to eliminate CLS on swap:

@font-face {
  font-family: 'fallback-inter';
  src: local('Arial');
  size-adjust: 107%;
  ascent-override: 90%;
  descent-override: 22%;
  line-gap-override: 0%;
}
body { font-family: 'Inter', 'fallback-inter', sans-serif; }

The fontaine library automates this for popular fonts.

9. JavaScript Performance

9.1 Bundle Size Budget

For mobile-first 2026:

Resource	Target
Initial JS bundle (compressed)	< 100 KB
Initial CSS (compressed)	< 30 KB
Initial HTML	< 50 KB
Total page weight (initial load)	< 500 KB
Total page weight (with all resources)	< 1.5 MB

These are aggressive targets and not always achievable, but they're the bar.

9.2 Code Splitting

Load only what's needed for the initial route. Defer route-specific bundles:

// Next.js dynamic import
const HeavyChart = dynamic(() => import('./HeavyChart'), { ssr: false });

9.3 Tree Shaking

Modern bundlers (esbuild, Vite, Rollup, Turbopack) tree-shake automatically. Verify by checking final bundle for unused imports — Coverage tab in Chrome DevTools shows unused JS.

9.4 Defer and Async

<!-- Async: download in parallel, execute as soon as ready -->
<script src="analytics.js" async></script>

<!-- Defer: download in parallel, execute in order after HTML parsing -->
<script src="enhancement.js" defer></script>

Most third-party scripts should be async or defer. Inline blocking <script> tags are the worst case for LCP.

9.5 Long Tasks

A "long task" is any JS execution over 50ms. Long tasks block input and hurt INP. Find them in Chrome DevTools Performance panel — they appear as red-flagged blocks. Common sources:

Heavy initial render (React/Vue hydration)
Large state updates
Synchronous loops over big arrays
Third-party SDK initialization

Break into smaller tasks with setTimeout(0), requestIdleCallback, or scheduler.yield.

10. Third-Party Tag Management

Most page-experience problems on real client sites trace to third-party scripts: analytics, ads, chat widgets, A/B testing tools, marketing automation pixels.

10.1 The Audit

For every site, inventory every third-party script and ask:

What does it do?
Does the client actually use the data it produces?
What's its INP impact?
Can it be loaded later (defer, async, post-interaction)?
Is there a lighter alternative?

Common removals after audit:

Old A/B testing platforms no longer in use
Multiple competing analytics (GA4 + Adobe + Heap + Hotjar + Mixpanel)
Chat widgets the client doesn't monitor
Pixel tags from agencies long since departed
"Just in case" tags whose purpose nobody remembers

10.2 Tag Manager Hygiene

If using GTM:

Audit triggers — many fire on every page load even when only relevant on specific pages
Audit tags — disable or remove unused tags
Use built-in tag templates rather than custom HTML where possible
Set "Wait for tags" thresholds that don't block CWV

10.3 The Self-Hosted Pattern

For high-impact third-party scripts (especially analytics), self-hosting can reduce DNS, TCP, and TLS overhead. Plausible, Fathom, Cloudflare Web Analytics all support self-hosting.

For Google Analytics, gtag.js itself can't be self-hosted easily, but the analytics.js payload can be proxied via Cloudflare Worker / nginx to reduce third-party origin connections.

10.4 Privacy and Performance

EU privacy law (GDPR) and US state laws (CCPA) increasingly require consent before tags fire. The consent gate has a side benefit: tags don't load until interaction, which is great for CWV. Consent Mode v2 in GTM is the conventional implementation.

11. Server-Side Performance

11.1 Time to First Byte (TTFB)

While not a CWV metric directly, TTFB feeds into LCP. Good TTFB is under 600ms; great is under 200ms.

Cause	Fix
Slow database queries	Add indexes, cache, denormalize
Slow templating / rendering	Cache rendered output (HTML cache, full-page cache)
Slow PHP / Python / Node app	Profile, optimize hot paths
Distant origin server	Add CDN, choose hosting near user base
Cold-start serverless	Use provisioned concurrency or always-warm tier

11.2 Caching Layers

In order of preference (cheapest to most expensive lookup):

CDN edge cache — Cloudflare, Fastly, etc. — milliseconds, free at scale
Application-level page cache — WP Super Cache, Vercel ISR, Astro static — single-digit ms
Object cache — Redis, Memcached — for query results, session data
Database query cache — built into MySQL/PostgreSQL — invalidate carefully
Database itself — last resort

11.3 HTTP/2, HTTP/3, Brotli

HTTP/2 — supported everywhere, multiplexes connections.
HTTP/3 — emerging; supported by Cloudflare, Fastly. Minor performance gain on lossy mobile networks.
Brotli compression — better than gzip for text resources. Enable at server or CDN level.

12. Real User Monitoring (RUM)

Lab tests catch some problems. Field data catches the rest. Set up RUM on every client site.

12.1 Free Options

Google Search Console — Core Web Vitals report — sitewide CrUX data, no setup
Cloudflare Web Analytics — free, privacy-respecting, includes CWV
Vercel Speed Insights — free for Vercel-hosted sites

12.2 Paid Options

SpeedCurve — comprehensive RUM with synthetic monitoring
Calibre — performance budgets, alerting
Pingdom RUM — basic monitoring

12.3 DIY with web-vitals

For full control, use the web-vitals library:

import { onLCP, onINP, onCLS } from 'web-vitals';

function sendToAnalytics({name, value, id}) {
  navigator.sendBeacon('/rum', JSON.stringify({name, value, id, url: location.href}));
}

onLCP(sendToAnalytics);
onINP(sendToAnalytics);
onCLS(sendToAnalytics);

Ship to your own endpoint and analyze with whatever tooling suits.

13. The Validation Workflow

For every client engagement:

Baseline (week 0) — record LCP, INP, CLS at 75th percentile from PageSpeed Insights field data, GSC CWV report, and any RUM available. Document mobile and desktop separately.
Diagnose — Lighthouse audit on representative pages. WebPageTest for waterfall. Identify top 5 contributing issues.
Fix — implement changes. Verify in lab tests first.
Measure — wait 28 days for CrUX field data to update (CrUX uses 28-day rolling window).
Iterate — if not yet "good," continue diagnosing.
Monitor — RUM and GSC CWV report ongoing.

14. Audit Mode

#	Criterion	Pass/Fail
PE1	Mobile LCP at 75th percentile under 2.5s
PE2	Mobile INP at 75th percentile under 200ms
PE3	Mobile CLS at 75th percentile under 0.1
PE4	Desktop LCP under 2.5s, INP under 200ms, CLS under 0.1
PE5	Lighthouse mobile performance score ≥ 90 on representative pages
PE6	GSC Core Web Vitals report shows zero "poor" URLs
PE7	Viewport meta tag present on every page
PE8	All tap targets ≥ 48 × 48 CSS pixels
PE9	Body text ≥ 16px on mobile
PE10	No horizontal scrolling on mobile
PE11	Mobile-Friendly Test (or URL Inspection) passes
PE12	HTTPS enforced; HSTS deployed
PE13	No mixed content on any page
PE14	No intrusive interstitials on mobile
PE15	Hero image NOT lazy-loaded; has `fetchpriority="high"`
PE16	All images have `width` and `height` (or aspect-ratio)
PE17	Below-fold images use `loading="lazy"`
PE18	Modern image formats (AVIF / WebP) served via `<picture>`
PE19	Responsive images via `srcset` and `sizes`
PE20	Fonts use `font-display: swap` or `optional`
PE21	Critical fonts preloaded; non-critical not
PE22	Initial JS bundle < 100KB compressed
PE23	Third-party scripts deferred or async (no inline blocking)
PE24	Third-party tag inventory documented and audited
PE25	TTFB at 75th percentile under 600ms
PE26	Brotli or gzip compression on all text resources
PE27	HTTP/2 or HTTP/3 enabled
PE28	Edge / CDN caching layer present
PE29	RUM tooling deployed (any of: GSC CrUX, Vercel Insights, Cloudflare Web Analytics, custom web-vitals)
PE30	No long tasks > 100ms on initial interaction (DevTools Performance)

Score: 30. World-class: 28+/30.

15. Common Mistakes

Lazy-loading the hero image. Slows LCP dramatically.
No image dimensions. Largest CLS source.
Cookie banner injected late, pushing content. Reserve space or use overlay.
Multiple analytics SDKs running concurrently. Pick one, remove the rest.
Synchronous third-party scripts. Use async / defer.
Optimizing only desktop. Mobile is what Google ranks.
Lab scores look great, field scores poor. Field data is what counts.
Long-running click handlers. INP killer; break into chunks.
font-display: block (or unspecified, which defaults to block). Hides text until font loads.
JavaScript-heavy "interactive" landing pages with sub-second blocking work. INP catastrophe on mid-tier mobile devices.
No CDN. Origin server in one region serves users globally; LCP suffers everywhere except near the origin.
Render-blocking CSS. Inline critical above-fold CSS; defer the rest.
Web fonts loading from external CDN with no preconnect. Add <link rel="preconnect"> for font origin.
Poll-based polling JavaScript. Use server-sent events or WebSockets.
Unused JS frameworks loaded. "We're using React for one widget" but shipping the whole bundle.
<iframe> embeds without dimensions. Major CLS source.
Treating CWV as a checkbox once and never again. CWV regress over time as features are added.

16. Maintenance

Weekly:

Spot-check PageSpeed Insights for representative pages
Review GSC Core Web Vitals report for new errors

Monthly:

Sitewide GSC CWV review
RUM dashboard review
New third-party scripts audit
Lighthouse audit on top 10 pages

Quarterly:

Comprehensive performance audit (WebPageTest + Lighthouse)
Third-party tag inventory refresh
Image/font/CSS/JS budget review
CDN configuration review
Cache hit ratio review

Annually:

Full performance budget reassessment
Hosting/CDN evaluation
New CWV metric watch (Google revises CWV periodically)
Major framework / CMS update planning

17. Companion Documents

framework-technicalseo.md — Indexing, HTTPS, server-side foundation
framework-performance.md — Deeper performance optimization beyond CWV
framework-imageseo.md — Image SEO including format and alt text
framework-mobileseo.md — Mobile-specific deep dive
framework-accessibility.md — A11y patterns (overlap with mobile usability)
framework-security.md — HTTPS, HSTS, security headers
framework-nextjs.md — Next.js performance patterns
framework-wordpress.md — WordPress performance patterns
framework-headless.md — Headless architecture performance
framework-cro.md — Performance and conversion correlation

Document version: 1.0
Last updated: 2026-05-05
Owner: Joseph W. Anady — ThatDeveloperGuy — SDVOSB

About this framework library

This article is the Dev.to republish of a framework reference document from ThatDevPro's SEO + AI engineering library. Canonical source: https://www.thatdevpro.com/insights/framework-pageexperience/

ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio operating from Cassville, Missouri. The studio runs the full 14-tier Engine Optimization stack and ships open-source tooling for AI citation engineering.

Companion 14-tier Engine Optimization stack (each tier is its own article):

Need this framework implemented on your site? See the Engine Optimization service or hire through ThatDevPro contact.

Technical SEO: crawling, indexing, JS rendering

Joseph Anady — Sun, 24 May 2026 01:12:31 +0000

Originally published at thatdevpro.com. Part of ThatDevPro's open SEO + AI framework library. ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.

Crawlability, Indexing, Canonicalization, Redirects, URL Structure, and the Bot-Facing Foundation

A comprehensive installation and audit reference for technical SEO — the bedrock layer that determines whether search engines and AI crawlers can discover, render, and index a site at all. Every other framework in this library assumes the technical foundation works. This document specifies what "works" means and how to verify it. Dual-purpose: installation manual and audit document.

Cross-stack implementation note: the code samples in this framework are written in plain HTML for clarity. For React, Vue, Svelte, Next.js, Nuxt, SvelteKit, Astro, Hugo, 11ty, Remix, WordPress, Shopify, and Webflow equivalents of every pattern below, see framework-cross-stack-implementation.md. For pure client-rendered SPAs (no SSR/SSG) see framework-react.md. For Tailwind-specific concerns (purge, dynamic classes, dark-mode CLS, focus accessibility) see framework-tailwind.md.

1. Document Purpose

This is the canonical reference for technical SEO. Content quality, authority signals, schema markup, and AI optimization are all wasted if a crawler cannot reach a page, cannot render it, or cannot decide which version to index. Technical SEO is the prerequisite. It is not glamorous. It is not optional.

In 2026, technical SEO has changed in three ways since 2020. First, JavaScript rendering is no longer the bleeding-edge concern — Google renders JS reliably and other major crawlers (Bingbot, GPTBot, ClaudeBot, PerplexityBot, Applebot) have caught up to varying degrees. Second, the bot landscape exploded: a 2026 site receives traffic from a dozen named AI crawlers in addition to the four major search engines, and robots.txt policy is now an editorial decision, not a technical default. Third, indexing has become more selective — Google indexes a smaller percentage of crawled URLs than it did a decade ago, so wasting crawl budget on duplicate, parameterized, or thin URLs has direct cost.

1.1 Required Tools

Google Search Console — search.google.com/search-console — coverage, sitemaps, URL inspection
Bing Webmaster Tools — www.bing.com/webmasters — Bing-specific coverage and IndexNow submission
Screaming Frog SEO Spider — desktop crawler, free up to 500 URLs, paid for unlimited
Sitebulb — desktop crawler, alternative to Screaming Frog with stronger reporting
Ahrefs Site Audit / Semrush Site Audit — cloud-based crawlers with historical tracking
Google Rich Results Test — search.google.com/test/rich-results — render + schema validation
Google Lighthouse — Chrome DevTools performance/SEO audit
GTmetrix / WebPageTest — performance and waterfall analysis
curl / httpie — manual header inspection
Cloudflare / nginx access logs — server-level crawl observation
IndexNow — www.indexnow.org — push-based indexing for Bing, Yandex, Naver

1.2 Document Scope

Covers: crawl access, robots.txt, XML sitemaps, canonicalization, redirects, URL structure, status codes, JS rendering, mobile-first indexing, HTTPS posture, hreflang, and crawler observability. Touches but does not exhaust: page experience (own framework: framework-pageexperience.md), schema (framework-schema.md), internal linking (framework-internallinking.md), security (framework-security.md).

2. Client Variables Intake

domain_apex: ""
www_or_non_www_canonical: ""           # decide which is canonical
http_or_https: "https"                 # always https in 2026
trailing_slash_policy: ""              # with-slash | without-slash
url_case_policy: "lowercase"
cms_or_framework: ""                   # WordPress | Next.js | Astro | Hugo | Shopify | Webflow | static
hosting_environment: ""
cdn: ""                                # Cloudflare | Fastly | none
search_console_verified: false
bing_webmaster_verified: false
indexnow_key_deployed: false
known_indexing_issues: []
recent_migrations: []
international_targets: []              # if any hreflang need

3. Crawl Access Layer

3.1 robots.txt

The robots.txt file at the domain root tells crawlers which paths they may request. It is advisory, not a security mechanism — anything genuinely sensitive belongs behind authentication, not behind a Disallow rule.

Minimum viable robots.txt for a production site:

User-agent: *
Allow: /
Disallow: /wp-admin/
Disallow: /staging/
Disallow: /*?*sessionid=
Disallow: /*?*utm_*

Sitemap: https://example.com/sitemap.xml

Required validations:

The file is served at /robots.txt with Content-Type: text/plain and HTTP 200.
It does NOT block CSS, JS, or image directories. Googlebot needs those to render.
It does NOT block fonts (/fonts/, /assets/fonts/) or web manifest assets.
The Sitemap directive uses an absolute URL.
Wildcards (*) are used sparingly and tested in GSC's robots tester before deploy.

AI crawler policy (2026 baseline):

In 2026, the question is no longer "do we block AI crawlers" but "which AI crawlers do we want citing us, and which do we want to block." A typical client-facing posture:

# AI search crawlers — usually allow (citation traffic)
User-agent: GPTBot
Allow: /

User-agent: ClaudeBot
Allow: /

User-agent: PerplexityBot
Allow: /

User-agent: Google-Extended
Allow: /

# Aggressive scrapers — block by default unless client requests otherwise
User-agent: AhrefsBot
Disallow: /

User-agent: SemrushBot
Disallow: /

User-agent: MJ12Bot
Disallow: /

Cross-reference: framework-aicitations.md for the full AI-crawler matrix.

3.2 X-Robots-Tag

For non-HTML resources (PDFs, images, JSON files) that should not be indexed, X-Robots-Tag is the only signal. Set via server config:

# nginx
location ~* \.(pdf|json)$ {
  add_header X-Robots-Tag "noindex, nofollow";
}

For HTML pages, <meta name="robots"> is preferred because it is more visible to humans editing pages.

3.3 Crawl Budget

Crawl budget is the number of URLs Googlebot crawls in a given period. For sites under ~50,000 URLs this rarely matters. Above that, crawl-budget waste shows as:

Many URLs in GSC's "Crawled — currently not indexed"
Many URLs in "Discovered — currently not indexed"
Slow propagation of new content to the index
Frequent crawls of low-value parameterized URLs

Crawl budget conservation:

Block parameterized/sessioned URLs in robots.txt
410 truly dead URLs (faster than 404 to be removed from crawl)
Reduce internal links to low-value pages
Use noindex on pages that should not be indexed (404 templates, search result pages, tag archives with thin content)
Use a clean XML sitemap so the crawler has a prioritized list

4. Indexing Layer

4.1 The Two-Step Process

Indexing is two steps, not one:

Discovery and crawl — the bot finds the URL (sitemap, link, IndexNow ping) and requests it.
Indexing — the bot parses the response, decides whether to add it to the index, and what to associate with it.

A page can be crawled but not indexed. A page can be in the index but not ranked. These are distinct states with distinct fixes.

4.2 Index Status in Google Search Console

Use Coverage (now Pages) report. The buckets:

Status	Meaning	Action
Indexed	In Google's index	Monitor for unexpected changes
Indexed, not submitted in sitemap	Found via links, not in sitemap	Add to sitemap if it should be indexed
Crawled — currently not indexed	Crawled but Google chose not to index	Improve content quality, add internal links, check duplication
Discovered — currently not indexed	Found but not yet crawled	Often crawl-budget signal; check site authority + reduce low-value URLs
Excluded by 'noindex' tag	Intentionally excluded	Verify intent
Page with redirect	Redirected; not indexed itself	Verify the redirect target is indexed
Duplicate, Google chose different canonical	Google ignored your canonical	Check internal linking + canonical signals consistency
Soft 404	Returns 200 but content looks like a 404 page	Either return real 404 or fix the page
Server error (5xx)	Crawl failed	Fix the server error

4.3 IndexNow

IndexNow is a push-based indexing protocol supported by Bing, Yandex, Seznam, and Naver (not Google). When a URL changes, you POST it to IndexNow and supported engines crawl within minutes instead of days.

Implementation:

Generate an API key (random 32-character string)
Place the key as /{key}.txt at the domain root with the key as its content
POST URL changes to https://api.indexnow.org/indexnow:

POST /indexnow HTTP/1.1
Host: api.indexnow.org
Content-Type: application/json

{
  "host": "example.com",
  "key": "abc123...",
  "keyLocation": "https://example.com/abc123.txt",
  "urlList": [
    "https://example.com/new-page/",
    "https://example.com/updated-page/"
  ]
}

For WordPress, plugin support exists. For Next.js / static sites, integrate as a build-time hook.

4.4 Mobile-First Indexing

Since 2023, Google indexes the mobile version of every site. The desktop version is largely ignored for ranking. Verify:

All content visible on mobile (not hidden behind "click to expand" with mobile-only display:none)
Structured data identical on mobile and desktop
Meta tags identical on mobile and desktop
Internal linking identical (no mobile-only menu omitting key links)
Images load on mobile (no desktop-only assets)

5. Canonicalization

5.1 Why Canonicalization Matters

Modern sites generate many URLs that resolve to the same content:

https://example.com/page and https://example.com/page/
https://example.com/page and https://www.example.com/page
https://example.com/page?utm_source=email
https://example.com/PAGE (some servers serve the same content for any case)
https://example.com/page?session=abc123

Without explicit canonical signals, Google picks one and may not pick the one you want. Ranking signals split across variants. Indexing decisions become inconsistent.

5.2 Canonical Signal Stack

Canonical signals reinforce each other. Use all of them:

<link rel="canonical" href="..."> — the explicit declaration. Self-referential on the canonical URL itself.
301 redirects — for true duplicates, redirect non-canonical to canonical (preferred over rel=canonical when content is genuinely identical).
Internal linking — every internal link points to the canonical URL, never to a redirected variant.
XML sitemap — only canonical URLs appear in the sitemap.
hreflang annotations — when present, must reference canonical URLs only.
HTTP Link header — equivalent to rel=canonical, used for non-HTML resources.

If these signals disagree, Google picks one and ignores the rest. Consistency is the rule.

5.3 Common Canonicalization Mistakes

Canonical to a redirect target. Always canonical to the URL that returns 200, never to one that 301s.
Cross-domain canonical without authority. You can canonical mirror.example.com to example.com, but canonicals across unrelated domains are usually ignored.
Self-canonical with parameters present. A URL like /page?utm_source=x should canonical to /page (no parameters), not self-canonical.
Conflicting canonicals between hreflang clusters. Each hreflang cluster member must canonical to itself, not to an English default.
HTTP version canonicalizing to HTTPS but not redirecting. Use a 301 plus self-canonical on HTTPS, not just rel=canonical.

5.4 Trailing Slash and Case

Pick one and enforce it sitewide via 301 redirect. Do not rely on canonicals alone — redirects collapse the duplication, canonicals only signal it.

# nginx — enforce trailing slash + lowercase
rewrite ^/(.*[A-Z]+.*)$ /$1 permanent;  # would need lua/regex helper
location / {
  try_files $uri $uri/ =404;
}

For Next.js, set trailingSlash: true (or false) in next.config.js and stick with it. Mixing breaks canonicalization.

6. Redirects

6.1 Status Codes

Code	Use case
301 Moved Permanently	The URL has permanently moved. Passes ranking signals. Default for migrations.
302 Found	Temporary redirect. Use only for actual temporary moves (A/B tests, seasonal pages). Misused 302s leak link equity.
307 Temporary Redirect	Like 302 but preserves request method. Rare in SEO context.
308 Permanent Redirect	Like 301 but preserves request method. Functionally equivalent for SEO.
410 Gone	Page is permanently removed and not coming back. Faster removal from index than 404.
451 Unavailable for Legal Reasons	Use when content removed for legal reasons (DMCA, jurisdictional).

6.2 Redirect Chains

A chain is A → B → C. Eliminate them. Every redirect should be a single hop to the final URL. Chains:

Waste crawl budget
Add latency for users
Risk dropping signals at each hop
Break when one link in the chain dies

Maintain a redirect map spreadsheet for any migration. After deploying redirects, crawl the site and verify zero chains.

6.3 Redirect Implementation Layers

In order of preference:

Server config (nginx, Apache, Cloudflare Rules) — fastest, most reliable, executed before page load.
CMS-level redirect plugin — fine for low-volume changes, performance penalty at scale.
JavaScript redirects — last resort. Slow, fragile, sometimes ignored by crawlers.
Meta refresh redirects — never use. Treated as low-quality signal.

6.4 The Migration Redirect Pattern

When migrating URL structure:

Generate a 1:1 map of old URL → new URL for every indexed page.
Implement 301s in server config before deploy.
Update internal links to point to new URLs (do not rely on the redirect).
Update XML sitemap to list only new URLs.
Submit new sitemap in GSC.
Monitor GSC's Coverage report for 30-90 days.
Keep redirects in place permanently — old URLs have inbound links from sites you don't control.

Cross-reference: framework-migration.md for full migration methodology.

7. URL Structure

7.1 The Eight URL Rules

Lowercase. Always.
Hyphens between words. Not underscores. Not camelCase.
Under 60 characters when possible. Long URLs index fine but truncate in SERPs.
No stop words unless meaningful. /the-best-web-hosting/ reads better as /best-web-hosting/.
Descriptive, not numeric. /blog/post-1234/ is opaque; /blog/local-seo-checklist/ is meaningful.
No file extensions where avoidable. /about/ over /about.html or /about.php.
One canonical separator policy. Don't mix /category/post/ and /category-post/.
Stable. Once published, do not change a URL without redirecting.

7.2 URL Hierarchy and Crawl Depth

A URL's path depth (/a/b/c/d/page/) is independent of crawl depth (clicks from homepage). Crawl depth matters for SEO; path depth is only loosely related.

Target: every important page reachable in 3 clicks or fewer from the homepage. Verify with Sitebulb's Crawl Depth report.

Cross-reference: framework-internallinking.md for hub-and-spoke architecture.

7.3 Parameter Handling

URL parameters create duplication. Strategies:

Block in robots.txt — for tracking parameters that should never be indexed (?utm_*, ?sessionid=, ?fbclid=).
Canonical to parameterless version — for sort/filter parameters where the parameterless version is canonical.
Self-canonical with noindex — for parameter combinations that are unique pages but should not be indexed.
GSC URL Parameter tool — deprecated as of 2022. Use canonical signals instead.

8. XML Sitemaps

8.1 What Belongs in a Sitemap

Only canonical, indexable, 200-status URLs that you want indexed. Everything else stays out:

Excluded: noindex pages, redirected URLs, 4xx URLs, duplicate URLs, parameterized variants
Excluded: pagination URLs (page/2/, page/3/) unless you have a strategic reason
Excluded: search result pages, login pages, account pages

8.2 Sitemap Structure

For sites under 50,000 URLs, a single sitemap is fine. Above that, use a sitemap index:

<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
    <loc>https://example.com/sitemap-pages.xml</loc>
    <lastmod>2026-05-05</lastmod>
  </sitemap>
  <sitemap>
    <loc>https://example.com/sitemap-posts.xml</loc>
    <lastmod>2026-05-05</lastmod>
  </sitemap>
  <sitemap>
    <loc>https://example.com/sitemap-images.xml</loc>
    <lastmod>2026-05-05</lastmod>
  </sitemap>
</sitemapindex>

Per-sitemap entry:

<url>
  <loc>https://example.com/page/</loc>
  <lastmod>2026-05-05</lastmod>
</url>

<changefreq> and <priority> are ignored by Google. <lastmod> is honored when accurate; if you fake it (always = today), Google starts ignoring it.

8.3 Specialized Sitemaps

Image sitemap — for image-heavy sites; accelerates Image Pack inclusion.
Video sitemap — required for native video content; alternative to VideoObject schema.
News sitemap — for sites approved for Google News; only includes articles from the last 48 hours.
hreflang sitemap — programmatic alternative to inline hreflang tags.

8.4 Submission

Submit sitemap URL in GSC and Bing Webmaster Tools.
Reference sitemap URL in robots.txt (Sitemap: https://...).
For large sites, ping the sitemap when content changes (or use IndexNow).

9. Status Codes — The Operator's Reference

Beyond redirects, status codes communicate site health to crawlers. The full inventory worth knowing:

9.1 2xx Success

200 OK — page delivered. Default for healthy URLs.
201 Created — resource created (POST endpoints).
204 No Content — success, no body returned.
206 Partial Content — range request (video, large download resume).

9.2 3xx Redirection

301 / 308 — permanent. Default for migrations.
302 / 307 — temporary. Use sparingly.
304 Not Modified — conditional GET succeeded; client uses its cached copy. Healthy at scale.

9.3 4xx Client Errors

400 Bad Request — malformed request. Usually bot or attack traffic.
401 Unauthorized — auth required.
403 Forbidden — access denied. If on a public page, check nginx/htaccess rules.
404 Not Found — URL does not exist. Track in GSC and either redirect or 410.
405 Method Not Allowed — right URL, wrong verb. Common form-handler misconfiguration.
410 Gone — permanently removed. Faster removal from index than 404.
429 Too Many Requests — rate limited. Usually bot abuse.
451 Unavailable for Legal Reasons — content removed for legal cause.

9.4 5xx Server Errors

500 Internal Server Error — application crash.
502 Bad Gateway — nginx couldn't reach upstream.
503 Service Unavailable — maintenance or overload. Use Retry-After header.
504 Gateway Timeout — upstream too slow.

5xx codes are urgent. Sustained 5xx during a Googlebot crawl drops pages from the index.

10. JavaScript Rendering

10.1 The Two-Wave Indexing Model (Mostly Obsolete)

For years, Google's two-wave model meant JS sites were indexed late: the first wave indexed HTML, the second wave indexed rendered content days later. As of 2025, Google renders the vast majority of pages within hours of the first crawl. The two-wave problem is no longer a structural blocker for most sites.

It is still real for AI crawlers. GPTBot, ClaudeBot, and PerplexityBot do not all render JS reliably. For AI search visibility, server-side rendered content matters more than for traditional Google SEO.

10.2 Rendering Strategy by Content Type

Content type	Recommended rendering
Marketing pages, landing pages	SSG or SSR (no client-side rendering for primary content)
Blog posts, articles	SSG
Ecommerce product pages	SSR with hydration
Logged-in user pages	CSR is fine (these aren't indexed anyway)
Real-time data displays	SSR shell + client hydration

10.3 Validation

Use Google's Mobile-Friendly Test or URL Inspection tool's "Test Live URL" to see what Googlebot actually renders. If primary content is missing, the page is not effectively indexed even if it returns 200.

For AI crawler visibility, curl -A "GPTBot" https://example.com/page and inspect the HTML response body. If the content is in <noscript> only or arrives via fetch/XHR, AI crawlers miss it.

Cross-reference: framework-headless.md and framework-nextjs.md for framework-specific rendering patterns.

11. HTTPS

In 2026, HTTPS is non-negotiable. HTTP-only sites suffer ranking penalties, browser warnings, and lost trust signals.

11.1 Required Configuration

TLS 1.2 minimum, TLS 1.3 preferred.
Valid certificate from a recognized CA (Let's Encrypt, Cloudflare, paid).
HSTS header: Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
HSTS preload list submission for high-value domains: hstspreload.org
HTTP-to-HTTPS 301 redirect, single hop.
Canonical and internal links use HTTPS exclusively.
Mixed-content audit: no HTTP resources loaded on HTTPS pages.

11.2 Certificate Maintenance

Auto-renewal via Let's Encrypt or hosting provider.
Monitor expiration via UptimeRobot or similar.
Verify certificate transparency log entries via crt.sh.

Cross-reference: framework-security.md for broader security posture.

12. International / hreflang

For sites targeting multiple languages or regions, hreflang annotations tell Google which version to show which user.

12.1 hreflang Implementation

Three valid placement methods, listed in order of preference:

HTTP Link header — non-HTML resources, full programmatic control.
XML sitemap hreflang — preferred for large sites; centralizes all annotations in one place.
<link rel="alternate"> tags in <head> — most common; works but harder to maintain at scale.

<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/page/">
<link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/page/">
<link rel="alternate" hreflang="x-default" href="https://example.com/page/">

12.2 hreflang Rules

Every page in a cluster must reference every other page in the cluster (return-link requirement).
Every page must self-reference.
Use x-default for the fallback when no language matches.
Use ISO 639-1 language + ISO 3166-1 region (en-US, not en_US).

Cross-reference: framework-international.md for full hreflang depth.

13. Crawler Observability

Knowing what crawlers actually do on a site, not what you think they do.

13.1 Server Log Analysis

The single best technical SEO data source. Server logs (nginx access logs, Apache access logs, Cloudflare logs) record every bot request with status, response time, and user agent.

Tools:

Screaming Frog Log File Analyser — desktop, parses nginx/Apache logs
GoAccess — terminal log viewer with web reports
Custom log pipeline — for clients with infrastructure depth, ship logs to BigQuery / DuckDB and query directly

What to look for:

Crawl frequency per URL (which pages does Googlebot revisit most often?)
Crawl-budget waste (low-value URLs with high crawl rate)
4xx/5xx clusters (pages crawlers are repeatedly hitting that error)
Slow URLs (high response time correlates with reduced crawl rate)
Bot fingerprint verification (real Googlebot? or a UA-spoofing scraper?)

13.2 Bot Verification

Anyone can claim to be Googlebot. Verify:

Reverse DNS lookup of the bot's IP must resolve to googlebot.com or google.com
Forward DNS of that hostname must resolve back to the same IP
Google publishes its IP ranges at developers.google.com/search/apis/ipranges/googlebot.json

For Bing: bingbot.com reverse DNS. For Apple: applebot.apple.com. AI crawlers vary; ClaudeBot publishes IP ranges, GPTBot publishes IP ranges, PerplexityBot publishes IP ranges.

13.3 GSC URL Inspection

For specific URLs, GSC's URL Inspection tool shows:

Last crawl date
Last response code
Indexed status
Mobile usability
Rendered HTML (live test)
Discovered referring URLs

Use this to debug specific indexing problems.

14. Audit Mode

#	Criterion	Pass/Fail
TS1	robots.txt returns 200 plain text, allows critical resources
TS2	XML sitemap returns 200, validates, lists only canonical indexable URLs
TS3	Sitemap submitted to Google Search Console and Bing Webmaster
TS4	All canonical URLs return 200
TS5	Self-referential rel=canonical on every indexable page
TS6	HTTP-to-HTTPS 301 redirect, single hop
TS7	www / non-www unified via 301, single hop
TS8	Trailing slash policy enforced sitewide
TS9	URLs lowercase, no mixed-case duplicates
TS10	Zero redirect chains (every redirect single-hop)
TS11	No 4xx URLs in sitemap or internal links
TS12	No 5xx URLs detected in last 30 days
TS13	HSTS header present with min 1-year max-age
TS14	TLS 1.2+ enforced, valid certificate, no mixed content
TS15	Mobile rendering verified (Mobile-Friendly Test)
TS16	JS-rendered content visible to Googlebot via URL Inspection
TS17	IndexNow key deployed (for Bing/Yandex/Naver indexing)
TS18	hreflang correctly implemented if multi-region
TS19	Bot verification logic in place (no UA-spoofing scrapers treated as bots)
TS20	Server logs analyzed at least quarterly for crawl-budget waste
TS21	Zero soft 404s in GSC
TS22	Crawled — currently not indexed bucket under 10% of total
TS23	Discovered — currently not indexed bucket under 5% of total
TS24	URL parameter strategy documented (block / canonical / index per parameter)
TS25	Pagination strategy documented (rel=next/prev replaced or supplemented)
TS26	AI crawler policy in robots.txt explicit and documented
TS27	Duplicate-content audit completed in last 90 days
TS28	All 301 redirects retained from migrations (don't expire redirects)
TS29	Crawl depth report shows zero pages over depth 3 (small sites) or 5 (large)
TS30	URLs under 60 characters where possible
TS31	Server response time under 600ms for HTML responses
TS32	GSC Coverage report shows zero "server error" URLs
TS33	GSC URL Inspection on 5 random pages confirms canonical, indexed status, no rendering issues
TS34	Lighthouse SEO score 100 on representative sample of pages
TS35	No JavaScript-only navigation (every link reachable via crawl without rendering)

Score: 35. World-class: 33+/35.

15. Common Mistakes

Blocking CSS/JS in robots.txt — Google needs them to render. Frequently breaks indexing.
Canonical pointing to a redirect target — invalidates the canonical signal.
Multiple canonical signals disagreeing — internal links say A, sitemap says B, rel=canonical says C; Google picks one and ignores the others.
Trailing slash inconsistency — half the site with /, half without; treated as duplicate URLs.
Redirect chains — A→B→C→D wastes crawl, leaks signals.
302s where 301 belongs — temporary redirect on a permanent move; ranking signals leak.
Soft 404s — page returns 200 but says "not found"; Google detects and demotes.
Indexable thin pages — tag archives, paginated category pages, search result pages with no value indexed without filtering.
JavaScript navigation only — links rendered via JS; crawl depth report shows orphaned pages.
Stale <lastmod> in sitemap — every URL claims today's date; Google starts ignoring lastmod entirely.
HTTPS deployed but HTTP not redirected — both versions serve, both indexed, duplicate-content penalty.
Mixed content — HTTPS page loads HTTP resources; browser blocks, layout breaks, ranking suffers.
AI crawler blocking by accident — wildcard Disallow: / block applied to legitimate AI crawlers losing citation traffic.
No IndexNow — Bing, Yandex, Naver indexing days late when push-based could do it in minutes.
Forgotten redirects after migration — old redirects removed prematurely; old inbound links 404.

16. Maintenance

Weekly:

Review GSC Coverage report for new errors
Check Bing Webmaster for crawl issues
Spot-check new URLs are indexable and in sitemap

Monthly:

Full GSC report review across all categories
Sitemap regeneration verification
Redirect map audit
Server log spot-check for 4xx/5xx clusters

Quarterly:

Comprehensive crawl audit (Screaming Frog or Sitebulb)
Server log deep analysis
Crawl-budget evaluation
Canonical audit
HTTPS / HSTS verification
AI crawler policy review (new bots emerge frequently)

Annually:

Full URL inventory and structural review
Migration redirect retention verification
Hreflang validation if international
IndexNow key rotation if compromised

17. Companion Documents

framework-pageexperience.md — Core Web Vitals, mobile, intrusive interstitials
framework-schema.md — Structured data implementation
framework-internallinking.md — Hub-and-spoke architecture
framework-migration.md — Site moves and URL restructures
framework-security.md — Broader security posture
framework-international.md — Full hreflang depth
framework-aicitations.md — AI crawler policy and visibility
framework-headless.md — Headless CMS rendering patterns

Document version: 1.0
Last updated: 2026-05-05
Owner: Joseph W. Anady — ThatDeveloperGuy — SDVOSB

About this framework library

Companion 14-tier Engine Optimization stack (each tier is its own article):

Need this framework implemented on your site? See the Engine Optimization service or hire through ThatDevPro contact.

Surviving Google's core algorithm updates

Joseph Anady — Sun, 24 May 2026 01:04:10 +0000

Originally published at thatdevpro.com. Part of ThatDevPro's open SEO + AI framework library. ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.

Google's Core Algorithm Updates — Detection, Response, Recovery, and Prevention

A comprehensive installation and audit reference for monitoring Google's core algorithm updates, classifying their impact on a website, executing the response protocol, tracking recovery, and building structural resilience to future updates. This document is dual-purpose: installation manual and audit document.

1. Document Purpose & How to Use This Document

1.1 What This Document Is

This is the canonical reference for handling Google core algorithm updates — the periodic broad-spectrum changes Google makes to its ranking systems that can dramatically reshape search results across millions of sites simultaneously. Core updates are different from spam updates, helpful content updates (now part of core), product reviews updates, and minor tweaks. Core updates are the largest, most consequential, and most disruptive changes Google deploys.

This document specifies how to detect when a core update is happening, how to assess its impact on a specific site, how to respond constructively (rather than panic-react), how to track recovery over the typical 60-90 day post-update period, and how to build a site that's structurally resilient to future updates.

1.2 Three Operating Modes

Mode A — Install Mode: Building monitoring and response infrastructure into ongoing site operations. Follow Sections 2 → 14.

Mode B — Audit Mode: Evaluating an existing site's preparedness for or response to core updates. Skip to Section 11.

Mode C — Hybrid Mode: Audit current state then install missing infrastructure.

1.3 How Claude Code CLI Should Consume This Document

Read Section 2 — collect client variables and historical update impact data
Read Section 3 — understand what core updates are and aren't
Install monitoring infrastructure — Section 5
Define response protocols — Section 6
Build resilience patterns — Section 7
Validate — Section 11
Generate report — Section 14

1.4 Conflict Resolution Rules

Conflict	Rule
Existing post-update remediation in progress	Don't reset. Document current state and continue tracking.
Existing recovery efforts that contradict this framework	Follow the framework here, but document deviation reasons for client/team.
Knee-jerk responses already deployed (mass content edits)	Audit changes for unintended consequences. Document.
Disagreement on what an update targeted	Document multiple hypotheses; track which holds up over recovery period.

1.5 Required Tools

Google Search Console — primary source for traffic and ranking data
Google Analytics 4 — for engagement data and traffic patterns
Semrush Sensor / Mozcast / Advanced Web Ranking — for SERP volatility tracking
Ahrefs / Semrush — for ranking history and competitor comparison
Wayback Machine — for historical site state research
Google Search Status Dashboard — status.search.google.com/
Algoroo / SEMrush Sensor / RankRanger — for daily SERP volatility tracking

2. Client Variables Intake

# ============================================
# CORE UPDATES FRAMEWORK CLIENT VARIABLES
# ============================================

# --- Business Identity (REQUIRED) ---
business_name: ""
primary_domain: ""
business_industry: ""
ymyl_classification: ""              # "full", "partial", "lite", "non" (affects update sensitivity)

# --- Site History (REQUIRED) ---
domain_age_years: 0
historical_traffic_baseline: 0       # Pre-most-recent-update average daily organic traffic
historical_keyword_count: 0          # Number of keywords ranking in top 10
last_known_volatility_event: ""      # Date of last identified algorithm impact

# --- Past Core Update Impacts (REQUIRED) ---
past_update_impacts:
  - update_name: ""                  # e.g., "March 2026 Core Update"
    update_date: ""                  # YYYY-MM-DD
    direction: ""                    # "loss", "gain", "neutral", "mixed"
    magnitude_percent: 0             # Percent change in organic traffic
    pages_most_affected: []          # URLs with biggest changes
    hypothesis_about_target: ""      # What this site/team believes the update targeted
    remediation_actions_taken: []
    recovery_status: ""              # "full", "partial", "none", "still_in_progress"
    recovery_completion_date: ""

# --- Monitoring Infrastructure Status (REQUIRED) ---
has_gsc_property_verified: false
has_ga4_configured: false
has_serp_volatility_monitoring: false
has_ranking_tracker: false           # Ahrefs, Semrush, AWR, etc.
has_brand_alert_monitoring: false    # Google Alerts, Mention, Brand24
has_competitor_tracking: false

# --- Response Capability (REQUIRED) ---
has_documented_response_protocol: false
response_team_identified: false
response_team_members: []
emergency_communication_channel: ""  # How team alerts each other to volatility

# --- Site Resilience Posture (RECOMMENDED) ---
eeat_score: 0                        # From framework-eeat.md audit
hcs_score: 0                         # From framework-hcs.md audit
ymyl_score: 0                        # From framework-ymyl.md audit if applicable
sqrg_estimated_rating: ""            # From framework-sqrg.md
content_quality_distribution:        # From HCS audit
  highest_or_high: 0                 # Percentage
  medium: 0                          # Percentage
  low_or_lowest: 0                   # Percentage

# --- Documentation (RECOMMENDED) ---
has_algorithm_update_log: false      # Internal log tracking all updates and impacts
has_post_update_review_process: false
has_quarterly_resilience_audit: false

# --- Recent Update Status (FILLED DURING ACTIVE UPDATE) ---
current_update_active: false
current_update_name: ""
current_update_started: ""           # Detection date
current_update_status: ""            # "rumored", "rolling_out", "completed", "in_recovery"
current_update_traffic_change: 0     # Percentage
current_update_response_phase: ""    # "detect", "assess", "diagnose", "remediate", "recover", "review"

3. What Core Updates Are

Google deploys algorithm changes constantly — hundreds of small updates per year. Most are imperceptible to individual sites. Three categories of updates have outsized impact and are publicly named by Google:

3.1 Core Updates

Core updates are broad changes to how Google's core ranking algorithms evaluate content. They typically:

Roll out over 1-3 weeks (some longer)
Affect rankings across all niches simultaneously
Are publicly announced by Google before, during, and after
Get named after the month and year (e.g., "March 2026 Core Update")
Cause significant SERP volatility during rollout
Reshape rankings substantially — some sites gain, some lose, most see some change

Google deploys 3-6 named core updates per year. Recent core updates and their characteristic focus:

March 2024 Core Update — Integrated the Helpful Content System into core ranking; expanded site reputation abuse guidance
August 2024 Core Update — Refined HCS signal weighting; addressed feedback about small site recovery from prior core updates
November 2024 Core Update — Significant rollout addressing site quality holistically
December 2024 Core Update — Targeted AI mass-production patterns specifically
March 2025 Core Update — Significant E-E-A-T re-weighting
June 2025 Core Update — Refinements to AI Overview source selection
November 2025 Core Update — Reputation and content originality emphasis
March 2026 Core Update — Most recent major update at time of this framework's creation; focused on entity-based ranking and AI citation worthiness

3.2 What Core Updates Are Not

Core updates are not:

Spam updates — These target manipulative practices specifically (link schemes, doorway pages, scraped content). Spam updates are separate.
Reviews updates — Targeted at product/service review content quality. Now folded into core updates as of late 2023.
Helpful Content updates — Now part of core ranking system as of March 2024.
Manual actions — Penalties applied by human reviewers, communicated via Search Console. Different mechanism entirely.
Indexing changes — When pages drop out of the index entirely, that's typically a different issue (technical, manual action, or sitewide spam).
SERP feature changes — When the SERP itself changes layout (more AI Overviews, more videos, etc.), that's separate from core updates though often coincident.

3.3 What Core Updates Reward and Punish

Google's official guidance: "There's nothing wrong with pages that drop after a core update. They haven't violated our spam policies nor are subject to a manual or algorithmic action, as can happen to pages that do violate those policies. In fact, there are no specific actions to take to recover from a core update. Negative rankings are not a signal that you have done anything wrong."

In practice, core updates appear to:

Reward:

Strong E-E-A-T signals (see framework-eeat.md)
Helpful Content System compliance (see framework-hcs.md)
Entity-based authority (see framework-knowledgegraph.md and framework-entitysalience.md)
Genuine first-hand experience and original content
Demonstrated topical authority through depth
Sites with strong reputation research signals (see framework-sqrg.md)
Sites with high information gain (see framework-infogain.md)
For YMYL: credentialed authorship and rigorous editorial process

Punish:

Thin or low-value content
Aggregated content that doesn't add original insight
Mass-produced AI content without expert review
Sites with reputation issues
YMYL content from non-credentialed sources
Sites violating spam policies (though spam violations typically trigger spam updates)
Sites with significant Helpful Content System failures
Sites that game freshness signals without substantive updates

3.4 The Recovery Truth

Recovery from a core update is possible but not guaranteed. Google's guidance: "Improvements in your content might result in better rankings — though changes might not be reflected until the next core update."

Core updates are evaluative re-baselines. Once Google's evaluation of a site changes negatively, recovery typically requires:

The site genuinely improving (content quality, E-E-A-T, etc.)
Time for Google to recognize the improvement
The next core update incorporating the new evaluation

Sites typically don't "recover" between core updates. They might see modest fluctuation but the major re-baseline happens at the next core update. This means recovery cycles are typically 90+ days minimum, often 6-12 months.

Some sites never recover. If the core update detected fundamental issues with the site's purpose, content strategy, or trust posture, those issues need fundamental remediation. Cosmetic changes don't trigger recovery.

4. Update Detection Protocol

4.1 Signals That an Update Is Happening

Detect updates through multiple signal sources:

4.1.1 Official Google announcements

Google typically announces core updates via:

@SearchLiaison on X — primary public communication channel
developers.google.com/search/blog — official blog posts
status.search.google.com — Search Status Dashboard
Reddit r/google_seo and r/seo — community confirmation

Set up alerts:

# Monitor SearchLiaison via RSS or alternative
# Monitor Google Search Blog RSS:
# https://developers.google.com/search/blog/feed.xml

4.1.2 SERP volatility tools

Daily volatility tracking:

Semrush Sensor — semrush.com/sensor/ — daily volatility per category
Mozcast — moz.com/mozcast/ — Moz's tracker
Advanced Web Ranking SERP Volatility — daily
Algoroo — algoroo.com — ranking volatility tracker
CognitiveSEO Signals — independent volatility tracker

When volatility spikes 7+ across multiple trackers, an update is likely active.

4.1.3 Site-specific signals

For each monitored site, set up:

GSC daily traffic alerts — flag any day with >15% traffic deviation
Ranking tracker alerts — flag tracked keywords with >5 position drops
Server log monitoring — sudden Googlebot crawl pattern changes
Brand mention alerts — sudden coverage in SEO publications

4.1.4 Industry signal aggregation

Monitor:

Search Engine Land — official update coverage
Search Engine Roundtable — Barry Schwartz's daily volatility coverage
Search Engine Journal — algorithm coverage
r/SEO — community-level confirmation

4.2 Detection Workflow

When potential update is detected:

Confirm via multiple sources — Don't react to single-source rumors
Document detection time — Note the moment volatility appeared
Note Google's communication status — Has Google confirmed officially?
Open algorithm update incident log entry — Begin tracking impact

Algorithm update incident log template at /admin/algorithm-incidents/{{date}}-{{update-name}}.md:

# Update Incident: {{UPDATE_NAME}}

## Detection
- Detected: {{DATETIME}}
- Detection sources: {{LIST}}
- Google confirmation: {{YES/NO/PENDING}}
- Confirmation date: {{DATE_IF_CONFIRMED}}

## Volatility Indicators
- Semrush Sensor: {{SCORE}}/10
- Mozcast: {{SCORE}}
- Other trackers: {{SCORES}}
- Industry sources reporting: {{LIST}}

## Initial Impact Assessment (24 hours post-detection)
- Traffic delta vs 7-day average: {{PERCENTAGE}}
- Top affected pages: {{LIST}}
- Top affected keywords: {{LIST}}

## Working Hypothesis
{{WHAT_WE_THINK_THIS_UPDATE_TARGETS}}

## Status
{{DETECTING / ASSESSING / DIAGNOSING / REMEDIATING / RECOVERING / REVIEWED}}

4.3 The 72-Hour Hold

Critical rule: do not take significant remediation action within 72 hours of detection.

Reasons:

The update is probably still rolling out — early data is incomplete
SERP volatility within an update is normal and self-corrects
Knee-jerk responses cause damage that's hard to reverse
The update may not target what you think it targets
Three days of data lets you distinguish signal from noise

During the 72-hour hold:

Document what's happening
Monitor (don't react)
Read Google's official communications
Read industry analysis
Survey community discussions
Resist client/stakeholder pressure to "do something now"

After 72 hours, you have enough data to begin assessment.

5. Update Impact Assessment

5.1 Quantitative Impact Analysis

After 72 hours, gather data:

5.1.1 Site-wide traffic delta

Compare: 7-day average post-detection vs 7-day average pre-detection
Compare: Same period year-over-year (control for seasonality)
Compare: Specific weekday-to-weekday (Monday vs Monday)

Calculate:
- Total organic traffic change (%)
- Total organic clicks change (GSC)
- Total impressions change (GSC) — distinguishes ranking from CTR issues
- Average position change (GSC)

5.1.2 Per-page impact

In GSC Performance report:

Filter date range: 7 days post-update vs 7 days pre-update
Sort by traffic change descending and ascending
Identify pages with >25% traffic change in either direction
Document URL, change percentage, page type, primary topic

Build a per-page impact spreadsheet:

url,page_type,primary_topic,traffic_pre,traffic_post,traffic_delta_pct,impressions_pre,impressions_post,impressions_delta_pct,position_pre,position_post,position_delta,ymyl_status,word_count,content_age_days,last_refresh_days_ago,has_credentialed_author,notes
/articles/medication-guide,article,health/medication,1247,621,-50.2,4500,3200,-28.9,3.2,4.8,-1.6,full_ymyl,2400,367,367,no,major_loss_no_credentialed_review
/articles/site-speed-guide,article,seo/technical,892,1108,+24.2,3200,3850,+20.3,4.1,3.6,+0.5,non,1850,121,32,yes,small_gain

5.1.3 Per-query impact

In GSC Performance:

Pivot by query
Identify queries with significant change
Determine if changes cluster around specific topics or page types

5.1.4 Per-content-type impact

Group affected pages by type:

Blog articles
Service pages
Product pages
Local landing pages
Author/author pages
Resource/tool pages
Category/hub pages

Compare change distribution across types. If one type is dramatically worse hit, the update likely targeted something specific to that type.

5.2 Pattern Recognition

Look for patterns among losing pages:

Content patterns:

Common topic clusters?
Common content type?
Common publication age?
Common author?
AI vs human-written?
Original vs aggregated content?
Length patterns?

Quality patterns:

Common E-E-A-T weaknesses?
Common HCS failures?
Common YMYL gaps?
Thin content patterns?

Technical patterns:

Common URL structures?
Common templates?
Common rendering issues?
Common Core Web Vitals issues?

Reputation patterns:

Topics where the site has weak authority?
Topics where competitors have stronger E-E-A-T?
Niches where the site doesn't fit the established expert pattern?

Document patterns in the incident log.

5.3 Hypothesis Formation

After pattern analysis, form 2-3 hypotheses about what the update targeted:

Example hypotheses:

H1: "Update targeted AI-generated YMYL content without expert review. Pages lost: 80% are AI-assisted YMYL articles. Pages held: 90% have credentialed reviewers."
H2: "Update reweighted entity-based authority. Pages lost: those on topics where the site lacks topical authority. Pages held: those in our 3 primary topical pillars."
H3: "Update penalized aggregator pages. Pages lost: 'best of' lists with no original testing. Pages held: original testing/research pages."

Test each hypothesis against the data:

Does the pattern hold across the affected page set?
Are there counter-examples?
Does the hypothesis explain the magnitude of loss?
Is the hypothesis consistent with Google's official communications?

The hypothesis that explains the most data is most likely correct. If multiple hypotheses fit, multiple changes may have happened.

5.4 External Hypothesis Validation

Compare to industry analysis:

What's the consensus from Search Engine Land, Search Engine Journal, Barry Schwartz's coverage?
What patterns are other practitioners reporting?
Has Google given any specific guidance about this update?

If external analysis matches your internal pattern, confidence is high. If it doesn't match, either your situation is unusual (worth investigating why) or your hypothesis is wrong.

6. Response Protocol

6.1 Response Phase Decision Matrix

Based on impact assessment, choose response track:

Minimal impact (<10% traffic change):

Document the update
Monitor for 30 days
No remediation action
Review at quarterly resilience audit

Moderate loss (10-30% traffic change):

Document patterns identified
Initiate targeted remediation on identified weaknesses
60-90 day recovery monitoring
Full audit using applicable frameworks

Significant loss (30-50%):

Comprehensive audit using all foundational frameworks
Aggressive remediation
6-12 month recovery expectation
Strategic review of content portfolio

Catastrophic loss (>50%):

Full strategic reset
Remove or significantly remediate large content sections
Likely 12+ month recovery if at all
Consider whether site model is viable

6.2 What Not to Do (Immediate)

Within first 30 days post-update, avoid:

Mass deletion of content — without rigorous analysis, you may delete the wrong content
Mass canonicalization changes — can compound the problem
Mass redirect operations — if rankings recover, redirects work against you
Major site architecture changes — distracts from the actual issue
Removing internal links — if you misdiagnose, you've lost link equity unnecessarily
Changing CMS or stack — adds variables that obscure what's working
Buying/exchanging links — never appropriate, especially during an update
Mass content rewriting — rewriting hundreds of articles in panic mode produces lower-quality content

6.3 Constructive Response Actions

6.3.1 If E-E-A-T issues identified

Apply framework-eeat.md remediation per pillar:

Strengthen author credentials and bio pages
Add reviewer credit to YMYL content
Improve schema graph for entity recognition
Build reputation infrastructure
Add citation lists to factual content

6.3.2 If HCS issues identified

Apply framework-hcs.md remediation:

Identify and remove/consolidate thin content
Refocus on topical pillars
Improve About page substantively
Add original value markers per article
Disclose AI use properly

6.3.3 If YMYL issues identified

Apply framework-ymyl.md remediation:

Add credentialed reviewers
Add primary literature citations
Build out editorial and corrections policies
Add topic-specific disclaimers per article

6.3.4 If entity issues identified

Apply framework-entitysalience.md and framework-knowledgegraph.md:

Reinforce primary entity per page
Build entity sameAs graph
Pursue Wikidata entry
Strengthen topical hub pages

6.3.5 If technical issues identified

Apply Tier 1 of the 14-tier framework:

Fix Core Web Vitals issues
Resolve crawl errors
Improve mobile experience
Address indexing problems

6.4 Remediation Documentation

Track every remediation action in the incident log:

## Remediation Actions Taken

### Week 1 ({{DATE_RANGE}})
- {{DATE}}: {{ACTION}} — {{PAGES_AFFECTED}} — {{REASONING}}
- {{DATE}}: {{ACTION}} — {{PAGES_AFFECTED}} — {{REASONING}}

### Week 2 ({{DATE_RANGE}})
- {{DATE}}: {{ACTION}} — {{PAGES_AFFECTED}} — {{REASONING}}

### Week 3+ ({{DATE_RANGE}})
{{...}}

This documentation is essential for:

Understanding what helped (correlation with recovery)
Avoiding repeated mistakes
Learning across multiple updates over time

6.5 Communication With Stakeholders

During an update, communicate clearly with clients/management:

Initial communication (within 48 hours of detection):

"Google deployed a core update. Industry-wide volatility is significant."
"Our site is showing {{IMPACT_DESCRIPTION}}."
"We're in the data-gathering phase. Substantive remediation begins in 72-96 hours."
"Recovery expectation: {{TIMEFRAME_BASED_ON_IMPACT_LEVEL}}."

Weekly during active update:

Status of impact (improving/stable/worsening)
Hypothesis about update targets
Remediation actions in progress
What we're not doing and why
Expected next milestone

Post-stabilization (4-6 weeks post-update):

Final impact assessment
Comprehensive remediation plan
Recovery monitoring schedule
Strategic recommendations

7. Recovery Tracking

7.1 Recovery Indicators

Monitor weekly:

Recovery signal indicators:

Traffic trending upward week-over-week
Lost keywords regaining position
Affected pages crawled more frequently
New impressions in GSC for previously suppressed queries
Indexed page count returning to baseline
Engagement metrics improving on remediated content

Continued suppression indicators:

Traffic remains flat at reduced level
Keywords don't recover position
Crawl frequency doesn't return to baseline
New content also struggles to rank

7.2 Recovery Timeline Expectations

Based on impact severity:

Impact Level	Initial Recovery Signals	Substantial Recovery	Full Recovery
Minor loss	2-4 weeks	1-2 months	Often by next core update
Moderate loss	4-8 weeks	3-6 months	6-12 months, often at next core update
Significant loss	2-3 months	6-12 months	12-24 months, may require multiple core updates
Catastrophic loss	3-6 months for any signal	12+ months	May not fully recover; strategic reset may be needed

Recovery is not linear. Expect ups and downs week-to-week. The trend over 30-60 day windows is what matters.

7.3 Cross-Update Recovery Patterns

Review historical update impact data:

Did this site recover from previous updates? On what timeline?
Were recovery efforts effective?
What patterns of remediation correlate with recovery?

Build institutional memory of what works for this specific site.

7.4 When Recovery Doesn't Happen

If 6-12 months post-update show no recovery signals:

Reassess hypothesis — was the diagnosis correct?
Audit remediation execution — did we actually do what we documented?
Compare to recovered competitors — what did they do differently?
Consider strategic reset — is the site model fundamentally compromised?

Strategic resets may include:

Migrating to a new domain
Spinning off categories into separate sites
Drastically reducing content footprint
Rebuilding from a different angle

These are major decisions made over months of consideration, not immediate post-update reactions.

8. Building Resilience to Future Updates

The best response to a core update is having built a site that wasn't going to be hit by it in the first place. Resilient sites share characteristics.

8.1 Foundational Resilience

E-E-A-T strong by default — Sites that score 110+/130 on E-E-A-T audit before an update are resilient by default. Apply framework-eeat.md continuously, not reactively.

HCS-aligned content strategy — Sites that publish for users, not for search, weather updates better. Apply framework-hcs.md.

YMYL standards maintained — YMYL content meeting elevated standards rarely loses in updates. Apply framework-ymyl.md.

Entity authority — Sites with strong entity recognition through Wikidata, Wikipedia, schema graph, and topical authority weather updates better. Apply framework-knowledgegraph.md and framework-entitysalience.md.

8.2 Content Portfolio Resilience

Topical focus — Sites covering 3-7 topics deeply outperform sites covering 30 topics shallowly. Don't dilute.

Quality over quantity — Better to have 100 high-quality articles than 1000 mediocre ones. The mediocre ones drag the whole site down.

Genuine first-hand expertise — Content built on actual experience holds value through algorithm changes.

Original research and insight — Information Gain (see framework-infogain.md) is durable across updates.

Refresh discipline — Time-sensitive content kept current; outdated content retired.

8.3 Trust Infrastructure Resilience

Reputation infrastructure — Strong reviews, earned media, industry recognition compound over time and protect against reputation-targeting updates.

Author identity stability — Real, credentialed, persistent authors. Not turnover-heavy author rosters.

Technical foundations solid — Fast, secure, accessible, well-structured sites are easier for Google to evaluate accurately.

8.4 Operational Resilience

Algorithm update log maintained — Every update tracked. Learning compounds.

Quarterly resilience audits — Catch drift before it costs.

Foundational framework compliance — These frameworks are not one-time installs. Maintain compliance continuously.

Don't over-optimize — Aggressive optimization creates fragility. Sites that try to game algorithms get hit by algorithm changes.

8.5 Resilience Audit

Quarterly, score the site against:

#	Criterion	Score
R1	E-E-A-T audit current and 100+/130	__/2
R2	HCS audit current and 45+/54	__/2
R3	YMYL audit (if applicable) current and 40+/48	__/2
R4	SQRG self-rating "High" or "Highest" on top pages	__/2
R5	Knowledge Graph entity established	__/2
R6	Entity Salience strong on primary topics	__/2
R7	Information Gain demonstrable per article	__/2
R8	AI Citation indicators positive (see framework-aicitations.md)	__/2
R9	Topical focus maintained (3-7 pillars)	__/2
R10	Content portfolio: 80%+ pages would rate Medium or higher	__/2
R11	Reputation research returns positive results	__/2
R12	Trust infrastructure complete (policies, security, schema)	__/2
R13	Refresh discipline in place	__/2
R14	Algorithm update log maintained	__/2
R15	Quarterly audits documented	__/2

Score: 30 max. Resilient site: 25+/30. Sites scoring below 20 are at substantial risk in core updates.

9. Learning From Updates

9.1 Post-Update Review Cadence

After each core update completes (typically 4-6 weeks post-rollout):

Conduct full impact analysis
Validate or revise hypothesis
Document what remediation worked or didn't
Update institutional knowledge
Update this framework if patterns suggest framework gaps

9.2 Cross-Update Pattern Analysis

Annually, review all algorithm update incidents:

What patterns repeat across updates?
What characteristics of this site keep getting hit?
What characteristics keep being rewarded?
What strategic changes should the site consider?

9.3 Industry Learning Integration

Continuously consume:

Search Engine Land's algorithm coverage
Google Search Central blog
Search Engine Roundtable's daily reports
WhitePress, Search Engine Journal analysis
@SearchLiaison communications

But filter heavily — much SEO commentary is speculation. Trust patterns from your own data more than generic guidance.

10. Spam Updates and Manual Actions (Adjacent Issues)

While this document is about core updates specifically, related events require similar protocols.

10.1 Spam Updates

Spam updates target manipulative practices. If a site is hit by a spam update:

Review Google's spam policies (developers.google.com/search/docs/essentials/spam-policies)
Identify and remediate violating practices
Recovery from spam updates can be faster than core updates if violations are clearly remediated

10.2 Manual Actions

Manual actions are penalties applied by human reviewers and communicated via Search Console.

Check Search Console > Security & Manual Actions > Manual actions regularly
If a manual action is issued, follow Google's reconsideration request process
Document everything; reconsideration requires showing remediation

10.3 Algorithmic Action Without Public Update

Sometimes sites lose ranking without a publicly-named update. Possible causes:

Localized algorithm changes
Targeted spam intervention
Hacking/security compromise
Technical issue (de-indexing, canonical confusion)
Reputation event

Investigation:

Check Search Console for security warnings, manual actions
Audit technical health (crawl errors, indexability, redirects)
Audit reputation (new negative content, hacked pages)
Audit content (was something published that violates policies?)
Compare to volatility trackers — was there an unannounced update?

Many "algorithmic actions" without public updates turn out to be technical issues or reputation issues remediable by direct action.

11. Audit Mode

11.1 Algorithm Update Preparedness Audit

Score the site:

#	Criterion	Severity
AU1	Resilience score 25+/30 (Section 8.5)	Critical
AU2	Algorithm update log maintained	Critical
AU3	Response protocol documented and team identified	Critical
AU4	Monitoring infrastructure in place (GSC, GA4, volatility, ranking)	Critical
AU5	Quarterly resilience audits performed	High
AU6	Past update impacts documented and analyzed	High
AU7	Foundational frameworks (E-E-A-T, HCS, YMYL, SQRG) installed	Critical
AU8	Content quality distribution favorable (80%+ Medium-or-higher PQ)	Critical

11.2 Active Update Response Audit

If currently in an active update response, score:

#	Criterion	Pass/Fail
AR1	Detection occurred within 24 hours of update start
AR2	72-hour hold respected — no panic actions in first 3 days
AR3	Quantitative impact assessment completed within 7 days
AR4	Pattern analysis completed
AR5	Hypothesis formed and validated against external sources
AR6	Constructive remediation underway based on hypothesis
AR7	Documentation maintained throughout
AR8	Stakeholder communication occurring on schedule
AR9	Recovery monitoring weekly

11.3 Post-Update Review Audit

After update completes (4-6 weeks post-rollout), score:

#	Criterion	Pass/Fail
AP1	Final impact assessment documented
AP2	Remediation actions and outcomes documented
AP3	Hypothesis validation or revision documented
AP4	Lessons integrated into framework
AP5	Resilience audit re-run
AP6	Remediation gaps identified and scheduled

12. Common Mistakes & Anti-Patterns

12.1 Panic Reaction

Anti-pattern: Within 48 hours of detecting an update, mass-deleting content or rewriting articles.

Why it fails: Premature action based on incomplete data causes more damage than the update did.

Fix: Respect the 72-hour hold. Gather data before acting.

12.2 Misdiagnosis

Anti-pattern: Assuming the update targeted thing X without checking the data, then remediating for thing X.

Why it fails: If the update actually targeted thing Y, your remediation doesn't help — and it may hurt by introducing new issues.

Fix: Data-driven hypothesis formation. Validate hypothesis against patterns and external sources before acting.

12.3 Treating Updates as Penalties

Anti-pattern: Believing the site was "punished" and looking for what to "fix" to make Google "stop punishing."

Why it fails: Updates re-evaluate quality holistically. Looking for a specific "violation" misses the structural nature of the change.

Fix: Treat updates as evaluative re-baselines. Improve the site genuinely, not as remediation theater.

12.4 Expecting Quick Recovery

Anti-pattern: Running emergency remediation hoping for recovery within weeks.

Why it fails: Recovery typically takes 90+ days minimum, often 6-12 months. Expecting faster sets up false hope and premature additional changes.

Fix: Realistic recovery expectations. Plan for the long game.

12.5 Single Update Focus

Anti-pattern: Treating each update as isolated event, not learning across them.

Why it fails: Misses pattern recognition. Sites that don't learn keep getting hit by similar update types.

Fix: Cross-update pattern analysis. Build institutional learning.

12.6 Tracker Chasing

Anti-pattern: Reacting to daily volatility tracker fluctuations as if every spike is a major update.

Why it fails: Most volatility is noise. Reacting to noise causes thrashing.

Fix: Trust multi-source confirmation before treating something as a major update.

12.7 Ignoring Foundational Frameworks

Anti-pattern: Trying to recover from an update without ever auditing E-E-A-T, HCS, YMYL, or SQRG compliance.

Why it fails: Updates reward sites that comply with foundational frameworks. Skipping them limits recovery.

Fix: Use update events as forcing function for foundational framework audits.

12.8 Stakeholder Pressure-Driven Decisions

Anti-pattern: Making changes because a client or executive demands action, not because data supports it.

Why it fails: Pressure-driven changes often hurt more than help.

Fix: Educate stakeholders on the 72-hour hold, the diagnostic process, and realistic recovery timelines. Hold the line on data-driven response.

12.9 Ignoring Spam Update vs Core Update Distinction

Anti-pattern: Treating a spam update like a core update or vice versa.

Why it fails: Different remediation protocols. Spam violations need direct remediation; core update issues need quality improvement.

Fix: Identify which type of update is occurring before responding.

12.10 Over-Documenting While Under-Acting

Anti-pattern: Spending all energy documenting impact and analyzing patterns, never actually executing remediation.

Why it fails: Analysis paralysis prevents recovery.

Fix: Documentation supports action, doesn't replace it. After 7-14 days of analysis, execute remediation in parallel with continued monitoring.

13. Maintenance Schedule

13.1 Daily

Monitor SERP volatility trackers
Check GSC for traffic anomalies
Watch @SearchLiaison and industry news for update mentions

13.2 Weekly

Review tracked keyword positions for unusual movement
Check brand search results for new negative content
Monitor traffic patterns for trend shifts

13.3 Monthly

Review crawl stats for unusual patterns
Check for new manual actions or security issues
Assess content portfolio quality distribution

13.4 Quarterly

Full resilience audit (Section 8.5)
Foundational framework compliance refresh (E-E-A-T, HCS, YMYL, SQRG)
Cross-incident pattern review
Update institutional knowledge base

13.5 Annually

Comprehensive year-in-review of all updates and impacts
Strategic resilience planning for upcoming year
Framework document revisions based on year's learning
Stakeholder education on update reality

13.6 During Active Update

24-hour intervals during first week
72-hour intervals during weeks 2-4
Weekly during recovery monitoring (months 2-6)

14. Implementation/Audit Report Templates

14.1 Post-Update Analysis Report Template

# Post-Update Analysis: {{UPDATE_NAME}}

## Update Identification
- Update name: {{NAME}}
- Detected: {{DATETIME}}
- Confirmed by Google: {{DATETIME}}
- Rollout completed: {{DATETIME}}
- Industry consensus on focus: {{SUMMARY}}

## Impact on This Site
- Total traffic change: {{PERCENTAGE}}
- Direction: {{LOSS/GAIN/MIXED}}
- Pages with >25% loss: {{COUNT}}
- Pages with >25% gain: {{COUNT}}
- Average position change: {{NUMBER}}
- Magnitude classification: {{MINIMAL/MODERATE/SIGNIFICANT/CATASTROPHIC}}

## Pages Most Affected
### Largest Losses
{{TABLE_OF_TOP_10_LOSSES}}

### Largest Gains
{{TABLE_OF_TOP_10_GAINS}}

## Pattern Analysis
{{IDENTIFIED_PATTERNS_ACROSS_AFFECTED_PAGES}}

## Hypothesis
**Primary hypothesis**: {{H1_DESCRIPTION}}
**Evidence supporting**: {{EVIDENCE}}
**Counter-evidence**: {{COUNTER_EVIDENCE}}

**Alternative hypothesis**: {{H2_DESCRIPTION}}
**Evidence supporting**: {{EVIDENCE}}

**Hypothesis confidence**: {{LOW/MEDIUM/HIGH}}

## Remediation Plan
### Phase 1 (Immediate)
{{ACTIONS}}

### Phase 2 (30 days)
{{ACTIONS}}

### Phase 3 (90 days)
{{ACTIONS}}

## Recovery Tracking
- 30-day check-in: {{SCHEDULED_DATE}}
- 60-day check-in: {{SCHEDULED_DATE}}
- 90-day check-in: {{SCHEDULED_DATE}}

## Lessons for Future Updates
{{INSIGHTS_TO_INTEGRATE}}

## Sign-Off
{{ANALYST_NAME}}, {{DATE}}

14.2 Algorithm Update Audit Report Template

# Algorithm Update Preparedness Audit

**Site**: {{BUSINESS_NAME}}
**Audit Date**: {{TODAY}}

## Resilience Score
{{X}}/30 — {{RESILIENT/AT_RISK/VULNERABLE}}

## Foundational Framework Status
- E-E-A-T: {{SCORE}}/130
- HCS: {{SCORE}}/54
- YMYL: {{SCORE}}/48 (if applicable)
- SQRG: {{ESTIMATED_RATING}}

## Monitoring Infrastructure Status
{{LIST_WITH_STATUS}}

## Response Capability Status
{{LIST_WITH_STATUS}}

## Past Update Impact History
{{TABLE_OF_PAST_UPDATES}}

## Risk Assessment
{{ASSESSMENT_OF_LIKELY_VULNERABILITIES}}

## Recommended Resilience Improvements
{{PRIORITIZED_LIST}}

## Sign-Off

End of Framework Document

Document version: 1.0
Last updated: 2026-04-29
Maintained by: ThatDeveloperGuy

Core updates are the most disruptive periodic events in SEO. The frameworks in this document — combined with foundational compliance with E-E-A-T, HCS, YMYL, SQRG, and entity-based authority — create resilience. Sites that build resilience proactively spend less time in reactive recovery. Sites that wait for updates to expose weaknesses spend significant time in recovery cycles.

The most important truth about core updates: the best response is not having needed one in the first place. Build sites that earn their rankings through genuine quality. Audit continuously. Improve continuously. Don't wait for updates to reveal what was always going to be revealed.

Companion documents:

framework-eeat.md
framework-ymyl.md
framework-hcs.md
framework-sqrg.md
framework-infogain.md
framework-entitysalience.md
framework-knowledgegraph.md
framework-aicitations.md

About this framework library

This article is the Dev.to republish of a framework reference document from ThatDevPro's SEO + AI engineering library. Canonical source: https://www.thatdevpro.com/insights/framework-coreupdates/

Companion 14-tier Engine Optimization stack (each tier is its own article):

Need this framework implemented on your site? See the Engine Optimization service or hire through ThatDevPro contact.

Google's Helpful Content System (HCS) explained

Joseph Anady — Sun, 24 May 2026 01:04:01 +0000

Originally published at thatdevpro.com. Part of ThatDevPro's open SEO + AI framework library. ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.

Google's "People-First Content" Framework

A comprehensive installation and audit reference for ensuring website content meets Google's Helpful Content System standards — the framework that became part of Google's core ranking infrastructure in 2024 and continues to drive ranking outcomes across every core update. This document is dual-purpose: installation manual and audit document.

Cross-stack implementation note: the code samples in this framework are written in plain HTML for clarity. For React, Vue, Svelte, Next.js, Nuxt, SvelteKit, Astro, Hugo, 11ty, Remix, WordPress, Shopify, and Webflow equivalents of every pattern below, see framework-cross-stack-implementation.md. For pure client-rendered SPAs (no SSR/SSG) see framework-react.md. For Tailwind-specific concerns (purge, dynamic classes, dark-mode CLS, focus accessibility) see framework-tailwind.md.

1. Document Purpose & How to Use This Document

1.1 What This Document Is

This is the canonical reference for implementing Google's Helpful Content System (HCS) on a website. HCS is the framework Google uses to distinguish content created for people (helpful, original, satisfies the searcher's need) from content created for search engines (manipulative, derivative, designed to rank rather than serve). HCS was launched in August 2022 as a standalone update, became part of Google's core ranking system in March 2024, and now operates continuously rather than as a periodic update.

This document specifies how to evaluate every piece of content against the HCS framework, what signals to install on every page to demonstrate "people-first" content creation, and how to audit existing content for HCS compliance.

1.2 Three Operating Modes

Mode A — Install Mode: Building HCS-compliant content infrastructure. Follow Sections 2 → 14 in order.

Mode B — Audit Mode: Evaluating existing content against HCS criteria. Skip to Section 11.

Mode C — Hybrid Mode: Audit then install for failing items.

1.3 How Claude Code CLI Should Consume This Document

Read Section 2 — collect client variables
Run Section 3 self-assessment — apply the HCS questions to each piece of content
Identify SEO-first patterns — flag content showing signals of "made for search engines"
Install per-article HCS markers (Section 5) and per-site HCS infrastructure (Section 6)
Validate — Section 11
Generate report — Section 14

1.4 Conflict Resolution Rules

Conflict	Rule
Existing thin content optimized for search	Flag for either deep enrichment or removal/consolidation. Do not preserve in current state.
Existing manipulative SEO patterns (keyword stuffing, doorway pages)	Remediate or remove. These pages drag down site-wide HCS score.
Existing content that's good but lacks HCS markers	Add markers without rewriting.
Existing content quantity vs quality tension	Quality always wins. Reduce scale if needed.

1.5 Required Tools

Google Search Console — for monitoring HCS-related ranking changes
MarketMuse, Frase, or Clearscope — for content depth and topic coverage analysis
Originality.ai or similar — AI content detection
Surfer SEO — for content quality benchmarking
Internal review — qualified human evaluators who can self-assess content honestly

2. Client Variables Intake

# ============================================
# HCS FRAMEWORK CLIENT VARIABLES
# ============================================

# --- Business Context (REQUIRED) ---
business_name: ""
primary_domain: ""
business_industry: ""
business_focus_topics: []            # 3-7 topics this site is genuinely the authority on

# --- Content Audit Baseline (REQUIRED) ---
total_content_pieces: 0
content_publication_rate: ""         # "high_volume" (>10/week), "medium" (1-5/week), "low" (<1/week)
content_creation_method: ""          # "in_house_experts", "freelancers", "ai_assisted", "outsourced", "mixed"
average_content_length: 0            # Words

# --- Audience (REQUIRED) ---
primary_audience_description: ""     # Who is this content actually for?
audience_pain_points: []             # 3-5 specific problems they're trying to solve
audience_expertise_level: ""         # "beginner", "intermediate", "expert", "mixed"

# --- Content Strategy Honesty Check (REQUIRED — answer truthfully) ---
publishes_for_search_intent_only: false  # Be honest. Were any articles published only because keywords had volume?
publishes_thin_content: false        # Articles under 500 words on substantive topics
publishes_aggregated_content: false  # Content that mostly summarizes others without adding value
uses_ai_for_bulk_content: false
ai_content_review_quality: ""        # "minimal", "moderate", "rigorous", "expert_review_required"
content_serves_genuine_user_need: ""  # 1-10 self-rating of how well content serves users vs ranks

# --- Helpful Content Markers (RECOMMENDED) ---
has_about_us_explaining_purpose: false
has_author_bios_with_credentials: false
has_original_research: false
has_first_hand_experience_demonstrated: false
has_clear_topical_focus: false
has_practical_value_per_article: false
publishes_only_what_audience_needs: false

# --- SEO-First Anti-Patterns (RECOMMENDED — be honest) ---
has_pages_targeting_high_volume_low_intent_keywords: false
has_doorway_pages: false
has_thin_aggregator_pages: false
has_AI_content_passed_off_as_expert: false
has_content_promising_what_it_doesnt_deliver: false
has_clickbait_titles_not_matching_content: false
has_padded_content_to_hit_word_count: false

# --- Refresh & Maintenance (REQUIRED) ---
content_review_cadence: ""           # "monthly", "quarterly", "annually", "never"
has_content_decay_process: false
retires_outdated_content: false
consolidates_redundant_content: false

3. What HCS Is

The Helpful Content System (HCS) is Google's evaluation framework — and now, ranking infrastructure — for distinguishing content that genuinely helps people from content that's primarily designed to rank in search. Launched August 2022 as a sitewide signal, HCS was integrated into Google's core ranking systems in the March 2024 core update. It now operates continuously rather than as a periodic update.

The HCS framework is centered on a simple but uncomfortable question: was this content made primarily for people, or made primarily for search engines? Google's algorithms attempt to detect content optimized for search rankings without genuinely serving the searcher's need. When detected, that content gets demoted — and the demotion can cascade across the entire site if the pattern is widespread.

HCS evaluates content using a "Who, How, and Why" framework:

Who created the content? Are they a real person with relevant expertise? Is there transparency about authorship?
How was the content created? What process produced it? Was AI involved? Was it reviewed?
Why was the content created? To genuinely help readers, or primarily to attract search traffic?

The framework is documented in Google's public guidance at developers.google.com/search/docs/fundamentals/creating-helpful-content. It overlaps significantly with E-E-A-T but is distinct: E-E-A-T evaluates whether the source is trustworthy; HCS evaluates whether the content itself serves users. A site can have strong E-E-A-T (credentialed authors, good security, accurate information) but weak HCS (publishing thin content, optimizing for keywords rather than user need).

The 2024-2026 evolution of HCS reflects Google's response to the AI content explosion. Google's December 2025 helpful content guidance updated the "Who, How, and Why" framework to explicitly address AI-generated content. The position: AI involvement isn't disqualifying. Low effort, generic content that doesn't serve users IS disqualifying. AI-assisted content that is thoroughly reviewed by experts, enriched with original insights, and serves a genuine user need can pass HCS. AI content that's mass-produced for SEO with minimal review fails HCS — and the December 2025 core update specifically targeted these patterns, with significant ranking losses for content farms.

The four behaviors HCS most directly punishes:

Volume-over-quality content strategies — sites that publish many articles per day on topics they don't have genuine expertise in
Search-intent-first content — articles that exist because a keyword has volume, not because the audience needs an answer
Aggregated/derivative content — articles that summarize what others have said without adding original insight
AI-generated content without expert review — bulk AI content optimized for ranking rather than helping

The four behaviors HCS rewards:

Topical authority through depth — sites that cover a focused set of topics deeply rather than broadly
First-hand experience and original insight — content that demonstrates the author actually did, used, or experienced what's being discussed
Clear practical value per article — every article should leave the reader with something they didn't have before
Editorial integrity — content created by people who care about the topic, reviewed by people who know the topic

4. Google's Self-Assessment Questions

Google publishes specific questions creators should ask themselves about their content. This is the official HCS self-evaluation framework. Apply these to every piece of content.

4.1 People-First Content Questions

Score each question Yes/No/Partial for each article being evaluated:

Content quality

Does the content provide original information, reporting, research, or analysis?
Does the content provide a substantial, complete, or comprehensive description of the topic?
Does the content provide insightful analysis or interesting information beyond the obvious?
If drawing on other sources, does the content avoid simply copying or rewriting them, and instead provide substantial additional value and originality?
Does the main heading or page title provide a descriptive, helpful summary of the content?
Does the main heading or page title avoid exaggerating or being shocking in nature?
Is this the sort of page you'd want to bookmark, share with a friend, or recommend?
Would you expect to see this content in or referenced by a printed magazine, encyclopedia, or book?
Does the content provide substantial value when compared to other pages in search results?
Does the content have any spelling or stylistic issues?
Is the content produced well, or does it appear sloppy or hastily produced?
Is the content mass-produced by or outsourced to a large number of creators, or spread across a large network of sites, so that individual pages or sites don't get as much attention or care?

Expertise

Does the content present information in a way that makes you want to trust it, such as clear sourcing, evidence of the expertise involved, background about the author or the site that publishes it?
If you researched the site producing the content, would you come away with an impression that it is well-trusted or widely-recognized as an authority on its topic?
Is this content written or reviewed by an expert or enthusiast who demonstrably knows the topic well?
Does the content have any easily-verified factual errors?

Page experience

Does the page have a clear purpose or focus?
Given the topic, does the page provide a satisfying experience?
Does the page have an intrusive amount of ads, including pop-ups, interstitials, or anything that distracts from the main content?
Does the page display well for mobile devices?

4.2 SEO-First Content Red Flags (Avoid These)

Google explicitly warns that creating content with these patterns is a problem:

Is content primarily made to attract people from search engines, rather than made for humans?
Are you producing lots of content on different topics in hopes that some of it might perform well in search results?
Are you using extensive automation to produce content on many topics?
Are you mainly summarizing what others have to say without adding much value?
Are you writing about things simply because they seem trending, and not because you'd write about them otherwise for your existing audience?
Does your content leave readers feeling they need to search again to get better information from other sources?
Are you writing to a particular word count because you've heard or read that Google has a preferred word count?
Did you decide to enter some niche topic area without any real expertise, but mainly because you thought you'd get search traffic?
Does your content promise to answer a question that actually has no answer, such as suggesting there's a release date for a product, movie, or TV show when one isn't confirmed?
Are you changing the date of pages to make them seem fresh when the content has not substantially changed?
Are you adding lots of new content or removing lots of older content primarily because you believe it will help your search rankings overall by somehow making your site seem fresh?

4.3 The "Who, How, Why" Framework

For every piece of content, document:

Who created it?

Real person or AI?
If real: what's their relevant expertise?
If AI-assisted: what role did AI play, and what role did humans play?
Is the creator's identity transparent on the page?

How was it created?

What was the editorial process?
Was original research conducted?
Was firsthand experience involved?
Was the content reviewed by someone qualified?
If AI was used, what was the review and editing process?

Why was it created?

To genuinely help the audience solve a problem? (good)
To demonstrate or document the creator's expertise on a topic they care about? (good)
To target a search keyword the site has no genuine authority on? (bad)
To increase publication volume for SEO? (bad)
Because someone said the keyword had high volume? (bad)

The "why" is the hardest to be honest about. Most low-quality SEO content is created by people who would never admit it's primarily for search engines. The honest test: would you publish this article if Google didn't exist? If no, it's probably search-first content.

5. Per-Article HCS Implementation

What every article must include to demonstrate HCS compliance.

5.1 The Five HCS Markers

Every article must visibly demonstrate these markers:

5.1.1 Clear creator identity

Author byline at the top of every article with link to author page. The author must be a real person with verifiable expertise. See framework-eeat.md Section 4.2 for full implementation. HCS adds the requirement that anonymous content is a red flag — even pseudonymous bylines should explain why pseudonymity is appropriate.

5.1.2 Demonstrable original value

Every article must add something not available in the top-ranked search results for the query. Original value can be:

Original research or data
First-hand experience or testing
Synthesis that connects ideas in a new way
Specific examples not available elsewhere
Counterintuitive findings or contrarian analysis
Updated information based on the author's recent work
Failure cases and edge cases the author has personally encountered

Build an "original value" sidebar on long-form articles:

<aside class="original-value" aria-label="What this article adds">
  <h3>What This Article Adds</h3>
  <p>Most articles on {{TOPIC}} cover {{COMMON_COVERAGE}}. This article goes further with:</p>
  <ul>
    <li>{{ORIGINAL_CONTRIBUTION_1}}</li>
    <li>{{ORIGINAL_CONTRIBUTION_2}}</li>
    <li>{{ORIGINAL_CONTRIBUTION_3}}</li>
  </ul>
</aside>

5.1.3 Comprehensive coverage when relevant

If the article promises to be a "complete guide" or "everything you need to know," it must actually be comprehensive. Use a coverage checklist in the article structure:

<nav class="article-coverage" aria-label="What this article covers">
  <h2>What This Guide Covers</h2>
  <ol>
    {{LIST_OF_SECTIONS_WITH_LINKS_TO_HEADINGS}}
  </ol>
</nav>

If you can't be comprehensive, don't claim to be. Title and meta should match the actual depth.

5.1.4 Honest meta and titles

Title and meta description must accurately describe the content. Anti-patterns:

"Ultimate Guide to X" when the article is 800 words of basics
"X Things You Didn't Know" when the things are well-known
"Best X for Y" when the article is just a list of things, not a real comparison
Question titles that the article doesn't actually answer
Numerical titles ("10 X") when the content has artificially padded to hit the number

Honest title test: would the article meet the searcher's expectation if they clicked from the title alone, without reading the meta?

5.1.5 No trailing fluff

End the article when the value is delivered. HCS-compliant articles avoid:

Conclusion paragraphs that restate what was said
"I hope this article helped" filler
Padding to hit a target word count
"Stay tuned for more articles like this" engagement bait
AI-generated boilerplate endings

End the article with: a clear takeaway, a next step, a related resource, or a question for the reader. Not filler.

5.2 The HCS Article Template

Combining the markers above:

<article class="article hcs-compliant">
  <!-- Metadata header -->
  <header>
    <h1>{{ACCURATE_TITLE_THAT_MATCHES_CONTENT}}</h1>

    <div class="article-byline">
      <img src="{{AUTHOR_PHOTO}}" alt="{{AUTHOR_NAME}}">
      <p>By <a href="/authors/{{AUTHOR_SLUG}}/" rel="author">{{AUTHOR_NAME}}</a></p>
      <p class="byline-credentials">{{RELEVANT_CREDENTIALS_FOR_THIS_TOPIC}}</p>
      <time datetime="{{PUBLISHED}}">Published {{PUBLISHED_HUMAN}}</time>
      <time datetime="{{UPDATED}}">Updated {{UPDATED_HUMAN}}</time>
    </div>

    {{IF_AI_USED}}
    <aside class="ai-disclosure">
      This article {{AI_USAGE_LEVEL}}. Reviewed and verified by {{REVIEWER_NAME}}.
    </aside>
    {{/IF}}
  </header>

  <!-- Original value indicator -->
  <aside class="original-value">
    <h2>What This Article Adds</h2>
    <ul>
      {{ORIGINAL_CONTRIBUTIONS}}
    </ul>
  </aside>

  <!-- Coverage promise (if comprehensive guide) -->
  {{IF_COMPREHENSIVE_GUIDE}}
  <nav class="article-coverage">
    <h2>What This Guide Covers</h2>
    {{TOC}}
  </nav>
  {{/IF}}

  <!-- Article body — substantive content -->
  <div class="article-body">
    {{CONTENT_THAT_DELIVERS_ON_THE_TITLE_PROMISE}}

    <!-- First-hand experience callout when applicable -->
    {{IF_PRACTICAL_CONTENT}}
    <aside class="experience-callout">
      <h3>How I Know This Works</h3>
      <p>{{SPECIFIC_EXPERIENCE_DETAILS}}</p>
    </aside>
    {{/IF}}

    <!-- Original imagery, screenshots, data visualizations -->
    {{ORIGINAL_VISUAL_CONTENT}}

    <!-- Failure cases for practical content -->
    {{IF_LONG_FORM_PRACTICAL}}
    <section class="failures-edge-cases">
      <h2>What Doesn't Work</h2>
      {{SPECIFIC_FAILURES_OR_EDGE_CASES}}
    </section>
    {{/IF}}
  </div>

  <!-- End cleanly: takeaway, next step, or related -->
  <footer>
    <section class="article-takeaway">
      <h2>Key Takeaway</h2>
      <p>{{ONE_SENTENCE_TAKEAWAY}}</p>
    </section>

    <section class="article-next-step">
      <h2>Next Step</h2>
      <p>{{SPECIFIC_RECOMMENDATION_FOR_THE_READER}}</p>
    </section>

    {{REFERENCES_IF_FACTUAL_CONTENT}}
    {{AUTHOR_BOX}}
    {{RELATED_ARTICLES_GENUINELY_RELATED}}
  </footer>
</article>

5.3 What to Remove from Articles

To be HCS-compliant, audit every article for and remove:

Generic introductions ("In this article, we'll cover...") — get to the value
Unnecessary backstory before the core content
Padded sections that don't add value
Restated conclusions
Engagement bait ("Don't forget to subscribe!")
AI-generated transition sentences ("It's important to note that...", "Furthermore...")
Sections clearly added to hit keyword density or word count
"Did you know" filler facts unrelated to the user's actual question
Disclaimers buried in irrelevant places
Sales pitches for unrelated services
Pop-up newsletter prompts that interrupt the reading experience

6. Site-Wide HCS Implementation

Beyond per-article work, the site as a whole must signal HCS compliance.

6.1 Phase 1: Topical Focus Audit

Sites that try to cover everything do worse than sites with clear topical focus. HCS rewards depth over breadth.

6.1.1 Define the site's topical pillars

Identify 3-7 topics this site is genuinely the authority on. These should be:

Topics the founder or team has demonstrable expertise in
Topics where the site has unique perspective or experience
Topics where the site can publish original research or insights
Topics that connect to the business's actual offerings

Document at /topics/ or in an internal strategy doc:

Primary Topics (we are the authority):
1. {{TOPIC_1}} - {{WHY_WE_ARE_AUTHORITY}}
2. {{TOPIC_2}} - {{WHY_WE_ARE_AUTHORITY}}
3. {{TOPIC_3}} - {{WHY_WE_ARE_AUTHORITY}}

Secondary Topics (we have meaningful coverage):
1. {{TOPIC_4}}
2. {{TOPIC_5}}

Topics We Don't Cover (and why):
- {{ADJACENT_TOPIC}} - {{REASON_NOT_COVERED}}

6.1.2 Audit existing content against pillars

For every existing piece of content:

Does it fit a primary or secondary pillar? (keep)
Is it a one-off article on an unrelated topic? (consolidate or remove)
Is it an old SEO experiment that doesn't fit our focus? (remove)
Is it duplicative of better existing content? (consolidate)

The result: a content inventory where every remaining article reinforces topical authority on a defined pillar.

6.2 Phase 2: Topical Hub Pages

Each primary pillar gets a dedicated hub page demonstrating depth.

<article class="topical-hub" itemscope itemtype="https://schema.org/CollectionPage">
  <h1>{{TOPIC_NAME}}</h1>

  <section class="hub-introduction">
    <p>{{200_400_WORD_AUTHORITATIVE_INTRO_DEMONSTRATING_DEPTH}}</p>
  </section>

  <section class="hub-our-perspective">
    <h2>Our Perspective on {{TOPIC}}</h2>
    <p>{{WHAT_MAKES_THIS_SITES_TAKE_ON_THE_TOPIC_DISTINCTIVE}}</p>
  </section>

  <section class="hub-content-organized">
    <h2>{{TOPIC}} — Complete Coverage</h2>

    <h3>Foundations</h3>
    <ul>{{FOUNDATIONAL_ARTICLES}}</ul>

    <h3>Practical Application</h3>
    <ul>{{PRACTICAL_ARTICLES}}</ul>

    <h3>Advanced Topics</h3>
    <ul>{{ADVANCED_ARTICLES}}</ul>

    <h3>Original Research</h3>
    <ul>{{RESEARCH_ARTICLES}}</ul>
  </section>

  <section class="hub-related-pillars">
    <h2>Related Topics We Cover</h2>
    <ul>{{LINKS_TO_RELATED_HUBS}}</ul>
  </section>

  <section class="hub-not-covered">
    <h2>Topics We Don't Cover (And Where to Find Them)</h2>
    <p>{{HONEST_GUIDANCE_TO_OTHER_AUTHORITATIVE_SOURCES}}</p>
  </section>
</article>

The "honest guidance to other sources" section is counterintuitive but powerful. Pointing readers to legitimate authorities on adjacent topics demonstrates editorial integrity and improves user satisfaction.

6.3 Phase 3: About Page That Explains the Site's Purpose

Google's HCS guidance specifically asks: "If you researched the site producing the content, would you come away with an impression that it is well-trusted or widely-recognized as an authority on its topic?"

The About page is the answer. Build at /about/ with:

<article class="about-page">
  <h1>About {{BUSINESS_NAME}}</h1>

  <section class="why-we-exist">
    <h2>Why We Exist</h2>
    <p>{{SPECIFIC_PROBLEM_THE_SITE_SOLVES_FOR_AUDIENCE}}</p>
    <p>{{HOW_THE_SITE_IS_DIFFERENT_FROM_ALTERNATIVES}}</p>
  </section>

  <section class="who-we-are">
    <h2>Who We Are</h2>
    <p>{{FOUNDER_BIO_WITH_RELEVANT_EXPERIENCE}}</p>
    <p>{{TEAM_INFO_IF_APPLICABLE}}</p>
  </section>

  <section class="what-we-cover">
    <h2>What We Cover</h2>
    <ul>{{LIST_OF_PRIMARY_PILLARS_WITH_LINKS}}</ul>
  </section>

  <section class="what-we-dont-cover">
    <h2>What We Don't Cover</h2>
    <p>{{HONEST_DESCRIPTION_OF_TOPICS_OUTSIDE_SCOPE}}</p>
  </section>

  <section class="our-process">
    <h2>How We Create Content</h2>
    <ul>
      <li>{{CONTENT_CREATION_PROCESS_DETAIL}}</li>
      <li>{{REVIEW_PROCESS_DETAIL}}</li>
      <li>{{FACT_CHECKING_DETAIL}}</li>
      <li>{{IF_AI_USED_HOW}}</li>
    </ul>
    <p>See our <a href="/editorial-policy/">editorial policy</a> for full details.</p>
  </section>

  <section class="our-relationships">
    <h2>Our Relationships and Commitments</h2>
    <p>{{INDEPENDENCE_STATEMENT}}</p>
    <p>{{ANY_AFFILIATE_OR_PARTNERSHIP_CONTEXT}}</p>
    <p>See our <a href="/disclosure/">full disclosures</a>.</p>
  </section>

  <section class="contact">
    <h2>How to Reach Us</h2>
    <p>{{CONTACT_INFO}}</p>
    <p>Editorial questions: <a href="mailto:editorial@{{DOMAIN}}">editorial@{{DOMAIN}}</a></p>
  </section>
</article>

6.4 Phase 4: Content Removal & Consolidation

Sites with significant low-quality content drag their entire site's HCS score down. HCS evaluates the site holistically — even good articles can underperform if they're surrounded by low-quality content.

6.4.1 Removal candidates

Remove or noindex content that:

Is thin (under 500 words on a substantive topic)
Has no original insight (purely aggregated/derivative)
Is outdated and not refreshed
Duplicates other content on the site
Was published as an SEO experiment without genuine expertise
Has consistently low engagement metrics
Is no longer aligned with the site's topical focus

6.4.2 Consolidation candidates

Consolidate content where:

Multiple articles cover overlapping ground
A series of thin articles could become one comprehensive piece
Old articles are still relevant but need merging with newer ones

6.4.3 Consolidation pattern

When merging multiple articles into one comprehensive piece:

Identify the strongest URL to keep (best-ranked, oldest authoritative URL, or cleanest URL structure)
Merge content from the others into the kept URL
Improve the merged article significantly — don't just stitch text together
301 redirect the consolidated URLs to the kept URL
Update internal links to point to the kept URL
Re-submit sitemap

6.5 Phase 5: AI Content Disclosure & Strategy

If AI is used in content creation, HCS requires more than just disclosure. Google's December 2025 guidance specifically asks "Why" content was created — using AI for bulk publication is a "Why" failure.

6.5.1 What's acceptable AI use under HCS

AI for research assistance (gathering information for human writer)
AI for first-draft generation followed by extensive human revision
AI for grammar and style editing
AI for summarizing the writer's own notes
AI for outline generation that the writer fills in with original content
AI in content the writer reviews and takes professional responsibility for

6.5.2 What's not acceptable

AI generating articles that get published with minimal review
AI generating articles on topics the publishing entity has no genuine expertise in
AI content masquerading as written by a specific human author
AI churning out articles to hit publication volume goals
AI generating fake quotes, fake statistics, or fake experiences

6.5.3 AI disclosure on every AI-assisted article

<aside class="ai-content-disclosure">
  <h3>About this article</h3>
  <p>{{SPECIFIC_DESCRIPTION_OF_HOW_AI_WAS_USED}}</p>
  <p>This article was reviewed and edited by {{REVIEWER_NAME}}, {{CREDENTIALS}}.</p>
  <p>{{REVIEWER_NAME}} verified all factual claims, citations, and recommendations. They take professional responsibility for the accuracy of this content.</p>
  <p>See our <a href="/disclosure/">full AI use policy</a>.</p>
</aside>

6.6 Phase 6: Refresh Strategy (Not Date Manipulation)

HCS specifically warns against "changing the date of pages to make them seem fresh when the content has not substantially changed."

6.6.1 Genuine refresh process

When refreshing an article:

Read the article from the user's perspective — what's no longer accurate?
Update outdated information with current data
Add new sections covering developments since the last update
Remove sections that are no longer relevant
Update statistics, examples, screenshots
Verify all citations still work
Get reviewer sign-off if YMYL

Then update dateModified and add a changelog entry.

6.6.2 Article changelog

For substantive refreshes, document what changed:

<details class="article-changelog">
  <summary>Last updated {{UPDATED_DATE}} — see what changed</summary>
  <ul>
    <li><time datetime="{{UPDATE_1_DATE}}">{{UPDATE_1_DATE_HUMAN}}</time>: {{WHAT_CHANGED}}</li>
    <li><time datetime="{{UPDATE_2_DATE}}">{{UPDATE_2_DATE_HUMAN}}</time>: {{WHAT_CHANGED}}</li>
    <li><time datetime="{{UPDATE_3_DATE}}">{{UPDATE_3_DATE_HUMAN}}</time>: {{WHAT_CHANGED}}</li>
  </ul>
</details>

This proves the refresh was substantive, not just a date change.

7. Per-Article HCS Audit Criteria

Score each article:

#	Criterion	Severity
H1	Article addresses a genuine user need (not just a keyword)	Critical
H2	Title and meta accurately describe the content	Critical
H3	Content delivers on what the title promises	Critical
H4	Author has demonstrable expertise on this specific topic	Critical
H5	Article adds original value beyond what's in top SERP results	High
H6	First-person experience or original research demonstrated	High
H7	No padding to hit word count	Medium
H8	No unnecessary fluff intro or trailing filler	Medium
H9	Original imagery (not just stock)	Medium
H10	Comprehensive coverage if claimed	High
H11	Honest about what's not covered	Low
H12	If AI was used, transparently disclosed and reviewed	Critical (if applicable)
H13	Last refresh was substantive (if claimed as updated)	High
H14	Content is well-organized and scannable	Medium
H15	Page experience is good (load speed, no intrusive ads)	High

Score: 30 max. World-class HCS article: 26+/30 with zero Critical fails.

8. Site-Wide HCS Audit Criteria

#	Criterion	Severity
HS1	Site has clear topical focus (3-7 pillars, not unlimited topics)	Critical
HS2	About page explains the site's purpose, audience, and creators	Critical
HS3	Topical hub pages exist for each primary pillar	High
HS4	Editorial policy documented	High
HS5	All authors have credentials matching topics they cover	Critical
HS6	No thin content or doorway pages	Critical
HS7	No content that exists only because keyword has volume	Critical
HS8	AI use is disclosed where applicable	Critical (if applicable)
HS9	Refresh strategy is genuine, not date manipulation	High
HS10	Outdated content is refreshed or retired	High
HS11	No mass-produced content patterns	Critical
HS12	Site doesn't make promises content doesn't deliver	Critical

Score: 24 max. World-class HCS site: 21+/24 with zero Critical fails.

9. Common HCS Mistakes & Anti-Patterns

9.1 Keyword-First Content Strategy

Anti-pattern: Selecting topics based on keyword volume regardless of whether the site has genuine expertise.

Why it fails: Google's HCS specifically targets this pattern. Even well-written articles on topics outside the site's authority struggle.

Fix: Topic selection must start with "what does our audience genuinely need?" not "what has high search volume?"

9.2 AI Content Volume Strategy

Anti-pattern: "We can publish 100 articles per month with AI." Mass-produced AI content with minimal review.

Why it fails: December 2025 core update specifically targeted this. Sites with this pattern lost significant traffic.

Fix: Either dramatically slow publication and improve review quality, or remove the AI content. Quality > quantity.

9.3 "Comprehensive Guide" Without Depth

Anti-pattern: Title says "complete guide" but article is 1500 words of basics.

Why it fails: Title-content mismatch is a Trust violation and HCS failure.

Fix: Either deliver actual comprehensive coverage (often 3000-8000+ words for genuinely comprehensive guides) or change the title.

9.4 Forced Word Count

Anti-pattern: "Articles need to be 2000 words to rank." Padded content to hit a number.

Why it fails: HCS specifically warns about this. Padded content is detectable and fails the user.

Fix: Length matches content needs. A 600-word article that perfectly answers the question outranks a padded 2000-word article.

9.5 Trending Topics Without Genuine Coverage

Anti-pattern: Site that normally covers cooking suddenly publishes articles about cryptocurrency because crypto is trending.

Why it fails: HCS asks "Are you writing about things simply because they seem trending?" Yes is a failure.

Fix: Stay in your lane. Cover what you genuinely know.

9.6 Date Refresh Without Content Refresh

Anti-pattern: Updating dateModified without substantively updating content.

Why it fails: Google detects this pattern. It's a Trust violation.

Fix: Update dates only when content was genuinely updated. Document what changed.

9.7 Generic AI Boilerplate

Anti-pattern: AI-generated articles with telltale phrases ("It's important to note...", "Furthermore...", "In conclusion...") and no specific examples or insights.

Why it fails: Detectable, generic, doesn't serve users.

Fix: Either rewrite to remove AI boilerplate and add specific value, or remove the article.

9.8 Aggregator Pages Without Original Insight

Anti-pattern: "The 10 best X tools" articles that just describe what each tool does without any actual evaluation, testing, or insight.

Why it fails: Low original value. The article doesn't add anything beyond visiting each tool's homepage.

Fix: Test the tools, document the testing, share specific findings, give a recommendation based on real evaluation.

9.9 Hidden Affiliate Optimization

Anti-pattern: "Best X for Y" article that's structured around which products have the best affiliate commissions.

Why it fails: HCS detects mismatch between recommendation and user need. Long-term Trust damage.

Fix: Recommendations based on actual user benefit. Disclose affiliates clearly.

9.10 Content Without a Real Person

Anti-pattern: "Editorial Team" or no byline at all on substantive content. Generic about pages.

Why it fails: HCS asks who created the content. Anonymous content is suspect.

Fix: Real author bylines. Real about pages.

10. Stack-Specific HCS Implementation

10.1 WordPress

Use Yoast or Rank Math to enforce title-meta-content alignment
Build content review workflow into Editorial Calendar
Custom fields per article: "What this article adds," "Author's experience with this topic"
Plugin to detect duplicate content and consolidation candidates

10.2 Next.js / Astro / Hugo

Type-safe content frontmatter requiring HCS metadata
Pre-publish CI/CD check that requires HCS markers (author, original value, etc.)
Build script generates topical hub pages from article frontmatter
Static analysis of content for AI boilerplate patterns

10.3 Universal Pattern

The HCS workflow:

Topic selection: passes "is this in our authority area?" test
Drafting: passes "what does this add?" test
Reviewing: passes "would a reader feel this was worth their time?" test
Publishing: HCS markers all present
Monitoring: track engagement metrics; revise or retire underperforming content
Refreshing: substantive updates only; document changes

11. Validation Protocol

11.1 Per-Article Validation

Sample 10% of articles. For each:

Read it as if you found it in search results
Apply Google's self-assessment questions (Section 4.1)
Score Pass/Partial/Fail per HCS criterion (Section 7)
Document findings

11.2 Site-Wide Validation

Audit topical focus — do articles cluster around clear pillars?
Inventory content quality — what percentage is high-quality vs thin/derivative?
Check for HCS-failing patterns (Section 9)
Evaluate About page against Section 6.3 requirements
Score against Section 8 criteria

11.3 Honesty Test

The hardest HCS validation: ask someone outside the site (a peer, a target audience member, an industry colleague) to read sample articles and answer:

"Did this article help you?"
"Did you trust the source?"
"Would you bookmark or share this?"
"Would you come back to this site?"
"Could you tell if this was AI-written or written by a real expert?"

External honest feedback is the most reliable HCS signal.

12. Audit Mode

Total HCS audit: 54 points (30 per-article average + 24 site-wide).

Score	Status
48-54	World-class HCS compliance
41-47	Compliant with minor gaps
30-40	Significant gaps requiring remediation
<30	Critical HCS failures — major content overhaul needed

A site with critical HCS fails (HS1, HS5, HS6, HS7, HS11, HS12) is at significant risk for ranking suppression in core updates regardless of E-E-A-T or technical SEO strength.

13. Maintenance Schedule

13.1 Weekly

Check newly published content for HCS markers
Review one piece of older content for refresh or retirement

13.2 Monthly

Audit recent publications against HCS criteria
Track engagement metrics to identify decay candidates
Review and update one topical hub page

13.3 Quarterly

Site-wide HCS audit
Review topical pillar definitions — still accurate?
Inventory removal/consolidation candidates
Update About page if business or focus has shifted

13.4 Annually

Comprehensive content inventory and quality scoring
Reduce content footprint if quality issues exist
Strategic review: are we publishing for users or for search?
Update editorial policy

13.5 Post-Core-Update

After every confirmed Google core update (typically 3-4 per year):

Identify pages that lost ranking
Apply HCS criteria to those pages
Look for patterns — what failed?
Remediate per HCS framework
Track recovery over 30-60 days

14. Implementation/Audit Report Templates

14.1 HCS Implementation Report Template

# HCS Framework Implementation Report

**Project**: {{BUSINESS_NAME}}
**Implementation Date**: {{TODAY}}

## Summary
- Total content audited: {{COUNT}}
- Content kept (high quality): {{COUNT}}
- Content refreshed substantively: {{COUNT}}
- Content consolidated: {{COUNT}}
- Content removed: {{COUNT}}

## Topical Pillars Defined
{{LIST_OF_PILLARS}}

## Hub Pages Created
{{LIST_OF_HUB_URLS}}

## About Page Updated
{{STATUS_AND_KEY_ADDITIONS}}

## AI Use Policy
{{POLICY_STATUS}}

## HCS Markers Installed Per Article Type
{{TABLE}}

## Items Flagged for Manual Review
{{LIST}}

## Validation Results
{{AUTOMATED_AND_MANUAL_RESULTS}}

## Sign-Off
Implementation complete: {{DATE}}

14.2 HCS Audit Report Template

# HCS Framework Audit Report

**Site**: {{BUSINESS_NAME}}
**Audit Date**: {{TODAY}}

## Executive Summary
{{ONE_PARAGRAPH_ASSESSMENT}}

**Overall Score**: {{X}}/54
**Status**: {{STATUS}}

## Topical Focus Assessment
{{FINDINGS}}

## Content Quality Distribution
- High-quality content: {{PERCENTAGE}}%
- Acceptable content: {{PERCENTAGE}}%
- Thin/derivative content: {{PERCENTAGE}}%

## Critical HCS Failures
{{LIST_WITH_REMEDIATION}}

## Per-Article Findings (Sample of 10%)
{{DETAILED_FINDINGS}}

## Site-Wide Findings
{{DETAILED_FINDINGS}}

## Recommended Remediation Order
1. Critical: {{PRIORITY_1}}
2. High: {{PRIORITY_2}}
3. Medium: {{PRIORITY_3}}

## Estimated Remediation Effort
{{HOURS}}

## Sign-Off

End of Framework Document

Document version: 1.0
Last updated: 2026-04-29
Maintained by: ThatDeveloperGuy

HCS is the evaluation framework for content quality — but more importantly, it's an honest mirror for content strategy. Sites that genuinely serve their audience pass HCS naturally. Sites that prioritize search rankings over user value fail HCS regardless of how clever the SEO is. The fastest path to HCS compliance is the hardest one: be honest about why content exists, who it's for, and whether it's genuinely useful.

Companion documents:

framework-eeat.md
framework-ymyl.md
framework-sqrg.md
framework-coreupdates.md
framework-infogain.md
framework-entitysalience.md
framework-knowledgegraph.md
framework-aicitations.md

About this framework library

This article is the Dev.to republish of a framework reference document from ThatDevPro's SEO + AI engineering library. Canonical source: https://www.thatdevpro.com/insights/framework-hcs/

Companion 14-tier Engine Optimization stack (each tier is its own article):

Need this framework implemented on your site? See the Engine Optimization service or hire through ThatDevPro contact.

YMYL: when Google holds you to higher standards

Joseph Anady — Sun, 24 May 2026 01:03:53 +0000

Originally published at thatdevpro.com. Part of ThatDevPro's open SEO + AI framework library. ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.

Your Money or Your Life — Content Sensitivity Classification & High-Stakes Quality Standards

A comprehensive installation and audit reference for identifying YMYL content on a website, applying the elevated quality standards Google requires for it, and protecting both users and the business from the legal, regulatory, and ranking consequences of YMYL violations. This document is dual-purpose: installation manual and audit document.

Cross-stack implementation note: the code samples in this framework are written in plain HTML for clarity. For React, Vue, Svelte, Next.js, Nuxt, SvelteKit, Astro, Hugo, 11ty, Remix, WordPress, Shopify, and Webflow equivalents of every pattern below, see framework-cross-stack-implementation.md. For pure client-rendered SPAs (no SSR/SSG) see framework-react.md. For Tailwind-specific concerns (purge, dynamic classes, dark-mode CLS, focus accessibility) see framework-tailwind.md.

1. Document Purpose & How to Use This Document

1.1 What This Document Is

This is the canonical reference for classifying website content under Google's YMYL framework and implementing the elevated quality standards YMYL content requires. Every category Google considers YMYL is documented here. Every signal Google's Search Quality Raters look for in YMYL content is specified. Every code block, schema, and structural requirement needed to meet the YMYL bar is included.

1.2 Three Operating Modes

Mode A — Install Mode: Building YMYL-compliant infrastructure into a new or existing site. Follow Sections 2 → 17 in order.

Mode B — Audit Mode: Evaluating an existing site for YMYL classification and compliance. Skip to Section 12.

Mode C — Hybrid Mode: Audit then install for failing items.

1.3 How Claude Code CLI Should Consume This Document

Read Section 2 — collect all client variables, especially YMYL category determinations
Run Section 3 — apply the YMYL classification decision tree to determine site or per-page YMYL status
Detect existing state — check what YMYL trust elements already exist
Follow phases in order — site-wide foundations before per-content-type elements
Validate after each phase
Generate the report — Section 17

1.4 Conflict Resolution Rules

Conflict	Rule
Existing medical/legal/financial disclaimer	Audit for completeness. Add missing elements. Do not remove existing disclaimer language without legal review.
Existing reviewer credit	Verify reviewer credentials. Update only if reviewer has changed.
Existing editorial policy page	Audit against Section 5.2.9 requirements. Add missing elements. Preserve customizations.
Existing corrections process	Verify it matches the policy page. Document any inconsistencies for manual review.
Existing content classified differently than this framework recommends	Flag for manual review with the legal/compliance owner. Do not reclassify automatically.

1.5 Required Tools & Validators

Whitespark / BrightLocal / Moz Local — for citation consistency audit
PubMed — for primary medical literature citations (health YMYL)
SEC EDGAR — for primary financial source citations (finance YMYL)
Westlaw / LexisNexis / CourtListener — for primary legal sources (legal YMYL)
FTC.gov — for compliance reference on advertising/affiliate disclosures
State Attorney General sites — for state-specific privacy and consumer protection law
Originality.ai — for AI content detection (Trust signal validation)

2. Client Variables Intake

# ============================================
# YMYL FRAMEWORK CLIENT VARIABLES
# ============================================

# --- Business Classification (REQUIRED) ---
business_name: ""
primary_domain: ""
business_industry: ""
state_of_operation: ""               # Primary state — affects regulatory framework
states_served: []                    # All states where the business operates

# --- YMYL Classification (REQUIRED) ---
ymyl_overall_classification: ""      # "full_ymyl", "partial_ymyl", "lite_ymyl", "non_ymyl"
ymyl_categories: []                  # Categories applicable to this site:
                                     # "health_medical", "mental_health", "fitness_nutrition",
                                     # "financial_advice", "investing", "tax", "banking", "insurance",
                                     # "legal_advice", "civic_government", "elections",
                                     # "safety_personal", "safety_occupational",
                                     # "major_life_decisions", "news_current_events",
                                     # "shopping_ecommerce"

# --- Content Inventory (REQUIRED for audit) ---
total_content_pieces: 0
ymyl_content_pieces: 0
ymyl_content_percentage: 0.0
ymyl_content_types: []               # "articles", "calculators", "tools", "directories", etc.

# --- Author/Reviewer Credentials (REQUIRED for full YMYL) ---
primary_authors:
  - name: ""
    credentials: []                  # Required: degrees, licenses, board certifications
    license_number: ""               # Where applicable (medical, legal, financial)
    license_state: ""                # Where applicable
    license_verification_url: ""     # Public verification link
    years_practicing: 0
    specialty_areas: []
    conflicts_of_interest: []

medical_reviewers:                   # Required for health YMYL
  - name: ""
    credentials: []                  # MD, RN, NP, DO, PhD, etc.
    license_number: ""
    license_state: ""
    npi_number: ""                   # National Provider Identifier
    specialty: ""
    affiliations: []                 # Hospital systems, academic institutions

legal_reviewers:                     # Required for legal YMYL
  - name: ""
    bar_admission: []                # State(s) where admitted
    bar_number: ""
    practice_areas: []
    firm_affiliation: ""

financial_reviewers:                 # Required for finance YMYL
  - name: ""
    credentials: []                  # CFP, CFA, CPA, ChFC, RIA registration
    sec_registration: ""             # If applicable
    finra_crd: ""                    # If applicable
    state_registrations: []
    specialty: ""

# --- Compliance Posture (REQUIRED) ---
hipaa_applicable: false              # Health entities subject to HIPAA
ferpa_applicable: false              # Educational records
glba_applicable: false               # Financial services
sox_applicable: false                # Public companies
fcra_applicable: false               # Consumer reporting
finra_member: false                  # Securities-related
sec_registered: false                # Investment advisor
state_insurance_licensed: []         # States with insurance license
attorney_advertising_compliant: false # If legal services

# --- Editorial Process (REQUIRED) ---
has_editorial_policy: false
has_corrections_policy: false
has_fact_checking_process: false
fact_checking_methodology: ""        # Brief description
review_cadence: ""                   # "monthly", "quarterly", "biannually", "annually"
content_source_standards: ""         # "primary_only", "primary_plus_secondary", etc.

# --- Disclosures (REQUIRED) ---
has_medical_disclaimer: false
has_financial_disclaimer: false
has_legal_disclaimer: false
has_general_advice_disclaimer: false
has_advertising_disclosure: false
has_affiliate_disclosure: false
has_sponsored_content_disclosure: false
has_ai_use_disclosure: false
has_conflict_of_interest_disclosure: false
has_results_may_vary_disclaimer: false  # For testimonials/case studies

# --- AI Use in YMYL Content (REQUIRED) ---
uses_ai_in_ymyl_content: false
ai_review_protocol_for_ymyl: ""      # If true: must describe stricter review for YMYL specifically

# --- Existing Compliance Documentation ---
last_legal_review_date: ""
legal_counsel_firm: ""
last_compliance_audit_date: ""
known_compliance_gaps: []

After variables are gathered, save them as ymyl-variables.yml in the project root.

3. What YMYL Is

YMYL stands for Your Money or Your Life — Google's classification for content categories where inaccurate, misleading, or low-quality information can cause real-world harm to users' health, financial stability, safety, or wellbeing. The term originated in Google's Search Quality Rater Guidelines and refers to topics where Google holds content to dramatically higher quality standards than non-YMYL topics.

YMYL is not a separate ranking factor. It's a quality multiplier — a classification that tells Google's algorithms and human raters to apply elevated E-E-A-T standards to the content. A non-YMYL article scoring 80% on E-E-A-T audit might rank well; a YMYL article at 80% will likely struggle. The bar is meaningfully higher because the consequences of bad YMYL content are meaningfully more severe.

The September 2025 Search Quality Rater Guidelines update significantly expanded the YMYL category to explicitly include elections, civic institutions, and government information alongside the historical categories of health, finance, legal, and safety. This expansion reflects Google's growing concern about misinformation on high-stakes civic topics. Sites covering these topics now face the same elevated quality bar as health and finance sites.

YMYL applies at the page level, not the site level. A general-purpose blog might publish one YMYL article among many non-YMYL ones — that single article must meet YMYL standards. A site that's primarily YMYL (a medical site, a financial advisory site, a legal directory) must meet YMYL standards across nearly every page.

The four core consequences of getting YMYL wrong:

Ranking suppression — Google de-prioritizes YMYL content that doesn't meet the bar
AI engine de-citation — ChatGPT, Perplexity, Claude, Gemini avoid citing untrusted YMYL sources
Regulatory action — FTC, state AGs, professional licensing boards, and securities regulators have enforcement authority
Civil liability — Bad medical/legal/financial advice that causes harm creates legal exposure

This framework specifies how to identify YMYL content, what elevated standards apply, and how to install the trust infrastructure required.

4. The YMYL Classification Decision Tree

4.1 Primary YMYL Categories

Use this tree to classify each piece of content. If any branch returns YMYL, the content is YMYL.

Does the content cover any of the following?

├── Health & Medical
│   ├── Diagnosis or treatment of medical conditions → YMYL (health, full)
│   ├── Medication information, dosing, side effects → YMYL (health, full)
│   ├── Mental health advice or crisis information → YMYL (mental health, full)
│   ├── Nutrition advice with health claims → YMYL (health, partial)
│   ├── Fitness routines with injury risk → YMYL (health, partial)
│   ├── Supplements with medical claims → YMYL (health, full)
│   ├── Pregnancy, parenting infant care → YMYL (health, full)
│   ├── Veterinary medical advice → YMYL (health, partial)
│   └── General wellness lifestyle content → Non-YMYL (be cautious)
│
├── Financial
│   ├── Specific investment recommendations → YMYL (finance, full)
│   ├── Tax advice or strategy → YMYL (finance, full)
│   ├── Retirement planning advice → YMYL (finance, full)
│   ├── Loan/mortgage/credit advice → YMYL (finance, full)
│   ├── Insurance advice or comparisons → YMYL (finance, full)
│   ├── Cryptocurrency advice → YMYL (finance, full)
│   ├── General financial education → YMYL (finance, partial)
│   ├── Personal finance budgeting tips → YMYL (finance, partial)
│   └── Reviews of financial products → YMYL (finance, partial)
│
├── Legal
│   ├── Specific legal advice for situations → YMYL (legal, full)
│   ├── Court procedures and rights → YMYL (legal, full)
│   ├── Immigration guidance → YMYL (legal, full)
│   ├── Family law (divorce, custody) → YMYL (legal, full)
│   ├── Criminal law information → YMYL (legal, full)
│   ├── Estate planning/wills → YMYL (legal, full)
│   ├── Business legal information → YMYL (legal, partial)
│   ├── Legal directory listings → YMYL (legal, partial)
│   └── General "what is X law" reference → YMYL (legal, partial)
│
├── Civic & Government (expanded September 2025)
│   ├── Election information, voter rights → YMYL (civic, full)
│   ├── Government services and benefits → YMYL (civic, full)
│   ├── Public health information → YMYL (civic + health, full)
│   ├── Civic institutional information → YMYL (civic, full)
│   ├── Tax filing and government forms → YMYL (civic + finance, full)
│   └── Political opinion content → Non-YMYL (but information integrity matters)
│
├── Safety
│   ├── Personal safety (assault, abuse) → YMYL (safety, full)
│   ├── Occupational safety → YMYL (safety, full)
│   ├── Driving and vehicle safety → YMYL (safety, partial)
│   ├── Home safety (electrical, gas, structural) → YMYL (safety, partial)
│   ├── Drug/substance information → YMYL (safety + health, full)
│   ├── Outdoor/wilderness safety → YMYL (safety, partial)
│   └── Child safety → YMYL (safety, full)
│
├── Major Life Decisions
│   ├── Career changes and education → YMYL (significant)
│   ├── Relationship and divorce decisions → YMYL (significant)
│   ├── Major purchases (home, car) → YMYL (significant + finance)
│   ├── Adoption or fertility → YMYL (significant + health)
│   └── End-of-life planning → YMYL (significant + legal)
│
├── News & Current Events
│   ├── Breaking news with safety implications → YMYL (news, full)
│   ├── Investigative journalism → YMYL (news, full)
│   ├── Public health announcements → YMYL (news + health, full)
│   ├── Election coverage → YMYL (news + civic, full)
│   └── Entertainment news → Non-YMYL
│
└── E-Commerce
    ├── Health products, supplements → YMYL (lite + health-adjacent)
    ├── Financial products, insurance → YMYL (lite + finance-adjacent)
    ├── Safety equipment → YMYL (lite + safety-adjacent)
    ├── Children's products → YMYL (lite + safety-adjacent)
    └── General consumer goods → Non-YMYL (held to higher standards but not full YMYL)

4.2 Classification Levels Explained

Full YMYL — Maximum elevated standards apply. Author credentials must match topic regulatory requirements. Reviewer credit on every article. Primary literature citations only. Editorial and corrections policies required. Topic-specific disclaimers on every article. Monthly refresh cadence for time-sensitive content.

Partial YMYL — Elevated standards apply but with some flexibility. Credentialed author or reviewer required. Primary or high-quality secondary sources acceptable. Disclaimers required. Quarterly refresh cadence acceptable.

Lite YMYL — Higher than non-YMYL but lower than full YMYL. Credentialed author preferred but not strictly required for non-advice content. Standard review process. General disclaimers. Quarterly refresh.

Non-YMYL — Standard E-E-A-T rules apply (see framework-eeat.md).

4.3 Edge Cases & Judgment Calls

Personal experience YMYL — "How I paid off $50k in debt" or "My experience with chemo" can be valuable YMYL content even without formal credentials. Frame as personal experience, not authoritative advice. Use first-person language consistently. Never present personal experience as universal recommendation. Disclaimers must be especially clear that this isn't professional advice.

Aggregated YMYL — A site that aggregates content (directory of medical providers, comparison of financial products) is YMYL even if the site doesn't author the underlying advice. Aggregation introduces YMYL responsibility — the curation itself affects user decisions.

Ambiguous content — When uncertain, classify higher. The cost of treating non-YMYL content as YMYL is some extra rigor. The cost of treating YMYL content as non-YMYL is potential harm to users plus ranking suppression plus regulatory exposure.

Mixed-classification sites — Many sites have both YMYL and non-YMYL content. Apply YMYL standards to YMYL pages only. Make YMYL content visually distinct from non-YMYL content where helpful (different page templates, clearer reviewer credits, more prominent disclaimers).

5. YMYL-Specific Implementation Requirements

This section adds to the standard E-E-A-T installation. All E-E-A-T requirements still apply; YMYL content additionally requires everything in this section.

5.1 Phase 1: YMYL Inventory & Classification

Before installing any YMYL trust elements, classify the site's content.

5.1.1 Content audit script

For each piece of content on the site:

Read the URL, page title, and primary topic
Apply the decision tree from Section 4.1
Record YMYL classification: full / partial / lite / non
Record applicable categories (health, finance, legal, etc.)
Flag any content that's currently published as authoritative advice but lacks credentialed authorship

Create a classification spreadsheet at /admin/ymyl-inventory.csv:

url,title,primary_topic,ymyl_classification,categories,current_author,author_credentials,reviewer,reviewer_credentials,disclaimer_present,citations_present,last_review_date,risk_level,action_required
/articles/diabetes-medication-guide,Diabetes Medication Guide,health/medication,full_ymyl,"health_medical","Sarah Smith","none","none","none","partial","2025-04-15","critical","add_medical_reviewer_disclaimer_citations"

5.1.2 Risk-prioritized remediation queue

Sort the inventory by risk level:

Critical risk: YMYL content with no credentialed author/reviewer, no disclaimer, factual claims without citations
High risk: YMYL content missing reviewer or disclaimer
Medium risk: YMYL content with all elements but stale (>12 months since review)
Low risk: YMYL content fully compliant but minor enhancements possible

Remediate in order: Critical → High → Medium → Low. Critical-risk YMYL content should not remain published past 7 days.

5.2 Phase 2: Editorial Policy Page

Build at /editorial-policy/. This is mandatory for all YMYL sites.

5.2.1 Required content

<article class="editorial-policy">
  <h1>Editorial Policy</h1>

  <p>{{BUSINESS_NAME}} is committed to publishing accurate, helpful, and well-sourced content on topics that affect our readers' {{YMYL_CATEGORIES_PROSE}}. This editorial policy describes our content creation standards, review processes, and accountability mechanisms.</p>

  <h2>Our Authors and Reviewers</h2>
  <p>{{BUSINESS_NAME}} content is created and reviewed by individuals with verifiable credentials in their subject areas:</p>
  <ul>
    {{LIST_OF_AUTHORS_WITH_CREDENTIALS}}
    {{LIST_OF_REVIEWERS_WITH_CREDENTIALS}}
  </ul>
  <p>You can verify all author and reviewer credentials on their respective <a href="/authors/">author profile pages</a>.</p>

  <h2>Content Creation Process</h2>
  <ol>
    <li><strong>Topic selection:</strong> {{TOPIC_SELECTION_PROCESS}}</li>
    <li><strong>Research:</strong> {{RESEARCH_STANDARDS_PROSE}}</li>
    <li><strong>Drafting:</strong> {{DRAFTING_PROCESS_PROSE}}</li>
    <li><strong>Expert review:</strong> {{EXPERT_REVIEW_PROCESS_PROSE}}</li>
    <li><strong>Fact-checking:</strong> {{FACT_CHECKING_PROCESS_PROSE}}</li>
    <li><strong>Editorial review:</strong> {{EDITORIAL_REVIEW_PROCESS_PROSE}}</li>
    <li><strong>Publication:</strong> {{PUBLICATION_PROCESS_PROSE}}</li>
    <li><strong>Ongoing review:</strong> {{ONGOING_REVIEW_CADENCE_PROSE}}</li>
  </ol>

  <h2>Source Standards</h2>
  <p>For {{YMYL_CATEGORY}} content, we cite from primary sources:</p>
  <ul>
    {{IF_HEALTH}}<li>Peer-reviewed medical journals indexed in PubMed</li>{{/IF}}
    {{IF_HEALTH}}<li>FDA, NIH, CDC, and WHO official publications</li>{{/IF}}
    {{IF_FINANCE}}<li>SEC filings and EDGAR records</li>{{/IF}}
    {{IF_FINANCE}}<li>IRS publications and Treasury guidance</li>{{/IF}}
    {{IF_FINANCE}}<li>Federal Reserve, FDIC, and CFPB publications</li>{{/IF}}
    {{IF_LEGAL}}<li>Primary case law via Westlaw/LexisNexis/CourtListener</li>{{/IF}}
    {{IF_LEGAL}}<li>Federal and state statutes and regulations</li>{{/IF}}
    {{IF_LEGAL}}<li>Bar association ethics opinions</li>{{/IF}}
  </ul>

  <h2>Disclosures and Independence</h2>
  <p>{{BUSINESS_NAME}} maintains editorial independence. {{INDEPENDENCE_STATEMENT_PROSE}}</p>
  <p>When commercial relationships exist, they are disclosed at the article level. See our <a href="/disclosure/">full disclosures policy</a>.</p>

  <h2>Limitations and Disclaimers</h2>
  <p>Our content is informational and educational. {{TOPIC_SPECIFIC_DISCLAIMER_PROSE}}</p>
  <p>See: <a href="/medical-disclaimer/">Medical Disclaimer</a>, <a href="/financial-disclaimer/">Financial Disclaimer</a>, <a href="/legal-disclaimer/">Legal Disclaimer</a>.</p>

  <h2>Corrections and Updates</h2>
  <p>If you find an error in our content, please contact us. See our <a href="/corrections-policy/">Corrections Policy</a> for our process.</p>

  <h2>Contact</h2>
  <p>Editorial questions: <a href="mailto:editorial@{{PRIMARY_DOMAIN}}">editorial@{{PRIMARY_DOMAIN}}</a></p>
  <p>Last reviewed: <time datetime="{{LAST_REVIEW_DATE_ISO}}">{{LAST_REVIEW_DATE_HUMAN}}</time></p>
</article>

5.3 Phase 3: Corrections Policy Page

Build at /corrections-policy/. Mandatory for all YMYL sites.

<article class="corrections-policy">
  <h1>Corrections Policy</h1>

  <p>{{BUSINESS_NAME}} is committed to factual accuracy. When we publish errors, we correct them transparently.</p>

  <h2>How to Report an Error</h2>
  <p>If you find a factual error in any {{BUSINESS_NAME}} content, please contact us at <a href="mailto:corrections@{{PRIMARY_DOMAIN}}">corrections@{{PRIMARY_DOMAIN}}</a> with:</p>
  <ul>
    <li>The URL of the page containing the error</li>
    <li>The specific text or claim you believe is incorrect</li>
    <li>The correct information, with source if possible</li>
  </ul>

  <h2>Our Correction Process</h2>
  <ol>
    <li><strong>Acknowledge:</strong> We respond to correction requests within 2 business days.</li>
    <li><strong>Investigate:</strong> Our editorial team and (where applicable) subject matter expert reviewer evaluate the claim against primary sources.</li>
    <li><strong>Decide:</strong> If the claim is correct, we update the content. If we believe the original content was correct, we explain our reasoning.</li>
    <li><strong>Update:</strong> Corrections are made to the source content immediately.</li>
    <li><strong>Disclose:</strong> Material corrections are disclosed at the top of the article with the date of correction and the nature of the change.</li>
    <li><strong>Notify:</strong> If you reported the error, we follow up to inform you of the outcome.</li>
  </ol>

  <h2>Types of Corrections</h2>
  <dl>
    <dt>Material corrections</dt>
    <dd>Factual errors that change the meaning or recommendation of the content. These are disclosed at the top of the article and noted in our corrections log.</dd>

    <dt>Minor corrections</dt>
    <dd>Typos, grammatical errors, formatting issues. These are corrected silently.</dd>

    <dt>Updates</dt>
    <dd>Information that was correct at publication but has since changed (e.g., updated regulations). These are reflected via dateModified and noted in the article changelog.</dd>
  </dl>

  <h2>Corrections Log</h2>
  <p>We maintain a public log of all material corrections at <a href="/corrections-log/">/corrections-log/</a>.</p>

  <h2>Contact</h2>
  <p>Corrections: <a href="mailto:corrections@{{PRIMARY_DOMAIN}}">corrections@{{PRIMARY_DOMAIN}}</a></p>
</article>

Pair with a /corrections-log/ page that lists all material corrections with date, article URL, and nature of correction.

5.4 Phase 4: Topic-Specific Disclaimer Pages

Each YMYL category requires its own dedicated disclaimer page.

5.4.1 Medical disclaimer (/medical-disclaimer/) — for health YMYL

<article class="medical-disclaimer">
  <h1>Medical Disclaimer</h1>

  <p>The information provided on {{BUSINESS_NAME}} ({{PRIMARY_DOMAIN}}) is for general informational and educational purposes only. <strong>It is not a substitute for professional medical advice, diagnosis, or treatment.</strong></p>

  <h2>Always Seek Professional Medical Advice</h2>
  <p>Always seek the advice of a qualified healthcare provider with any questions you may have regarding a medical condition. Never disregard professional medical advice or delay seeking it because of something you have read on this website.</p>

  <h2>Emergency Situations</h2>
  <p><strong>If you think you may have a medical emergency, call 911 (or your local emergency number) or go to the nearest emergency room immediately.</strong></p>

  <p>If you are experiencing thoughts of suicide or self-harm:</p>
  <ul>
    <li>988 Suicide & Crisis Lifeline (US): Call or text 988</li>
    <li>Crisis Text Line: Text HOME to 741741</li>
    <li>International Association for Suicide Prevention: <a href="https://www.iasp.info/resources/Crisis_Centres/" rel="noopener">https://www.iasp.info/resources/Crisis_Centres/</a></li>
  </ul>

  <h2>No Doctor-Patient Relationship</h2>
  <p>Reading content on {{BUSINESS_NAME}} does not create a doctor-patient or healthcare provider relationship between you and {{BUSINESS_NAME}}, its authors, its medical reviewers, or anyone else affiliated with the site.</p>

  <h2>Individual Variation</h2>
  <p>Medical information presented on this site is general. Individual circumstances vary, and what is appropriate for one person may not be appropriate for another. Always consult with your healthcare provider before making decisions about your health.</p>

  <h2>Medications and Treatments</h2>
  <p>Information about medications, treatments, and procedures is for educational purposes. {{BUSINESS_NAME}} does not endorse or recommend any specific test, physician, product, procedure, opinion, or other information that may be mentioned on the site. Reliance on any information provided by {{BUSINESS_NAME}} is solely at your own risk.</p>

  <h2>Currency of Information</h2>
  <p>Medical knowledge evolves rapidly. While we work to keep our content current — see our <a href="/editorial-policy/">Editorial Policy</a> — information may not reflect the latest guidance. Always verify with your healthcare provider.</p>

  <h2>External Links</h2>
  <p>{{BUSINESS_NAME}} may contain links to external websites. We are not responsible for the content of those external sites and inclusion of a link does not constitute endorsement.</p>

  <h2>Editorial Standards</h2>
  <p>Our content is created by {{AUTHOR_DESCRIPTION}} and reviewed by licensed medical professionals. See our <a href="/editorial-policy/">Editorial Policy</a> for details.</p>

  <p><time datetime="{{LAST_UPDATED_ISO}}">Last updated: {{LAST_UPDATED_HUMAN}}</time></p>
</article>

5.4.2 Financial disclaimer (/financial-disclaimer/) — for finance YMYL

<article class="financial-disclaimer">
  <h1>Financial Disclaimer</h1>

  <p>The information provided on {{BUSINESS_NAME}} ({{PRIMARY_DOMAIN}}) is for general informational and educational purposes only. <strong>It is not financial, investment, tax, or legal advice.</strong></p>

  <h2>No Personalized Advice</h2>
  <p>Nothing on this website constitutes a recommendation to buy, sell, or hold any security, investment, or other financial product. Content is general in nature and does not consider your specific financial situation, goals, or risk tolerance.</p>

  <h2>Consult Qualified Professionals</h2>
  <p>Before making financial decisions, consult with qualified professionals:</p>
  <ul>
    <li>Certified Financial Planner (CFP) for comprehensive financial planning</li>
    <li>Registered Investment Advisor (RIA) for investment advice</li>
    <li>Certified Public Accountant (CPA) or Enrolled Agent for tax advice</li>
    <li>Licensed insurance agent for insurance decisions</li>
    <li>Estate planning attorney for estate decisions</li>
  </ul>

  <h2>Past Performance Disclaimer</h2>
  <p><strong>Past performance is not indicative of future results.</strong> Investment values fluctuate, and you may lose principal. Historical examples shown for educational purposes do not guarantee similar future outcomes.</p>

  <h2>No Guarantees</h2>
  <p>{{BUSINESS_NAME}} makes no guarantees about the accuracy, completeness, timeliness, or applicability of information presented. Financial regulations, tax laws, and market conditions change frequently. Verify all information with current primary sources or qualified professionals.</p>

  <h2>Affiliate and Advertising Relationships</h2>
  <p>{{BUSINESS_NAME}} may have affiliate or advertising relationships with financial product providers. These relationships are disclosed at the article level. See our <a href="/disclosure/">full disclosures policy</a>. Such relationships do not influence editorial recommendations, but you should consider them when evaluating our content.</p>

  <h2>Securities Regulation Disclosure</h2>
  {{IF_NOT_REGISTERED_INVESTMENT_ADVISOR}}
  <p>{{BUSINESS_NAME}} is not a registered investment advisor under the Investment Advisers Act of 1940 and does not provide personalized investment advice. Information on this site is not tailored to any individual's financial situation.</p>
  {{/IF}}

  {{IF_REGISTERED_INVESTMENT_ADVISOR}}
  <p>{{BUSINESS_NAME}} is a Registered Investment Advisor (CRD #{{CRD_NUMBER}}). However, content on this website is for educational purposes and does not constitute personalized investment advice. Personalized advice is available only through our advisory engagement. <a href="/services/">Learn about our services</a>.</p>
  {{/IF}}

  <h2>Tax Disclaimer</h2>
  <p>Tax information is general and not personalized tax advice. Tax laws are complex and vary by jurisdiction and individual circumstances. Consult a qualified tax professional before making tax-related decisions.</p>

  <h2>No Fiduciary Relationship</h2>
  <p>Reading content on {{BUSINESS_NAME}} does not create a fiduciary or advisory relationship between you and {{BUSINESS_NAME}}.</p>

  <p><time datetime="{{LAST_UPDATED_ISO}}">Last updated: {{LAST_UPDATED_HUMAN}}</time></p>
</article>

5.4.3 Legal disclaimer (/legal-disclaimer/) — for legal YMYL

<article class="legal-disclaimer">
  <h1>Legal Disclaimer</h1>

  <p>The information provided on {{BUSINESS_NAME}} ({{PRIMARY_DOMAIN}}) is for general informational and educational purposes only. <strong>It is not legal advice.</strong></p>

  <h2>No Attorney-Client Relationship</h2>
  <p>Reading content on this website, contacting us through this website, or otherwise interacting with {{BUSINESS_NAME}} does not create an attorney-client relationship between you and {{BUSINESS_NAME}} or any of its authors, reviewers, or affiliates.</p>

  <p>An attorney-client relationship is established only through a signed engagement agreement.</p>

  <h2>Consult a Qualified Attorney</h2>
  <p>Laws vary by jurisdiction and change frequently. The information on this site may not be current or applicable to your specific situation. Always consult a qualified attorney licensed in your jurisdiction before making legal decisions.</p>

  <h2>Confidentiality</h2>
  <p><strong>Communications sent through this website are not confidential.</strong> Do not send confidential or time-sensitive information through this website or via email to addresses listed on this website.</p>

  <h2>No Guarantee of Outcome</h2>
  <p>Discussions of legal cases, statutes, or principles do not predict the outcome of any specific legal matter. Past results do not guarantee similar outcomes in your case.</p>

  <h2>Attorney Advertising</h2>
  {{IF_LAW_FIRM}}
  <p>This website may constitute attorney advertising under applicable rules of professional conduct. {{ATTORNEY_ADVERTISING_DISCLOSURE_BY_STATE}}.</p>
  {{/IF}}

  <h2>Bar Admissions</h2>
  {{IF_LAW_FIRM}}
  <p>{{BUSINESS_NAME}} attorneys are admitted to practice in the following jurisdictions: {{LIST_OF_BAR_ADMISSIONS}}. We do not practice law in jurisdictions where we are not admitted.</p>
  {{/IF}}

  <h2>Currency of Information</h2>
  <p>Laws change. Court decisions are issued daily. Regulations are updated. While we work to keep content current — see our <a href="/editorial-policy/">Editorial Policy</a> — information may not reflect the latest law. Always verify with current primary sources or a qualified attorney.</p>

  <h2>External Links</h2>
  <p>This website may link to external websites. We are not responsible for content on external sites, and inclusion of a link does not constitute endorsement.</p>

  <p><time datetime="{{LAST_UPDATED_ISO}}">Last updated: {{LAST_UPDATED_HUMAN}}</time></p>
</article>

5.5 Phase 5: Per-Article YMYL Trust Elements

Every YMYL article requires these elements in addition to standard E-E-A-T elements.

5.5.1 Top-of-article disclaimer banner

<aside class="ymyl-top-disclaimer" role="note">
  <p>
    <strong>{{TOPIC_DISCLAIMER_HEADLINE}}</strong>
    {{TOPIC_DISCLAIMER_TEXT}}
    <a href="/{{TOPIC}}-disclaimer/">Read our full {{TOPIC}} disclaimer.</a>
  </p>
</aside>

Examples:

For health: "This article is for informational purposes only and is not a substitute for professional medical advice. Always consult a qualified healthcare provider for personal medical decisions."

For finance: "This article is for informational purposes only and is not personalized financial advice. Consult a qualified financial professional before making financial decisions."

For legal: "This article is for informational purposes only and is not legal advice. Consult a qualified attorney for legal decisions specific to your situation."

5.5.2 Author + Reviewer credit block

<header class="article-header ymyl-article">
  <h1>{{TITLE}}</h1>

  <div class="ymyl-byline">
    <div class="author-credit">
      <img src="{{AUTHOR_PHOTO}}" alt="{{AUTHOR_NAME}}" width="48" height="48">
      <p>
        Written by <a href="/authors/{{AUTHOR_SLUG}}/" rel="author">{{AUTHOR_NAME}}</a>
        <br>
        <span class="credentials">{{AUTHOR_CREDENTIALS}}</span>
      </p>
    </div>

    <div class="reviewer-credit">
      <img src="{{REVIEWER_PHOTO}}" alt="{{REVIEWER_NAME}}" width="48" height="48">
      <p>
        {{REVIEWER_TYPE_VERB}} reviewed by <a href="/authors/{{REVIEWER_SLUG}}/">{{REVIEWER_NAME}}</a>
        <br>
        <span class="credentials">{{REVIEWER_CREDENTIALS}}</span>
        {{IF_LICENSED}}
        <br>
        <span class="license-info">License #{{LICENSE_NUMBER}}, {{LICENSE_STATE}} · <a href="{{VERIFY_URL}}" rel="noopener">Verify</a></span>
        {{/IF}}
      </p>
    </div>
  </div>

  <div class="ymyl-dates">
    <p>
      <time datetime="{{PUBLISHED_DATE}}">Published {{PUBLISHED_DATE_HUMAN}}</time>
      ·
      <time datetime="{{UPDATED_DATE}}">Last updated {{UPDATED_DATE_HUMAN}}</time>
      ·
      <time datetime="{{REVIEWED_DATE}}">Last reviewed by {{REVIEWER_TYPE}} {{REVIEWED_DATE_HUMAN}}</time>
    </p>
  </div>
</header>

{{REVIEWER_TYPE_VERB}} examples:

"Medically" (for medical reviewer)
"Legally" (for legal reviewer)
"Financially" (for financial reviewer)

5.5.3 Conflict-of-interest disclosure

When applicable:

<aside class="coi-disclosure" role="note">
  <strong>Conflict of Interest Disclosure:</strong>
  {{COI_DISCLOSURE_TEXT}}
</aside>

Example: "The author owns shares in companies discussed in this article. The reviewer has consulted for one of the firms mentioned. These relationships are disclosed in compliance with our editorial policy and do not influence the analysis presented."

5.5.4 Primary literature citations

YMYL content cites from primary sources only. Format inline citations with prominent links to primary literature:

<p>
  A 2025 systematic review<sup><a href="#ref-1">1</a></sup> found that
  the recommended treatment protocol reduces complications by 47% in patients
  with Type 2 diabetes<sup><a href="#ref-2">2</a></sup>.
</p>

<section class="article-references">
  <h2>References</h2>
  <ol>
    <li id="ref-1">
      Smith J, Doe A, et al. (2025). "Treatment protocols for Type 2 diabetes: A systematic review."
      <em>New England Journal of Medicine</em>, 392(15), 1422-1438.
      <a href="https://pubmed.ncbi.nlm.nih.gov/{{PMID}}/" rel="noopener">PubMed</a>
      ·
      DOI: <a href="https://doi.org/{{DOI}}" rel="noopener">{{DOI}}</a>
    </li>
    <li id="ref-2">
      American Diabetes Association. (2026). "Standards of Medical Care in Diabetes — 2026."
      <em>Diabetes Care</em>, 49(Supplement 1).
      <a href="{{URL}}" rel="noopener">Full text</a>
    </li>
  </ol>
</section>

For finance YMYL, cite SEC filings, IRS publications, FRED data, and Federal Reserve research. For legal YMYL, cite primary case law, statutes, and regulations.

5.5.5 Schema additions for YMYL articles

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "MedicalWebPage",
  "headline": "{{TITLE}}",
  "author": {"@id": "https://{{PRIMARY_DOMAIN}}/authors/{{AUTHOR_SLUG}}/#person"},
  "reviewedBy": {"@id": "https://{{PRIMARY_DOMAIN}}/authors/{{REVIEWER_SLUG}}/#person"},
  "datePublished": "{{PUBLISHED_DATE}}",
  "dateModified": "{{UPDATED_DATE}}",
  "lastReviewed": "{{LAST_REVIEW_DATE}}",
  "publisher": {"@id": "https://{{PRIMARY_DOMAIN}}/#organization"},
  "specialty": {
    "@type": "MedicalSpecialty",
    "name": "{{MEDICAL_SPECIALTY}}"
  },
  "audience": {
    "@type": "MedicalAudience",
    "audienceType": "Patient"
  },
  "citation": {{ARTICLE_CITATIONS_JSON}},
  "isPartOf": {"@id": "https://{{PRIMARY_DOMAIN}}/#website"}
}
</script>

For legal articles, use LegalService or Article with detailed about properties. For financial articles, use Article with mentions of relevant FinancialProduct entities.

5.5.6 Reviewer Person schema (additional fields)

YMYL reviewers need expanded Person schema beyond standard E-E-A-T:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Person",
  "@id": "https://{{PRIMARY_DOMAIN}}/authors/{{REVIEWER_SLUG}}/#person",
  "name": "{{REVIEWER_NAME}}",
  "jobTitle": "{{REVIEWER_TITLE}}",
  "honorificPrefix": "{{HONORIFIC_PREFIX}}",
  "honorificSuffix": "{{HONORIFIC_SUFFIX}}",
  "hasCredential": [
    {
      "@type": "EducationalOccupationalCredential",
      "name": "{{DEGREE_NAME}}",
      "credentialCategory": "degree",
      "recognizedBy": {
        "@type": "EducationalOrganization",
        "name": "{{INSTITUTION}}"
      }
    },
    {
      "@type": "EducationalOccupationalCredential",
      "name": "{{LICENSE_NAME}}",
      "credentialCategory": "license",
      "recognizedBy": {
        "@type": "GovernmentOrganization",
        "name": "{{LICENSING_BODY}}"
      },
      "identifier": "{{LICENSE_NUMBER}}",
      "url": "{{LICENSE_VERIFICATION_URL}}"
    }
  ],
  "memberOf": [
    {
      "@type": "Organization",
      "name": "{{PROFESSIONAL_ORG}}"
    }
  ],
  "knowsAbout": {{REVIEWER_SPECIALTIES_JSON}},
  "sameAs": {{REVIEWER_PROFILES_JSON}}
}
</script>

5.6 Phase 6: Mental Health Crisis Handling

For any health YMYL site that touches mental health topics, install crisis-line resources prominently and consistently.

5.6.1 Mental health crisis banner

Display on every mental-health-related page:

<aside class="crisis-resources" role="note">
  <h2>If You're in Crisis</h2>
  <p>If you're experiencing thoughts of suicide or self-harm:</p>
  <ul>
    <li><strong>988 Suicide & Crisis Lifeline (US):</strong> Call or text <a href="tel:988">988</a></li>
    <li><strong>Crisis Text Line:</strong> Text HOME to <a href="sms:741741">741741</a></li>
    <li><strong>Veterans Crisis Line:</strong> Call <a href="tel:988">988</a> and press 1</li>
    <li><strong>International:</strong> <a href="https://www.iasp.info/resources/Crisis_Centres/" rel="noopener">Find a crisis center near you</a></li>
  </ul>
  <p>If you are in immediate danger, call <a href="tel:911">911</a> or go to your nearest emergency room.</p>
</aside>

This banner appears at the top of mental health articles, not the bottom.

5.7 Phase 7: Regulatory Compliance Per Industry

5.7.1 Healthcare (HIPAA-applicable entities)

If hipaa_applicable: true:

HIPAA Privacy Notice page
Notice of privacy practices
Patient rights enumeration
Breach notification procedure
Business associate agreement template (for vendors)
All forms collecting PHI use HTTPS with proper encryption
Cookie consent calibrated for HIPAA-compliant analytics

5.7.2 Financial Services

If sec_registered: true:

Form ADV linked from footer
Brochure (Form ADV Part 2A) downloadable
Code of ethics
Customer relationship summary (Form CRS) for retail clients
Cybersecurity disclosures per SEC rules

If finra_member: true:

BrokerCheck links per representative
Investor education resources
Required disclosures per FINRA Rule 2210 (advertising)

5.7.3 Legal Services

State-by-state attorney advertising compliance:

"Attorney advertising" or equivalent label per state requirements
Disclaimer language varies by jurisdiction (NY, FL, TX, CA each have different requirements)
Past results disclaimer
Bar association required language
Specialization claim restrictions per state

5.8 Phase 8: AI Content in YMYL — Higher Bar

The standard AI content disclosure (E-E-A-T Section 4.4.6) is insufficient for YMYL. Additional protocols apply:

5.8.1 Per-article YMYL AI disclosure

<aside class="ymyl-ai-disclosure" role="note">
  <h3>How This Article Was Created</h3>
  <ul>
    <li>{{AI_USAGE_LEVEL}} — {{AI_USAGE_DESCRIPTION}}</li>
    <li>Reviewed for accuracy by {{REVIEWER_NAME}}, {{REVIEWER_CREDENTIALS}}</li>
    <li>All factual claims verified against primary sources cited in the references section</li>
    <li>{{REVIEW_DATE_AND_TIME_INVESTED}}</li>
  </ul>
  <p>See our <a href="/disclosure/">AI use policy</a> and <a href="/editorial-policy/">editorial policy</a> for details on our YMYL content standards.</p>
</aside>

5.8.2 What's never acceptable in YMYL

AI-generated content published without expert review
AI-generated medical advice, diagnoses, or treatment recommendations
AI-generated legal analysis presented as authoritative
AI-generated financial recommendations
AI-generated case studies or statistics that aren't real
AI-fabricated citations (always verify every citation independently)

If an AI tool produces content for YMYL purposes, treat the AI output as a research draft. The credentialed reviewer must verify every fact, every citation, every recommendation. The reviewer's name and credentials go on the article — taking professional responsibility for the content.

5.9 Phase 9: Refresh Cadence Calendar

YMYL content requires more frequent refreshing than non-YMYL.

YMYL Category	Refresh Cadence
Drug information, dosing, interactions	Monthly
Medical condition treatment guidelines	Quarterly
Tax deadlines and rates	Annually + on regulatory change
Investment product reviews	Quarterly
Legal procedure guides	Quarterly + on case law change
Insurance regulation guides	Annually + on regulatory change
News-sensitive YMYL (elections, public health)	Daily during active periods
Evergreen YMYL (anatomy, basic legal concepts)	Annually

Build a refresh calendar at /admin/ymyl-refresh-calendar/ listing every YMYL article with next-review-due date.

6. Per-Page YMYL Validation

Every YMYL page must pass:

#	Criterion	Severity
Y1	Top-of-article topic-specific disclaimer banner present	Critical
Y2	Credentialed author byline	Critical
Y3	Credentialed reviewer byline (with verifiable license where applicable)	Critical
Y4	Last-published, last-updated, last-reviewed dates all displayed	Critical
Y5	Conflict-of-interest disclosure if applicable	Critical
Y6	Primary literature citations for every factual claim	Critical
Y7	References section with full source citations	High
Y8	Topic-specific schema (MedicalWebPage for health, etc.)	High
Y9	Reviewer Person schema with `hasCredential` including license	Critical
Y10	Crisis resources displayed if mental health topic	Critical (mental health)
Y11	AI use disclosed if AI was involved in creation	Critical (if applicable)
Y12	Article reviewed within required cadence (not stale)	High

Score: 24 max. World-class YMYL article: 22+/24 with zero Critical fails.

7. Site-Wide YMYL Audit Criteria

Beyond per-article criteria, the site as a whole must satisfy:

#	Criterion	Severity
YS1	Editorial policy page exists at `/editorial-policy/`	Critical
YS2	Corrections policy page exists at `/corrections-policy/`	Critical
YS3	Corrections log maintained at `/corrections-log/`	High
YS4	Topic-specific disclaimer pages exist (medical, financial, legal as applicable)	Critical
YS5	Author hub page lists credentialed authors with verifiable licenses	Critical
YS6	YMYL inventory and classification documented internally	High
YS7	Refresh calendar maintained with next-review dates	High
YS8	Industry-specific compliance documentation in place (HIPAA, SEC, bar advertising)	Critical (if applicable)
YS9	Cookie consent calibrated for industry compliance	Critical (if HIPAA/finance)
YS10	Crisis resources prominent on mental health pages sitewide	Critical (mental health)
YS11	AI use policy explicitly addresses YMYL content standards	High
YS12	Quarterly internal YMYL audit conducted and documented	Medium

Score: 24 max. World-class YMYL site: 22+/24 with zero Critical fails.

8. Common YMYL Mistakes & Anti-Patterns

8.1 "Educational" Content That Functions as Advice

Anti-pattern: Articles framed as "educational" but written to direct readers toward specific decisions ("This medication is best for...", "You should invest in..."). The educational framing is a fig leaf for advice.

Why it fails: Google's raters see through this. Regulatory bodies see through this. Readers harmed by following the implicit advice have legal recourse.

Fix: Either commit to advice (with credentialed authorship and proper disclosures) or commit to education (with clearer language that isn't directive).

8.2 Generic Reviewer Stamping

Anti-pattern: A single "medical reviewer" listed on hundreds of articles without evidence they actually reviewed each one.

Why it fails: When detected (typically through inconsistencies in claims across articles), it collapses Trust across the entire site.

Fix: Reviewer process must be real. Track which articles each reviewer has actually reviewed. Maintain audit trail.

8.3 Outdated YMYL Content Treated as Current

Anti-pattern: Article published 2021 about "current tax law" still ranking and not refreshed.

Why it fails: Stale YMYL content harms users and tanks rankings post-core-update.

Fix: Aggressive refresh cadence. Retire content that can't be maintained.

8.4 Hidden Affiliate Conflicts in YMYL

Anti-pattern: A health site recommends a supplement; affiliate disclosure exists in footer but not on the article.

Why it fails: FTC requires "clear and conspicuous" disclosure. For YMYL especially, the conflict is material.

Fix: Top-of-article disclosure for any YMYL article with affiliate links.

8.5 Personal Anecdote Presented as Universal Advice

Anti-pattern: "How I cured my anxiety with this technique" framed as a solution that will work for readers.

Why it fails: Mental health is highly individual. Generalizing personal experience creates harm.

Fix: Frame personal experience as personal. Add disclaimers explicitly stating the experience may not apply to others.

8.6 AI-Generated YMYL Without Real Review

Anti-pattern: ChatGPT writes an article on medication side effects. A non-credentialed editor "reviews" it. Published as authoritative.

Why it fails: AI hallucinations in YMYL content can directly harm readers. Lack of credentialed review is a Trust violation. Detection rate is rising.

Fix: Either don't use AI for YMYL drafting, or have a credentialed expert genuinely verify every fact and citation.

8.7 Boilerplate Disclaimers That Don't Match Content

Anti-pattern: Generic "consult a professional" disclaimer at the bottom of an article that explicitly tells readers what to do.

Why it fails: Disclaimers don't immunize against directive content. Plus: regulators don't accept boilerplate disclaimers as protection.

Fix: Match disclaimer to content. If you're giving advice, the disclaimer should reflect that. If you're educating, the content should be educational.

8.8 Misleading Credential Claims

Anti-pattern: Author bio claims "20 years of experience" without specifying in what. Or lists credentials abbreviations that look impressive but aren't actually relevant (e.g., a non-medical "PhD" reviewing health content).

Why it fails: Misleading credentials are a Trust violation when discovered. Plus: in regulated industries (medicine, law, finance), can be illegal.

Fix: Specific, verifiable credentials. Plain-language explanation of why this person's credentials are relevant to the topic.

8.9 Fabricated Citations

Anti-pattern: Article cites a study that doesn't exist or misrepresents what the study found. Often happens with AI-generated content.

Why it fails: Easily verified. Catastrophic Trust violation when discovered.

Fix: Verify every citation independently before publishing. Click every link. Read the actual source.

8.10 Cross-Border YMYL Without Jurisdictional Awareness

Anti-pattern: US-focused legal content viewed by readers in other countries who follow guidance that doesn't apply.

Why it fails: Harm to international readers. Reflects on the site's quality.

Fix: Clear jurisdictional scope statements. International readers redirected to country-appropriate resources where possible.

9. Stack-Specific YMYL Implementation Notes

YMYL content can be created and managed in any stack, but these patterns help:

9.1 WordPress

Plugin: Use a custom plugin or ACF (Advanced Custom Fields) to add YMYL-specific fields per article: reviewer, license number, last review date, conflict disclosures
Template: Build dedicated ymyl-article.php template that renders required disclaimer + reviewer block + citation requirements
Workflow: Use Editorial Calendar or PublishPress to enforce reviewer assignment before publish

9.2 Next.js

Content schema: Define TypeScript types for YMYL article frontmatter requiring reviewer, license, citations array
Validation: Pre-publish CI/CD step validates required YMYL fields are present
Component: <YmylArticleHeader /> component encapsulates disclaimer + author/reviewer credit + dates

9.3 Astro / Hugo / Static Sites

Content collections: Define YMYL article schema with required fields
Build-time validation: Reject builds where YMYL articles are missing required fields
Layout: Dedicated YMYL article layout enforces structural requirements

9.4 Universal Pattern

Regardless of stack, the YMYL workflow looks like:

Author drafts article with YMYL classification metadata
Drafted content goes to credentialed reviewer
Reviewer adds review notes and signs off (with date)
Editorial layer fact-checks against primary sources
Publication system requires all YMYL fields present before publishing
Article appears with full YMYL trust elements
Refresh calendar tracks next-review-due date
Quarterly audit verifies compliance across all YMYL content

10. Cross-Reference to the 14-Tier Framework

YMYL implementation touches multiple tiers:

Tier 1 SSO: Security required for HIPAA-compliant health sites
Tier 1 GCO: GDPR/CCPA compliance overlaps with health/finance privacy requirements
Tier 2 ETO: Per-article trust signals (disclaimer banner, reviewer credit)
Tier 2 AAO: Author authority — extended for credentialed YMYL authors
Tier 4 PBO: Personal brand for credentialed reviewers
Tier 4 REO: Reviews carry more weight in YMYL niches
Tier 6 RSO: Research and original studies — primary literature citations
Tier 8 GA4: Compliance-aware analytics for YMYL sites

When YMYL improvement is the priority for a site, implement in this order:

Classify content (Section 5.1)
Build editorial and corrections policy pages (Sections 5.2-5.3)
Build topic-specific disclaimer pages (Section 5.4)
Recruit credentialed reviewers if not already in place
Per-article YMYL elements (Section 5.5)
Industry compliance documentation (Section 5.7)
Refresh calendar (Section 5.9)
Mental health crisis resources if applicable (Section 5.6)

11. Validation Protocol

11.1 Automated Validation

# Verify all YMYL articles have required schema
for url in $YMYL_URLS; do
  curl -sL "$url" | python -c "
import sys, re, json
html = sys.stdin.read()
matches = re.findall(r'<script type=\"application/ld\+json\">(.*?)</script>', html, re.DOTALL)
has_reviewer = False
for m in matches:
    try:
        data = json.loads(m)
        if 'reviewedBy' in data:
            has_reviewer = True
    except:
        pass
if not has_reviewer:
    print(f'{url}: MISSING reviewedBy')
    sys.exit(1)
"
done

# Verify all YMYL articles have disclaimer
for url in $YMYL_URLS; do
  if ! curl -sL "$url" | grep -q 'class="ymyl-top-disclaimer"'; then
    echo "FAIL: $url missing disclaimer"
  fi
done

# Verify required pages
REQUIRED=(/editorial-policy/ /corrections-policy/ /corrections-log/)
for page in "${REQUIRED[@]}"; do
  status=$(curl -o /dev/null -s -w "%{http_code}" "https://$DOMAIN$page")
  [ "$status" != "200" ] && echo "FAIL: $page returned $status"
done

11.2 Manual Validation

Sample 10% of YMYL articles. Verify each has all elements from Section 6.
Verify reviewer credentials by checking license verification URLs.
Spot-check citations — click every link in the references section of sampled articles. Verify the source actually exists and supports the claim.
Test mental health crisis resources are visible and links work.
Verify AI disclosure if AI is used in any YMYL content.

11.3 Regulatory Validation

HIPAA covered entities: have HIPAA officer review the site annually
SEC-registered firms: have compliance officer review marketing content quarterly
Law firms: have managing partner review attorney advertising compliance per state
Financial advisors: have compliance officer review per FINRA Rule 2210

12. Audit Mode

Use Section 4.1 to classify each piece of content. Then score against:

Per-article criteria (Section 6) — 24 points max per article. Average across all YMYL articles.
Site-wide criteria (Section 7) — 24 points max.

Total: 48 points max for YMYL audit.

Score	Status
44-48	World-class YMYL compliance
38-43	Compliant with minor gaps
30-37	Significant gaps requiring remediation
<30	Critical YMYL failures — immediate action required

A site cannot be considered YMYL-compliant if any Critical-severity item fails, regardless of total score.

13. Maintenance Schedule

13.1 Daily

Monitor mental health crisis page accuracy if applicable
Respond to corrections requests within 2 business days

13.2 Weekly

Review one piece of YMYL content from refresh queue
Check for new citations to add (new studies, regulatory updates)

13.3 Monthly

Generate YMYL compliance status report
Update corrections log with any material corrections
Run automated YMYL validation across all flagged content
Refresh time-sensitive content (drug info, tax dates, etc.)

13.4 Quarterly

Full YMYL audit of randomly sampled 10% of YMYL content
Reviewer credential verification (license still active, not suspended)
Editorial policy review
Industry compliance audit (HIPAA, SEC, bar advertising)
Update refresh calendar with new content

13.5 Annually

Comprehensive site-wide YMYL audit
Editorial policy substantive review
Disclaimer language legal review
AI use policy review
Reviewer team review (any changes, additions, departures)
Strategic decision: are we still publishing YMYL content responsibly?

13.6 On Regulatory Change

New SEC/FINRA rule → financial content review within 30 days
New tax law → tax content review immediately
New medical guidelines (ADA standards, ACOG guidelines, etc.) → relevant content review within 60 days
Court decisions affecting legal content → review within 90 days

14. Implementation/Audit Report Templates

14.1 YMYL Implementation Report Template

# YMYL Framework Implementation Report

**Project**: {{BUSINESS_NAME}}
**Domain**: {{PRIMARY_DOMAIN}}
**Implementation Date**: {{TODAY}}
**YMYL Classification**: {{CLASSIFICATION}}
**YMYL Categories**: {{CATEGORIES}}

## Summary
- **Total YMYL articles**: {{COUNT}}
- **Articles with full YMYL trust elements**: {{COUNT}}
- **Critical items remediated**: {{COUNT}}
- **Reviewer team established**: {{REVIEWER_LIST}}

## Required Pages Created
- /editorial-policy/ — {{STATUS}}
- /corrections-policy/ — {{STATUS}}
- /corrections-log/ — {{STATUS}}
- /medical-disclaimer/ — {{STATUS}}
- /financial-disclaimer/ — {{STATUS}}
- /legal-disclaimer/ — {{STATUS}}

## Per-Article Trust Elements Installed
{{TABLE_OF_ARTICLES_WITH_INSTALLED_ELEMENTS}}

## Industry Compliance Documentation
{{LIST_OF_COMPLIANCE_DOCS}}

## Items Flagged for Manual Review
{{LIST_WITH_REASONS}}

## Refresh Calendar Established
- Articles requiring monthly refresh: {{COUNT}}
- Articles requiring quarterly refresh: {{COUNT}}
- Articles requiring annual refresh: {{COUNT}}

## Validation Results
{{AUTOMATED_AND_MANUAL_RESULTS}}

## Sign-Off
Implementation complete: {{DATE}}
Implementer: {{NAME}}
Editorial Lead: {{NAME}}
Compliance Lead: {{NAME}}

14.2 YMYL Audit Report Template

# YMYL Framework Audit Report

**Site**: {{BUSINESS_NAME}}
**Audit Date**: {{TODAY}}
**YMYL Classification**: {{CLASSIFICATION}}

## Executive Summary
{{SUMMARY}}

**Overall Score**: {{X}}/48 ({{PERCENTAGE}}%)
**Status**: {{STATUS}}

## YMYL Inventory
- Total content: {{COUNT}}
- YMYL content (full): {{COUNT}}
- YMYL content (partial): {{COUNT}}
- YMYL content (lite): {{COUNT}}
- Non-YMYL content: {{COUNT}}

## Per-Article Compliance ({{X}}/24 average)
{{DETAILED_PER_ARTICLE_FINDINGS}}

## Site-Wide Compliance ({{X}}/24)
{{DETAILED_SITE_FINDINGS}}

## Critical Failures
{{LIST_WITH_REMEDIATION}}

## High-Severity Issues
{{LIST_WITH_REMEDIATION}}

## Industry-Specific Findings
{{HIPAA_SEC_BAR_FINDINGS}}

## Recommended Remediation Order
{{PRIORITIZED_LIST}}

## Sign-Off
Audit complete: {{DATE}}
Auditor: {{NAME}}

End of Framework Document

Document version: 1.0
Last updated: 2026-04-29
Maintained by: ThatDeveloperGuy

YMYL is the highest-stakes framework in the foundational library. Errors in YMYL content can harm users, expose the business to legal and regulatory consequences, and tank rankings. The standards in this document are non-negotiable. When in doubt, err toward more rigor — extra disclaimers, more credentialed reviewers, more frequent refresh, more conservative claims.

Companion documents in this library:

framework-eeat.md — Foundational E-E-A-T (YMYL applies elevated E-E-A-T standards)
framework-hcs.md — Helpful Content System
framework-sqrg.md — Search Quality Rater Guidelines
framework-coreupdates.md — Core Updates
framework-infogain.md — Information Gain
framework-entitysalience.md — Entity Salience
framework-knowledgegraph.md — Knowledge Graph
framework-aicitations.md — AI Citation Theory

About this framework library

This article is the Dev.to republish of a framework reference document from ThatDevPro's SEO + AI engineering library. Canonical source: https://www.thatdevpro.com/insights/framework-ymyl/

Companion 14-tier Engine Optimization stack (each tier is its own article):

Need this framework implemented on your site? See the Engine Optimization service or hire through ThatDevPro contact.

Schema.org + JSON-LD: the complete pattern reference

Joseph Anady — Sun, 24 May 2026 01:03:44 +0000

Originally published at thatdevpro.com. Part of ThatDevPro's open SEO + AI framework library. ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.

JSON-LD Implementation, the @id Graph Pattern, Per-Page Type Selection, and Validation

A comprehensive installation and audit reference for structured data — the machine-readable layer that tells Google, AI crawlers, and other consumers what entities a page is about and how they relate. Every meaningful SERP feature, AI citation, and Knowledge Panel claim depends on this layer being correct. Dual-purpose: installation manual and audit document.

Cross-stack implementation note: the code samples in this framework are written in plain HTML for clarity. For React, Vue, Svelte, Next.js, Nuxt, SvelteKit, Astro, Hugo, 11ty, Remix, WordPress, Shopify, and Webflow equivalents of every pattern below, see framework-cross-stack-implementation.md. For pure client-rendered SPAs (no SSR/SSG) see framework-react.md. For Tailwind-specific concerns (purge, dynamic classes, dark-mode CLS, focus accessibility) see framework-tailwind.md.

1. Document Purpose

This is the canonical reference for schema.org structured data implementation. Schema is no longer optional in 2026 — it is the foundation that lets Google's Knowledge Graph populate, AI search engines extract claims, and SERP rich results render. A site without proper structured data is invisible to half of modern search.

Schema in 2026 differs from schema in 2020 in three critical ways. First, the @id graph pattern (cross-referenced nodes within a single @graph block) has overtaken the older "one schema block per page" approach because it lets entities reference each other across the site. Second, AI search engines (ChatGPT, Perplexity, Claude, Gemini) rely on schema as a primary signal for entity extraction — accurate schema increases citation likelihood. Third, validation is non-negotiable: invalid schema is worse than no schema, because Google penalizes spam markup.

1.1 Required Tools

Google Rich Results Test — search.google.com/test/rich-results — primary validator
Schema.org Validator — validator.schema.org — comprehensive validator (accepts more types than Google's tool)
Google Search Console — Enhancements section — sitewide schema health monitoring
Yandex Microdata Validator — webmaster.yandex.com/tools/microtest/
JSON-LD Playground — json-ld.org/playground/ — for graph experimentation
Schema App / Schema Pro — paid tooling for non-developer environments
Yoast SEO / Rank Math — WordPress plugins with schema generators
Browser DevTools — Application > Frames > Structured Data
curl + jq — extract and inspect JSON-LD from a URL programmatically

1.2 Document Scope

Covers: schema formats, @id graph pattern, the major schema types every site needs, type-specific implementation per content type, validation methodology, sameAs networks, and common pitfalls. Touches but does not exhaust: Knowledge Graph claiming (own framework: framework-knowledgegraph.md), AI citation mechanics (framework-aicitations.md), Local SEO schema (framework-localseo.md).

2. Client Variables Intake

business_type: ""                      # local | ecommerce | publisher | b2b_service | sdvosb
primary_entity: ""                     # Organization name
person_entity: ""                      # Founder/author Person if relevant
website_domain: ""
local_business_subtype: ""             # Restaurant | Plumber | Dentist | etc. — only if local
ecommerce_product_count: 0
existing_schema_present: false
existing_schema_format: ""             # JSON-LD | Microdata | RDFa
existing_schema_validated: false
wikidata_qid_org: ""                   # if claimed
wikidata_qid_person: ""                # if claimed
sameas_targets: []                     # LinkedIn, GitHub, Wikidata, Wikipedia, etc.
known_schema_errors: []

3. Schema Format Decision

Three formats are valid. Pick one and stick with it.

Format	Recommendation	Why
JSON-LD	Use this.	Decoupled from rendered HTML; survives template changes; preferred by Google; trivial to maintain.
Microdata	Avoid for new builds	Inline HTML attributes; brittle; tied to template structure.
RDFa	Avoid for new builds	Similar drawbacks to Microdata; less common.

JSON-LD lives in a <script type="application/ld+json"> block in the document head (or anywhere in the body — head is conventional). It does not need to mirror the visible HTML.

4. The @id Graph Pattern

This is the single most important pattern in modern schema implementation. Older sites declared one schema block per type per page, with no cross-references. The graph pattern declares all entities in one @graph block with cross-referenced @id URIs, letting Google reconstruct the entity relationships.

4.1 Anatomy of a Graph

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": ["Organization", "ProfessionalService", "LocalBusiness"],
      "@id": "https://example.com/#organization",
      "name": "Example Co",
      "url": "https://example.com/",
      "sameAs": [
        "https://www.wikidata.org/wiki/Q12345",
        "https://www.linkedin.com/company/example",
        "https://github.com/example"
      ],
      "founder": { "@id": "https://example.com/#founder" }
    },
    {
      "@type": "Person",
      "@id": "https://example.com/#founder",
      "name": "Joseph W. Anady",
      "sameAs": [
        "https://www.wikidata.org/wiki/Q139592630",
        "https://www.linkedin.com/in/josephanady"
      ],
      "worksFor": { "@id": "https://example.com/#organization" },
      "knowsAbout": ["Technical SEO", "AI search optimization"]
    },
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "url": "https://example.com/",
      "name": "Example Co",
      "publisher": { "@id": "https://example.com/#organization" }
    },
    {
      "@type": "WebPage",
      "@id": "https://example.com/about/#webpage",
      "url": "https://example.com/about/",
      "name": "About — Example Co",
      "isPartOf": { "@id": "https://example.com/#website" },
      "about": { "@id": "https://example.com/#organization" }
    }
  ]
}
</script>

4.2 The @id Convention

@id values are URIs. Use absolute URLs with a fragment identifier (#) to disambiguate entities on the same page:

https://example.com/#organization — the Organization entity
https://example.com/#website — the WebSite entity
https://example.com/#founder — the Person entity
https://example.com/about/#webpage — the About page WebPage entity
https://example.com/blog/post-name/#article — an Article entity

The @id does NOT need to resolve to a real URL. It is just a unique identifier within the graph.

4.3 Cross-Page Consistency

Every page on the site declares the same Organization, WebSite, and Person entities (with the same @id URIs). Page-specific entities (WebPage, Article, Service, Product) reference back via @id:

{
  "@type": "Article",
  "@id": "https://example.com/blog/post/#article",
  "headline": "Post Title",
  "author": { "@id": "https://example.com/#founder" },
  "publisher": { "@id": "https://example.com/#organization" },
  "isPartOf": { "@id": "https://example.com/blog/post/#webpage" }
}

This cross-referencing is what gives Google's Knowledge Graph the connectivity it needs to attribute Articles to Authors, Authors to Organizations, and Organizations to Knowledge Panel entries.

5. The Foundation Schemas

Every meaningful site needs these. Implement them sitewide before any page-specific schema.

5.1 Organization

Required for every site. If the business has a physical location, extend with LocalBusiness; if it serves a profession, extend with ProfessionalService.

{
  "@type": ["Organization", "ProfessionalService", "LocalBusiness"],
  "@id": "https://example.com/#organization",
  "name": "Example Co",
  "alternateName": ["example.com", "Example"],
  "url": "https://example.com/",
  "logo": {
    "@type": "ImageObject",
    "url": "https://example.com/logo.png",
    "width": 600,
    "height": 600
  },
  "image": "https://example.com/og-default.png",
  "description": "Plain-English description matching the site's actual purpose.",
  "telephone": "+1-505-512-3662",
  "email": "hello@example.com",
  "priceRange": "$597-$11997",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main St",
    "addressLocality": "Cassville",
    "addressRegion": "MO",
    "postalCode": "65625",
    "addressCountry": "US"
  },
  "geo": {
    "@type": "GeoCoordinates",
    "latitude": 36.6811,
    "longitude": -93.8702
  },
  "areaServed": [
    { "@type": "AdministrativeArea", "name": "Northwest Arkansas" },
    { "@type": "AdministrativeArea", "name": "Southwest Missouri" }
  ],
  "founder": { "@id": "https://example.com/#founder" },
  "foundingDate": "2017-01-01",
  "sameAs": [
    "https://www.wikidata.org/wiki/Q139592631",
    "https://www.linkedin.com/company/example",
    "https://github.com/example"
  ]
}

5.2 Person

For owner-operated businesses, sole-proprietor agencies, and any site with named editorial authors. Critical for E-E-A-T.

{
  "@type": "Person",
  "@id": "https://example.com/#founder",
  "name": "Joseph W. Anady",
  "givenName": "Joseph",
  "additionalName": "W.",
  "familyName": "Anady",
  "jobTitle": "Founder",
  "worksFor": { "@id": "https://example.com/#organization" },
  "image": "https://example.com/joseph.jpg",
  "url": "https://example.com/about/",
  "knowsAbout": [
    "Technical SEO", "Local SEO", "AI search optimization",
    "Schema markup", "SDVOSB digital marketing"
  ],
  "knowsLanguage": ["English"],
  "alumniOf": "U.S. Army",
  "sameAs": [
    "https://www.wikidata.org/wiki/Q139592630",
    "https://www.linkedin.com/in/josephanady",
    "https://github.com/josephanady"
  ]
}

Cross-reference: framework-eeat.md for Person schema's role in expertise signals; framework-knowledgegraph.md for sameAs network construction.

5.3 WebSite

Declares the site itself as an entity. Enables sitelinks search box.

{
  "@type": "WebSite",
  "@id": "https://example.com/#website",
  "url": "https://example.com/",
  "name": "Example Co",
  "publisher": { "@id": "https://example.com/#organization" },
  "inLanguage": "en-US",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://example.com/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}

5.4 WebPage (per-page)

Every page declares itself as a WebPage. Subtypes when applicable: AboutPage, ContactPage, FAQPage, CollectionPage.

{
  "@type": "WebPage",
  "@id": "https://example.com/about/#webpage",
  "url": "https://example.com/about/",
  "name": "About — Example Co",
  "description": "About page meta description.",
  "isPartOf": { "@id": "https://example.com/#website" },
  "about": { "@id": "https://example.com/#organization" },
  "primaryImageOfPage": {
    "@type": "ImageObject",
    "url": "https://example.com/about-hero.jpg"
  },
  "datePublished": "2026-01-15",
  "dateModified": "2026-05-05",
  "breadcrumb": { "@id": "https://example.com/about/#breadcrumb" }
}

5.5 BreadcrumbList

For every non-homepage. Drives breadcrumb display in SERPs.

{
  "@type": "BreadcrumbList",
  "@id": "https://example.com/about/#breadcrumb",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://example.com/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "About",
      "item": "https://example.com/about/"
    }
  ]
}

6. Per-Content-Type Schemas

6.1 Article (blog post, news story, editorial)

Use Article, NewsArticle, BlogPosting, or TechArticle depending on content. Article is the safe default.

{
  "@type": "Article",
  "@id": "https://example.com/blog/post-slug/#article",
  "headline": "Post headline (under 110 characters)",
  "description": "Meta description.",
  "image": [
    "https://example.com/post-image-1x1.jpg",
    "https://example.com/post-image-4x3.jpg",
    "https://example.com/post-image-16x9.jpg"
  ],
  "author": { "@id": "https://example.com/#founder" },
  "publisher": { "@id": "https://example.com/#organization" },
  "datePublished": "2026-04-15T10:00:00-05:00",
  "dateModified": "2026-05-05T14:30:00-05:00",
  "mainEntityOfPage": { "@id": "https://example.com/blog/post-slug/#webpage" },
  "wordCount": 2500,
  "articleBody": "First 200 characters of body, optional but improves AI extraction.",
  "keywords": ["technical seo", "schema", "json-ld"]
}

Image best practice: provide three images at three aspect ratios (1x1, 4x3, 16x9). Google selects the best fit per surface.

6.2 Service

For service-based businesses describing what they offer.

{
  "@type": "Service",
  "@id": "https://example.com/services/local-seo/#service",
  "name": "Local SEO for Northwest Arkansas",
  "description": "Description of the service offered.",
  "provider": { "@id": "https://example.com/#organization" },
  "serviceType": "Local SEO",
  "areaServed": [
    { "@type": "AdministrativeArea", "name": "Northwest Arkansas" }
  ],
  "hasOfferCatalog": {
    "@type": "OfferCatalog",
    "name": "Local SEO Services",
    "itemListElement": [
      {
        "@type": "Offer",
        "itemOffered": {
          "@type": "Service",
          "name": "Google Business Profile setup"
        },
        "price": "597",
        "priceCurrency": "USD"
      }
    ]
  }
}

6.3 Product (ecommerce)

Cross-reference: framework-ecommerceseo.md for full product schema depth.

{
  "@type": "Product",
  "@id": "https://example.com/products/sku-123/#product",
  "name": "Product Name",
  "description": "Product description.",
  "image": ["https://example.com/product.jpg"],
  "sku": "SKU-123",
  "gtin13": "1234567890123",
  "brand": { "@type": "Brand", "name": "Brand Name" },
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/products/sku-123/",
    "priceCurrency": "USD",
    "price": "29.99",
    "priceValidUntil": "2026-12-31",
    "availability": "https://schema.org/InStock",
    "itemCondition": "https://schema.org/NewCondition",
    "shippingDetails": { "@type": "OfferShippingDetails" },
    "hasMerchantReturnPolicy": { "@type": "MerchantReturnPolicy" }
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.8",
    "reviewCount": "127"
  }
}

aggregateRating is only valid if you actually have those reviews on-site. Fabricating reviews is a manual-action violation. Cross-reference: framework-spampolicies.md.

6.4 LocalBusiness (with subtype)

For local businesses, use the most specific subtype available. Schema.org has hundreds: Restaurant, Plumber, Dentist, HVACBusiness, RealEstateAgent, LegalService, MedicalBusiness, HomeAndConstructionBusiness, etc.

{
  "@type": ["LocalBusiness", "Plumber"],
  "@id": "https://example.com/#organization",
  "name": "Example Plumbing",
  "telephone": "+1-555-555-5555",
  "address": { "@type": "PostalAddress", "..." : "..." },
  "openingHoursSpecification": [
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
      "opens": "08:00",
      "closes": "17:00"
    }
  ],
  "priceRange": "$$"
}

Cross-reference: framework-localseo.md for full LocalBusiness depth.

6.5 FAQPage

Only when the page actually answers questions. Misuse triggers manual actions.

{
  "@type": "FAQPage",
  "@id": "https://example.com/faq/#faqpage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "How long does local SEO take to show results?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Most clients see Local Pack improvements within 30-60 days..."
      }
    }
  ]
}

FAQ rich results were largely deprecated by Google in 2023 for non-government / non-health sites, but the schema still feeds AI extraction. Keep using it where it accurately describes the page; do not expect rich results.

6.6 HowTo

For genuine step-by-step instructions. Like FAQ, rich results were curtailed in 2023 but the schema remains useful for AI extraction.

{
  "@type": "HowTo",
  "name": "How to claim a Google Business Profile",
  "step": [
    {
      "@type": "HowToStep",
      "name": "Sign in to Google Business Profile",
      "text": "Visit business.google.com and sign in..."
    }
  ]
}

6.7 Event

For dated events.

{
  "@type": "Event",
  "name": "Workshop on Local SEO",
  "startDate": "2026-06-15T18:00:00-05:00",
  "endDate": "2026-06-15T20:00:00-05:00",
  "location": {
    "@type": "Place",
    "name": "Cassville Chamber",
    "address": { "@type": "PostalAddress", "..." : "..." }
  },
  "organizer": { "@id": "https://example.com/#organization" },
  "eventStatus": "https://schema.org/EventScheduled",
  "eventAttendanceMode": "https://schema.org/OfflineEventAttendanceMode"
}

6.8 Review (single review)

When a page is genuinely a single review of one product/service.

{
  "@type": "Review",
  "itemReviewed": { "@type": "Product", "name": "Product Name" },
  "author": { "@id": "https://example.com/#founder" },
  "reviewRating": {
    "@type": "Rating",
    "ratingValue": "4.5",
    "bestRating": "5"
  },
  "datePublished": "2026-04-01"
}

6.9 VideoObject

For pages embedding or hosting video. Required for video sitemap inclusion.

{
  "@type": "VideoObject",
  "name": "Video Title",
  "description": "Video description.",
  "thumbnailUrl": ["https://example.com/thumb.jpg"],
  "uploadDate": "2026-04-01T08:00:00-05:00",
  "duration": "PT5M30S",
  "contentUrl": "https://example.com/video.mp4",
  "embedUrl": "https://www.youtube.com/embed/abc123"
}

Cross-reference: framework-videoseo.md for full video implementation.

6.10 Other Useful Types

Course — for educational content
Recipe — for food sites
JobPosting — for hiring pages
RealEstateListing — for property listings
MedicalCondition / Drug — for YMYL medical content (high standard required)
SoftwareApplication — for tools/apps
DataCatalog / Dataset — for structured data publishers
ItemList — for lists of any kind

7. The sameAs Network

sameAs declares external canonical identifiers for an entity. This is how Google's Knowledge Graph builds entity confidence.

7.1 sameAs Hierarchy of Trust

Source	Weight	Notes
Wikidata	Highest	Entity ID format: `https://www.wikidata.org/wiki/Q12345`
Wikipedia	Very high	Article URL
Crunchbase (orgs)	High	Verified company entries
LinkedIn (orgs and persons)	High	Verified accounts
GitHub (devs/orgs)	High when relevant
Twitter/X	Medium	Verified accounts only
Facebook	Medium	Page (not personal)
Instagram	Medium	Business profiles
YouTube	Medium	Channel URL
Personal website	Low (when used as sameAs from another entity)
Random social network	Low	Avoid noise

Cross-reference: framework-knowledgegraph.md for Wikidata claiming methodology.

7.2 sameAs Hygiene

Only declare sameAs for entities you actually own and control.
Verify each sameAs target resolves and represents the same entity.
Do not include URL shorteners or redirects in sameAs.
Update sameAs when external profiles move.
Both directions matter: the external profile should also link back to the canonical site.

8. Schema Implementation Patterns

8.1 The Sitewide Block

Every page on the site emits the same Organization, WebSite, and Person entities. Implement once in your template head:

<!-- Sitewide schema graph (every page) -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    { /* Organization */ },
    { /* Person */ },
    { /* WebSite */ }
  ]
}
</script>

8.2 The Page-Specific Block

Each page adds its specific entities (WebPage, Article, BreadcrumbList, etc.) referencing the sitewide entities via @id. Two valid patterns:

Pattern A: Two separate script tags

Sitewide block in template head
Page-specific block in template body or a content-type-specific include

Pattern B: Merged graph

Single script tag combining sitewide + page-specific entities
Cleaner output; more complex template logic

Pattern A is easier to maintain. Pattern B is what Yoast / Rank Math output.

8.3 Dynamic Sites

For React, Next.js, Astro, Hugo, etc., the schema is built from data at render time. Maintain a single schema.ts (or equivalent) module that exports typed builders:

export function organizationSchema(): Organization { /* ... */ }
export function articleSchema(post: Post): Article { /* ... */ }
export function pageSchema(page: Page): WebPage { /* ... */ }

Tests assert the output validates. Cross-reference: framework-nextjs.md, framework-astrohugo.md.

8.4 WordPress Sites

Yoast and Rank Math both output JSON-LD using the @id graph pattern. Verify their output rather than rebuilding. Common gotchas:

Yoast and Rank Math both running → duplicate schema. Pick one.
Theme adding schema in addition to the plugin → duplicate or conflicting. Strip theme schema.
Plugin defaults inadequate (e.g., missing Person schema for the site owner) → use plugin's customization hooks.

9. Validation Methodology

9.1 Per-URL Validation

Three tools to run on every important page:

Google Rich Results Test — confirms Google can parse and what rich results are eligible.
Schema.org Validator — confirms strict schema.org compliance (catches issues Google's tool doesn't).
Yandex Microdata Validator — third opinion; sometimes catches edge cases.

A page that passes all three is in good shape.

9.2 Sitewide Validation

For sites with many URLs, sample-test rather than per-URL:

Pick one URL per content type (homepage, About, blog post, service page, product page if ecommerce, etc.)
Run the three validators on each
Crawl the site with Screaming Frog — Custom Extraction can pull JSON-LD blocks from every URL
Programmatically parse and validate (custom script + schema.org's Java validator or a Node lib like structured-data-testing-tool)

9.3 GSC Enhancements Monitoring

Google Search Console's Enhancements section reports schema-related issues sitewide. Categories include Articles, Products, FAQs, How-tos, Breadcrumbs, Sitelinks searchbox, Logos, etc. Check monthly. New errors usually indicate a template change broke schema for a content type.

10. Schema for AI Search

In 2026, AI search engines (ChatGPT, Perplexity, Claude, Gemini, Copilot) use schema as a primary signal for entity extraction. Practical implications:

10.1 Make Claims Extractable

AI engines parse schema looking for atomic facts: "Joseph W. Anady is the founder of That Stupid Computer," "That Stupid Computer is a SDVOSB business in Cassville, Missouri." Express these as schema:

founder relationship between Person and Organization
address.addressLocality for the city
award, honorificPrefix, certifications declared on Person
description written as plain prose, not marketing copy

10.2 Don't Hide Facts in Prose Only

A page can have a clear fact in body text ("we serve all of Northwest Arkansas") but if it isn't also in the schema (areaServed), AI engines may miss it.

10.3 Use Specific Subtypes

Organization is too generic. LocalBusiness is better. Plumber (a LocalBusiness subtype) is best because it matches a query category. AI search engines weight specificity.

10.4 The answer-capsule Pattern

Pair schema with a 200-300 word "answer capsule" paragraph in the visible page content that AI extractors can copy verbatim. The schema gives them entity confidence; the prose gives them the quote. Cross-reference: framework-aicitations.md.

11. Audit Mode

#	Criterion	Pass/Fail
SC1	Format is JSON-LD (not Microdata or RDFa)
SC2	Sitewide Organization schema present on every page
SC3	Sitewide WebSite schema present on every page
SC4	Person schema for owner/key author present and referenced from Organization
SC5	Per-page WebPage schema present, references WebSite via @id
SC6	BreadcrumbList present on every non-homepage
SC7	@id graph pattern used (entities cross-reference via @id, not duplicated)
SC8	All @id values are absolute URLs with fragment identifier
SC9	sameAs network includes Wikidata Q-ID where claimed
SC10	sameAs network includes 3+ authoritative external profiles
SC11	Article schema on every editorial page with author + publisher refs
SC12	Service or Product schema on every commercial page
SC13	LocalBusiness with specific subtype if local business
SC14	All schema URLs use HTTPS
SC15	Image fields point to existing assets, correct dimensions
SC16	datePublished and dateModified accurate (not faked)
SC17	aggregateRating only present if reviews actually exist
SC18	FAQPage schema only on pages that genuinely answer questions
SC19	No deprecated types (`hCard`, `hReview`, etc.)
SC20	Google Rich Results Test passes for sample of 5+ pages
SC21	Schema.org Validator passes for sample of 5+ pages
SC22	GSC Enhancements section shows zero errors (warnings acceptable)
SC23	No duplicate schema (multiple plugins emitting overlapping blocks)
SC24	sameAs targets verified to resolve and represent same entity
SC25	Schema present in initial HTML (not added by client-side JS)
SC26	Schema identical on mobile and desktop
SC27	Article images provided in 1x1, 4x3, 16x9 ratios
SC28	Wikidata Q-ID present in Person and Organization sameAs if claimed
SC29	Specific LocalBusiness subtype used (not generic LocalBusiness)
SC30	Sitewide schema validated quarterly

Score: 30. World-class: 28+/30.

12. Common Mistakes

Microdata or RDFa instead of JSON-LD. Maintainability nightmare.
One schema per page, no @graph. Misses the cross-referencing benefit.
No Person schema. Erases E-E-A-T author signals.
Generic LocalBusiness. Plumber or Dentist is far stronger than LocalBusiness.
Fabricated aggregateRating. Manual-action territory.
FAQ schema on pages that aren't FAQs. Same.
Schema added by client-side JavaScript. Some crawlers see it; many don't.
Duplicate schema from multiple plugins. Yoast + Rank Math + theme = three Organization blocks. Conflicting signals.
@id values that aren't URIs. Use absolute URLs with # fragments.
Image fields pointing to broken assets. Schema validates but rich results don't show.
datePublished after dateModified. Logical impossibility, occasionally happens.
sameAs targets that don't resolve. Dead links erode signal.
Schema on staging visible to crawlers. Robots-blocked staging still gets indexed sometimes; schema there pollutes the entity graph.
Schema not updated when content changes. Stale wordCount, stale dateModified, stale description.
Skipping BreadcrumbList. Trivial to implement, immediate SERP benefit.
Over-decorating schema with marketing language. "Best plumber in Cassville" in description instead of plain prose. AI extractors discount marketing phrases.

13. Maintenance

Weekly:

Spot-check newly published content for correct schema
Monitor GSC Enhancements for new errors

Monthly:

Sitewide validation sample (5 representative URLs through Rich Results Test)
Review GSC Enhancements report
Verify sameAs targets still resolve

Quarterly:

Comprehensive schema audit (every content type sampled)
Validate Wikidata Q-IDs still claimed
Refresh any schema fields that depend on counted data (review counts, post counts, etc.)
Review new Schema.org types released; adopt where applicable

Annually:

Full sitewide JSON-LD extraction and programmatic validation
Review schema strategy against new SERP features and AI search developments
Verify schema authoring tools (plugins, modules) are up to date

14. Companion Documents

framework-knowledgegraph.md — Wikidata claiming, Knowledge Panel, sameAs network construction
framework-eeat.md — Person schema's role in E-E-A-T signals
framework-localseo.md — LocalBusiness subtype selection and full local schema depth
framework-aicitations.md — Schema's role in AI search citation
framework-ecommerceseo.md — Product schema, MerchantReturnPolicy, OfferShippingDetails
framework-videoseo.md — VideoObject and video sitemap
framework-spampolicies.md — Schema spam policies (fabricated reviews, FAQ misuse)
framework-internallinking.md — BreadcrumbList placement strategy
framework-technicalseo.md — Schema's place in the indexing pipeline

Document version: 1.0
Last updated: 2026-05-05
Owner: Joseph W. Anady — ThatDeveloperGuy — SDVOSB

About this framework library

This article is the Dev.to republish of a framework reference document from ThatDevPro's SEO + AI engineering library. Canonical source: https://www.thatdevpro.com/insights/framework-schema/

Companion 14-tier Engine Optimization stack (each tier is its own article):

Need this framework implemented on your site? See the Engine Optimization service or hire through ThatDevPro contact.

Wikidata, Wikipedia, and Knowledge Graph entity engineering

Joseph Anady — Sun, 24 May 2026 01:03:36 +0000

Originally published at thatdevpro.com. Part of ThatDevPro's open SEO + AI framework library. ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.

Establishing Entities in Google's Knowledge Graph — Wikidata, Wikipedia, and the Entity Web

A comprehensive installation and audit reference for establishing a business and its key entities in Google's Knowledge Graph, claiming and managing the Knowledge Panel, building reciprocal entity reconciliation across the web, and maintaining the entity authority that compounds across rankings, AI engines, and brand search results. This document is dual-purpose: installation manual and audit document.

Cross-stack implementation note: the code samples in this framework are written in plain HTML for clarity. For React, Vue, Svelte, Next.js, Nuxt, SvelteKit, Astro, Hugo, 11ty, Remix, WordPress, Shopify, and Webflow equivalents of every pattern below, see framework-cross-stack-implementation.md. For pure client-rendered SPAs (no SSR/SSG) see framework-react.md. For Tailwind-specific concerns (purge, dynamic classes, dark-mode CLS, focus accessibility) see framework-tailwind.md.

1. Document Purpose & How to Use This Document

1.1 What This Document Is

This is the canonical reference for establishing entities in Google's Knowledge Graph (KG). The Knowledge Graph is Google's database of entities and their relationships — people, places, organizations, products, concepts, events. When Google recognizes an entity in its Knowledge Graph, that recognition manifests as Knowledge Panels in search results, populates AI Overviews, drives entity-based ranking, and feeds the data that LLMs train on.

This framework specifies how to assess current entity recognition status, how to build the foundation for entity recognition (Wikidata being the primary path), how to pursue Wikipedia inclusion when notability supports it, how to claim and optimize the Knowledge Panel when it appears, and how to maintain entity authority over time. It also specifies entity reconciliation — the process by which Google associates external profiles, references, and data points with the canonical entity in its Knowledge Graph.

Entity authority compounds. Every authoritative reference, every Wikidata property added, every Wikipedia mention, every reciprocal external link reinforces Google's confidence in the entity. Conversely, weak or fragmented entity signals leave Google uncertain — and uncertain entities don't get Knowledge Panels, don't rank as authoritatively, and don't get cited by AI engines.

1.2 Three Operating Modes

Mode A — Install Mode: Building entity recognition from scratch or adding to existing presence. Follow Sections 2 → 14.

Mode B — Audit Mode: Evaluating existing Knowledge Graph status. Skip to Section 11.

Mode C — Hybrid Mode: Audit then install for gaps.

1.3 How Claude Code CLI Should Consume This Document

Read Section 2 — collect client variables, especially existing entity references
Read Section 3 — understand the Knowledge Graph and entity ecosystem
Run Section 4 — assess current entity recognition status
Install Sections 5-9 — Wikidata first, then external reconciliation, then Wikipedia if notable, then Knowledge Panel claim
Validate — Section 11
Generate report — Section 14

1.4 Conflict Resolution Rules

Conflict	Rule
Existing Wikidata entry with errors	Audit; correct via standard Wikidata editing process. Do not delete and recreate.
Existing Wikipedia article with errors	Use talk page to discuss; let community editors handle changes. Don't edit your own entry.
Multiple Wikidata entries for same entity	Use merge process; flag for review by Wikidata community.
Knowledge Panel showing wrong information	Suggest edit through Knowledge Panel suggest-edit feature.
Entity name conflict with existing notable entity	Disambiguate clearly; never try to claim someone else's entity.

1.5 Required Tools

Wikidata — wikidata.org — primary platform for entity creation and management
Wikipedia — wikipedia.org — for notable entities
Google Search Console — to verify Knowledge Panel claim eligibility
Google Knowledge Graph Search API — developers.google.com/knowledge-graph — to verify entity recognition
OpenRefine — openrefine.org — for batch entity reconciliation
Wikidata Query Service — query.wikidata.org — for testing Wikidata entries

2. Client Variables Intake

# ============================================
# KNOWLEDGE GRAPH FRAMEWORK CLIENT VARIABLES
# ============================================

# --- Business Entity (REQUIRED) ---
business_name: ""                    # Canonical name as entity
business_alternate_names: []         # All variations
business_legal_name: ""              # If different from canonical
business_type: ""                    # Schema.org type
business_founded_year: ""
business_founder_names: []
business_founder_qids: []            # Wikidata QIDs if exist
business_industry: ""
business_industry_qid: ""            # Wikidata industry classification
business_headquarters_city: ""
business_headquarters_country: ""
business_official_website: ""

# --- Existing Entity Recognition Status (REQUIRED) ---
business_in_knowledge_graph: false   # Use Knowledge Graph Search API to check
business_knowledge_panel_appears: false  # Search business name; does panel appear?
business_wikidata_qid: ""            # Existing Wikidata entry if any
business_wikipedia_article_exists: false
business_wikipedia_article_url: ""

# --- Founder Entity (REQUIRED) ---
founder_full_name: ""
founder_alternate_names: []
founder_birth_year: ""               # Optional but helps disambiguation
founder_credentials: []
founder_employer_qid: ""             # Wikidata QID for current/founded business
founder_in_knowledge_graph: false
founder_wikidata_qid: ""
founder_wikipedia_article_exists: false

# --- Notability Assessment (REQUIRED for Wikipedia) ---
business_independent_secondary_sources: []  # URLs of substantial coverage in independent publications
business_passes_wikipedia_notability_test: false
founder_independent_secondary_sources: []
founder_passes_wikipedia_notability_test: false

# --- External Profile Inventory (REQUIRED for sameAs reconciliation) ---
business_linkedin_url: ""
business_x_url: ""
business_facebook_url: ""
business_youtube_url: ""
business_github_org_url: ""
business_crunchbase_url: ""
business_bbb_url: ""
business_chamber_of_commerce_url: ""
business_industry_directory_urls: []

founder_linkedin_url: ""
founder_x_url: ""
founder_github_url: ""
founder_huggingface_url: ""
founder_orcid: ""
founder_personal_site_url: ""
founder_other_profile_urls: []

# --- Topical Entity Coverage (RECOMMENDED) ---
primary_topical_entities: []         # Topics covered with topical hub pages
topical_entity_qids: {}              # Existing Wikidata QIDs for major topics

# --- Knowledge Graph Strategy Status (REQUIRED) ---
has_strategy_for_kg_inclusion: false
plans_to_pursue_wikipedia_inclusion: ""  # "yes_now", "yes_when_notable", "no", "uncertain"
plans_to_create_wikidata_entries: false
has_kg_inclusion_timeline: false

# --- Entity Maintenance (REQUIRED ongoing) ---
wikidata_last_reviewed: ""
wikipedia_last_monitored: ""
knowledge_panel_last_audited: ""
external_profile_last_audited: ""

3. What the Knowledge Graph Is

Google's Knowledge Graph is a database of entities and their relationships. Launched in 2012, it powers:

Knowledge Panels in search results (the boxes on the right side showing entity information)
Featured snippets and rich results for entity-related queries
AI Overview source selection — AI Overviews preferentially cite Knowledge Graph entities
Voice search and assistant responses ("Hey Google, who is...")
Entity-based ranking — pages associated with recognized entities benefit
Disambiguation — when multiple entities share names, KG provides the disambiguation infrastructure

The Knowledge Graph contains hundreds of billions of facts about millions of entities. Most is automatically extracted from sources like Wikipedia, Wikidata, government databases, structured data on websites, and news mining. Some is manually curated.

Entity inclusion in the Knowledge Graph isn't binary — it's confidence-based. Google may have very high confidence in well-established entities (Apple Inc, Albert Einstein, Tokyo) and lower confidence in less-established entities. Confidence determines whether Knowledge Panels appear, how prominently the entity features in results, and how authoritatively the entity is treated in AI Overviews.

Entity confidence comes from:

1. Wikidata presence — Wikidata entries are direct input into Google's Knowledge Graph. A complete, well-cited Wikidata entry is the strongest single signal for entity inclusion.

2. Wikipedia presence — Wikipedia articles flow into Wikidata and are direct sources for Knowledge Panels. Wikipedia coverage is a strong signal but has higher notability requirements than Wikidata.

3. Schema markup with sameAs — Schema on the entity's official website that declares sameAs links to authoritative external profiles helps Google reconcile the entity.

4. Citation by other authoritative sources — When other recognized entities reference this entity, confidence increases.

5. Consistent factual data across sources — When the same facts appear across multiple authoritative sources, confidence increases.

6. Structured data accessibility — Sites that expose entity data via schema, API, or other structured formats are easier to ingest into KG.

The 2026 evolution of the Knowledge Graph is significant. AI engines (ChatGPT, Perplexity, Claude, Gemini) all rely on entity data overlapping with Google's KG. Entities recognized in KG get cited more frequently across AI engines. The Knowledge Graph is no longer just for Google search — it's foundational infrastructure for the entire AI search ecosystem.

For any business or individual seeking to be recognized as an authoritative entity in 2026, Knowledge Graph inclusion is foundational — not optional.

4. Current Entity Recognition Assessment

Before pursuing inclusion, understand current status.

4.1 Knowledge Graph Search API Check

Use Google's Knowledge Graph Search API to check if entities are already recognized:

curl "https://kgsearch.googleapis.com/v1/entities:search?query={{ENTITY_NAME}}&key={{API_KEY}}&limit=10"

The response shows whether Google has the entity, its type, description, and confidence score. If the entity returns:

Strong match (resultScore >100): Entity is well-recognized
Weak match (resultScore <100): Some recognition but not strong
No match: No KG presence

For this site's primary entities (business, founder, key topics), document current status.

4.2 Knowledge Panel Search Test

In incognito mode, search for the entity name and document:

Does a Knowledge Panel appear on the right side?
What information is in the panel?
Is the information accurate?
Is the panel "claimed" (has owner verification)?
What sources does the panel cite (Wikipedia, official website, etc.)?

Test variations:

{{exact_business_name}}
{{business_name}} {{location}}
{{business_name}} {{founder_name}}
{{founder_full_name}}
who is {{founder_name}}

4.3 Wikidata Direct Search

Search Wikidata directly: wikidata.org/w/index.php?search={{ENTITY_NAME}}

Document:

Existing entries that match
Existing entries that conflict (other entities with same name)
Whether existing entry is complete and accurate

4.4 Wikipedia Search

Search Wikipedia: en.wikipedia.org/w/index.php?search={{ENTITY_NAME}}

Document:

Existing article if any
Quality and completeness of article
Whether the article links to the official website

4.5 External Profile Mapping

Document all existing external profiles for the entity. Each profile is a potential sameAs reconciliation point:

business_external_profiles:
  - platform: "LinkedIn"
    url: ""
    verified: false
    matches_official_data: true
  - platform: "X / Twitter"
    url: ""
    verified: false
    matches_official_data: true
  - platform: "Crunchbase"
    url: ""
    matches_official_data: true
  # ... etc

Identify any profiles with mismatched data (different addresses, different founding dates, etc.). These need correction before reconciliation, or they'll undermine entity confidence.

4.6 Recognition Status Summary

After assessment, classify status:

Established entity — Strong KG presence, accurate Knowledge Panel, complete Wikidata, possible Wikipedia. Focus on maintenance and refinement.
Recognized but partial — Some KG presence, partial info, no Knowledge Panel or unclaimed panel. Focus on completion and claiming.
Minimal recognition — Some external profiles but no KG presence. Focus on creating Wikidata entry and reconciliation.
No recognition — No external profiles, no Wikidata, no KG. Foundation must be built from scratch.

The implementation path varies by status.

5. Wikidata Implementation (Foundation)

Wikidata is the primary path to Knowledge Graph inclusion. Wikidata has a lower notability bar than Wikipedia and is direct input to Google's Knowledge Graph. Every entity that wants KG inclusion should have a Wikidata entry as foundation.

5.1 Wikidata Notability Requirements

To create a Wikidata entry, the entity must satisfy at least one notability criterion:

Has a Wikipedia article in any language (automatic notability)
Refers to an instance of a clearly identifiable conceptual or material entity (most businesses, people, places qualify)
Fulfills a structural need to make statements about other entities

For most businesses and individuals associated with businesses, criterion 2 applies. Notability bar is essentially: is this a real, identifiable entity that people might reasonably want to make statements about?

5.2 Wikidata Account Setup

Create a Wikidata account at wikidata.org. Use a real account with established edit history if possible — accounts with no history can have edits scrutinized more carefully.

Best practice: declare conflict of interest on user page if creating entry for own business or self.

5.3 Creating the Business Entity

Navigate to wikidata.org/wiki/Special:NewItem.

Required initial fields:

Label — {{business_name}} (canonical form, capitalized correctly)

Description — Concise (under 250 char), defining sentence. Examples:

"American technology company headquartered in Cupertino, California" (Apple Inc.)
"Service-Disabled Veteran-Owned web development and SEO firm based in Cassville, Missouri" (ThatDeveloperGuy)

Aliases — All alternate names. List every legitimate alternate spelling, abbreviation, DBA name.

After creating the basic entry, populate properties.

5.4 Required Wikidata Properties for Businesses

Add these properties (Wikidata uses property IDs like P31, P17 — find each on Wikidata's property documentation):

Property	Property ID	Value Source
Instance of	P31	Type — "business" (Q4830453), "company" (Q783794), or more specific
Country	P17	Country (US = Q30)
Headquarters location	P159	City Wikidata QID
Founder	P112	Person Wikidata QID (create if needed)
Inception	P571	Founding date
Industry	P452	Industry QID
Official website	P856	Domain URL
Logo image	P154	Wikimedia Commons file (upload first if not there)
Coordinates	P625	Lat/long for physical location

Example of a populated business entry:

Item: Q138610626 (ThatDeveloperGuy)
Label (en): ThatDeveloperGuy
Description (en): Service-Disabled Veteran-Owned web development and SEO firm based in Cassville, Missouri

Statements:
- instance of (P31): business (Q4830453)
- country (P17): United States of America (Q30)
- headquarters location (P159): Cassville (Q...)
- founder (P112): Joseph Anady (Q... if created)
- inception (P571): 2020
- industry (P452): web development (Q386275)
- official website (P856): https://thatdeveloperguy.com
- coordinates (P625): 36.6770° N, 93.8730° W

External Identifiers:
- LinkedIn (P4264): {{linkedin_handle}}
- Crunchbase (P2087): {{crunchbase_id}}

5.5 Required References for Each Property

Every statement should be supported by a reference:

inception (P571): 2020
References:
- stated in: official website (P856) of subject
- reference URL: https://thatdeveloperguy.com/about/
- retrieved: 2026-04-29

Without references, statements can be challenged. With strong references, the entry is robust against editor revisions.

5.6 Creating the Founder Person Entity

Same process for founder. Required Person properties:

Property	Property ID	Value
Instance of	P31	human (Q5)
Country of citizenship	P27	Country
Date of birth	P569	If notable; can omit for privacy
Place of birth	P19	If notable
Occupation	P106	Occupation QIDs
Employer	P108	Business QID (the entity created above)
Educated at	P69	School QIDs
Field of work	P101	Field QIDs
Native language	P103	Language QID
Official website	P856	Personal site if exists

External Identifier properties for founder:

Identifier	Property ID
LinkedIn personal profile	P6634
GitHub username	P2037
Hugging Face username	P9100
ORCID iD	P496
X (Twitter) username	P2002

5.7 Topical Entity Wikidata Entries

For unique topical entities the site is the authority on (specific frameworks, methods, tools the site has created), create Wikidata entries. Most general topics already have entries.

For example, if the site has authored a specific framework called "SDVOSB Engine Optimization Methodology," that could be a Wikidata entity:

Item: Q... (SDVOSB Engine Optimization Methodology)
Label (en): SDVOSB Engine Optimization Methodology
Description (en): A 14-tier framework for search engine and AI engine optimization developed by Joseph Anady at ThatDeveloperGuy

Statements:
- instance of (P31): methodology (Q1799072)
- developed by (P178): Joseph Anady (Q...)
- subclass of (P279): search engine optimization (Q180711)
- depicts (P180): 14-tier framework

5.8 Cross-Linking via External Identifiers

Wikidata's external identifier properties allow direct linking to authoritative external databases. Add as many as apply:

For businesses:

LinkedIn company ID (P4264)
Crunchbase organization ID (P2087)
BBB business profile (... if property exists)
Industry-specific identifiers (BSI, NAICS code, etc.)

For people:

LinkedIn personal ID (P6634)
ORCID (P496)
Google Scholar author ID (P1960)
ResearchGate profile (P6178)
GitHub username (P2037)

External identifiers strengthen entity reconciliation — they tell systems unambiguously that this Wikidata entity is the same entity as in those external sources.

5.9 Wikimedia Commons Logo Upload

Upload the business logo to Wikimedia Commons:

Visit commons.wikimedia.org/wiki/Special:UploadWizard
Confirm copyright (logo must be licensed permissively or be your own work you license)
Upload with descriptive filename: ThatDeveloperGuy-logo.svg
Add to Wikidata entry as logo image (P154)

The logo is then available for use in Knowledge Panels and other systems.

5.10 Patience for Wikidata Propagation

After creating Wikidata entries, allow time for propagation:

24-72 hours for community visibility
1-4 weeks for Google's Knowledge Graph ingestion
1-3 months for stable Knowledge Panel appearance (typically requires multiple signals beyond Wikidata)

Don't expect immediate Knowledge Panel from Wikidata alone. Wikidata is foundational; other signals build on it.

6. External Reconciliation Strategy

Beyond Wikidata, build the network of references that reinforce entity recognition.

6.1 Schema sameAs on Official Website

The official website's Organization and Person schema must include sameAs links to all authoritative external profiles AND to the Wikidata entry:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://{{domain}}/#organization",
  "name": "{{business_name}}",
  "sameAs": [
    "https://www.wikidata.org/wiki/{{business_qid}}",
    "https://en.wikipedia.org/wiki/{{business_wiki_slug}}",
    "{{linkedin_company_url}}",
    "{{x_company_url}}",
    "{{facebook_url}}",
    "{{crunchbase_url}}",
    "{{bbb_url}}",
    "{{youtube_channel_url}}",
    "{{github_org_url}}",
    "{{industry_directory_urls}}"
  ]
}
</script>

This declares: "All these URLs refer to the same entity." Google uses this for entity reconciliation.

6.2 Reciprocal sameAs from External Profiles

Where possible, add the website URL to external profiles so reconciliation is bidirectional:

LinkedIn company page: lists official website
X bio: includes website URL
Crunchbase profile: official website field
Personal LinkedIn: lists company and website
GitHub org/user: website field

Some platforms allow rel="me" markup for verified mutual claiming. Where supported (Mastodon, personal sites), use rel="me" to formally declare the relationship.

6.3 Authority-Building Profile Coverage

Build presence on platforms that contribute to entity authority:

For businesses:

LinkedIn Company Page
Google Business Profile
Crunchbase
BBB (where applicable)
Trustpilot
Industry-specific directories (Clutch for B2B services, etc.)
Local Chamber of Commerce
State business registry (already exists if formally registered)

For founders:

LinkedIn personal profile
GitHub (for developers)
Hugging Face (for AI work)
ResearchGate or ORCID (for academics)
Industry-specific profiles
Personal domain with comprehensive bio

6.4 Industry-Specific Authoritative Listings

Each industry has authoritative directories Google trusts:

Medical: NPI registry, state medical board, hospital staff directory
Legal: Bar association directory, Avvo, Martindale-Hubbell
Financial: BrokerCheck, SEC IAPD, Form ADV
Real estate: NAR, state real estate licensing
Construction: state contractor licensing, BBB

Listing on these sources contributes to entity authority and provides additional sameAs targets.

6.5 Earned Media Coverage

When the entity is featured in articles, news, or industry publications, ensure:

The publication's article links to the official website
The article uses the canonical entity name
The article references factual data consistent with Wikidata/official sources

Inconsistencies across earned media weaken entity confidence. Reach out to publications to correct factual errors when they appear.

6.6 Press Kit With Canonical Entity Data

Maintain a press kit at /press/ with canonical entity facts:

Official entity name and acceptable abbreviations
Founding year
Founder names with correct spellings
Headquarters location
Industry classification
Brief description (matching Wikidata description)
High-resolution logos
Founder photos
Recent press releases

Make it easy for journalists to use correct facts. Inconsistent facts in earned media create entity confusion that takes time to resolve.

7. Wikipedia Strategy

Wikipedia has a higher notability bar than Wikidata. Don't pursue Wikipedia until notability is genuinely demonstrable.

7.1 Wikipedia Notability Test

Wikipedia's notability requirement: "significant coverage in independent reliable secondary sources."

Tests:

Significant coverage — multiple paragraphs about the entity, not just passing mention
Independent — not the entity's own marketing, press releases, or affiliated sources
Reliable — established publications with editorial standards (newspapers, trade publications, academic journals, books)
Secondary sources — not primary sources like the entity's own website or interviews

For most businesses, Wikipedia notability requires:

Coverage in 3+ independent reliable sources
Coverage that's substantive (not just listings or brief mentions)
Coverage spanning more than a single time period

For most individuals, similar tests but framed around the person's accomplishments, work, recognition.

If notability is genuinely there, Wikipedia inclusion follows. If it's not, attempting to create a Wikipedia article will result in deletion, often with administrative rebuke that makes future attempts harder.

7.2 Don't Create Your Own Wikipedia Article

Wikipedia has strong policies against creating articles about yourself or your business (conflict of interest). Articles created by COI editors are flagged, scrutinized, often deleted.

Better path:

Build genuine notability over time
Wait for organic article creation by an independent editor
If asked, provide factual support to editors but don't draft the article

7.3 If You Must Create a Wikipedia Article

If notability is genuinely strong and no organic editor is creating an article, the legitimate path:

Disclose conflict of interest on user page
Use Articles for Creation process (en.wikipedia.org/wiki/Wikipedia:Articles_for_creation) rather than direct creation
Submit through draft review by uninvolved editors
Accept their feedback and revisions

The article must:

Be written in encyclopedic tone, not promotional
Cite multiple independent reliable sources
Cover both achievements and any controversies fairly
Avoid superlatives, marketing language, original research
Use neutral point of view

7.4 Maintaining the Wikipedia Article

Once created, monitor the article but don't edit it directly:

Watch for changes via Wikipedia's watchlist feature
Use Talk page to suggest corrections with citations
Engage with editors who request information
Provide source materials when requested
Accept that the article belongs to Wikipedia community, not the subject

Inappropriate editing of own Wikipedia article causes:

Edit reverts
Articles flagged for COI review
Sometimes article deletion
Editor account sanctions

7.5 What Wikipedia Inclusion Adds

When/if Wikipedia article exists:

Knowledge Graph confidence increases dramatically
Knowledge Panel typically appears in search results
AI engines cite the entity more confidently
The Wikipedia article becomes input into many derivative systems (LLM training data, AI knowledge bases, etc.)

Wikipedia is force-multiplying for entity authority. But it must be earned, not engineered.

8. Knowledge Panel Claiming

Once an entity has Knowledge Graph recognition, claim the Knowledge Panel for control.

8.1 Verifying Eligibility

Knowledge Panels can be claimed when:

The entity is recognized in Google's Knowledge Graph (Knowledge Panel appears)
You can demonstrate official representation (own the website, are the entity, or are authorized representative)

To check if a Knowledge Panel exists for your entity, search the entity name in Google. The panel appears on the right side (desktop) or below results (mobile).

8.2 Claiming Process

If a Knowledge Panel exists:

Click "Claim this knowledge panel" link in the panel (typically at bottom)
Sign in with Google account
Verify ownership through one of:
- Authorized social profile (verified Twitter/X, official LinkedIn, etc.)
- YouTube channel
- Official Twitter/X account
- Other verified Google service
Wait for Google review (typically days to weeks)

Once claimed, you can:

Suggest edits to information in the panel
Add or update images
Request corrections to factual errors
Update social profile links

8.3 Maintaining the Knowledge Panel

After claiming:

Monthly: review panel for accuracy
After business changes (address, hours, name): suggest update
After credentials/awards: suggest addition
Quarterly: verify all linked profiles still active

8.4 What If No Knowledge Panel Exists

If no Knowledge Panel exists despite Wikidata presence and external profile coverage, possible reasons:

Recognition exists but below threshold for panel display
Entity is too new (give it 3-6 months after building foundation)
Entity confusion (Google can't disambiguate from other entities with same name)
Insufficient cross-source consistency

Continue building entity signals: more authoritative external profiles, more earned media, more consistent factual data across sources, possibly Wikipedia inclusion if notability allows. Knowledge Panel typically follows when entity confidence reaches threshold.

9. Topical Entity Strategy

Beyond business and founder entities, topical entities matter.

9.1 Major Topic Wikidata Entries

Most major topics (web development, SEO, AI, etc.) already have Wikidata entries. Reference them in your content schema:

<script type="application/ld+json">
{
  "@type": "Article",
  "about": [
    {
      "@type": "Thing",
      "name": "Search engine optimization",
      "sameAs": "https://www.wikidata.org/wiki/Q180711"
    }
  ]
}
</script>

Topical hub pages similarly use the Wikidata QID for their primary topic.

9.2 Custom Methodology Entities

If the site has authored unique methodologies, frameworks, or tools, create Wikidata entries for them. See Section 5.7.

9.3 Person-Topic Affinity

Connect people entities to topical entities via Wikidata:

For founder entry, add:

field of work (P101): SEO QID
field of work (P101): Web development QID
field of work (P101): AI optimization QID

This declares topical authority in Wikidata, which compounds with on-site knowsAbout schema.

10. Common Mistakes & Anti-Patterns

10.1 Self-Created Wikipedia Article

Anti-pattern: Creating own Wikipedia article without notability.

Why it fails: Almost certainly deleted. Editor account sanctioned. Future legitimate attempts harder.

Fix: Build notability first. Use Wikidata in the meantime. Wait for organic Wikipedia creation.

10.2 Inconsistent Entity Names Across Sources

Anti-pattern: "ThatDeveloperGuy" on website, "That Developer Guy LLC" on LinkedIn, "TDG Inc" on Crunchbase.

Why it fails: Google can't reconcile these as the same entity. Entity confidence stays low.

Fix: Pick canonical name. Use consistently everywhere. Document acceptable variations as alternateName only.

10.3 Wikidata Without References

Anti-pattern: Wikidata entry created with statements but no supporting references.

Why it fails: Entry is fragile; community editors may revise or remove unsupported statements.

Fix: Cite sources for every statement.

10.4 No Schema sameAs

Anti-pattern: Site has Wikidata entry, but Organization schema doesn't include sameAs link to Wikidata.

Why it fails: Google has to reconcile via other means; loses easy direct signal.

Fix: sameAs link to Wikidata in all relevant schema.

10.5 Sparse External Profile Coverage

Anti-pattern: Only website and one social profile. Nothing else.

Why it fails: Entity reconciliation needs multiple signals. Sparse coverage means low confidence.

Fix: Build coverage on 8-15 authoritative platforms.

10.6 Outdated Wikidata Information

Anti-pattern: Wikidata entry created years ago, never updated. Address has changed, founder roles changed, founding date inaccurate.

Why it fails: Inconsistent data across sources weakens entity confidence.

Fix: Quarterly Wikidata review; keep current.

10.7 Edit Warring on Wikipedia

Anti-pattern: Repeatedly editing your own Wikipedia article to add favorable content.

Why it fails: Article flagged for COI review. Editor account sanctioned. Trust damaged.

Fix: Use Talk page to suggest changes. Provide sources. Let community editors decide.

10.8 Knowledge Panel Errors Ignored

Anti-pattern: Knowledge Panel showing wrong information, no action taken.

Why it fails: Wrong information at the most prominent position in search results. Long-term reputation damage.

Fix: Claim panel; suggest corrections; provide source documentation for corrections.

10.9 Multiple Wikidata Entries for Same Entity

Anti-pattern: Creating new Wikidata entry without checking if one already exists, resulting in duplicates.

Why it fails: Confusion. Statements split across entries. Reconciliation issues.

Fix: Search before creating. If duplicates exist, use Wikidata's merge process.

10.10 Trying to Game Knowledge Graph

Anti-pattern: Creating fake Wikipedia citations, manipulating Wikidata, fabricating earned media to inflate entity authority.

Why it fails: Detection by Wikipedia community is high. Wikidata has data quality processes. Fabricated earned media is detectable. Caught manipulation = catastrophic reputation damage.

Fix: Build genuine entity authority through real work, real notability, real recognition.

11. Audit Mode

11.1 Knowledge Graph Status Audit

#	Criterion	Pass/Fail
KG1	Business entity recognized in Knowledge Graph (KG Search API)
KG2	Founder entity recognized in Knowledge Graph
KG3	Wikidata entry exists for business with 8+ properties
KG4	Wikidata entry exists for founder with 6+ properties
KG5	Wikidata entries have references for all major statements
KG6	Schema sameAs on website includes Wikidata link
KG7	Schema sameAs includes 8+ external profiles
KG8	External profile data is consistent (NAP, dates, etc.)
KG9	Knowledge Panel appears for business name search
KG10	Knowledge Panel claimed (if appears)
KG11	Knowledge Panel information accurate (if appears)
KG12	Wikipedia article exists and accurate (if notability supports)
KG13	Major topical entities referenced via Wikidata QIDs in schema
KG14	Custom methodology entities created in Wikidata where applicable
KG15	Press kit maintained with canonical entity facts

Score: 15. World-class KG status: 13+/15.

11.2 Entity Authority Strength Score

For each primary entity (business, founder, key topics), score:

Signal	Strong (3)	Moderate (2)	Weak (1)	Absent (0)
Wikidata presence	Complete entry with 12+ properties	Basic entry	Minimal entry	None
Wikipedia presence	Substantial article	Brief article	Mention only	None
Schema declaration	Full declaration with sameAs	Partial	Minimal	None
External profile coverage	12+ authoritative profiles	8-11	4-7	<4
Earned media	Multiple substantive coverage	Some coverage	Minimal	None
Industry recognition	Awards, certifications, memberships	Some	Few	None
Knowledge Panel	Claimed and accurate	Appears unclaimed	Appears with errors	Doesn't appear

Per entity: 21 max. Strong entity: 18+/21.

12. Maintenance Schedule

12.1 Monthly

Verify Wikidata entries still accurate; correct if facts changed
Monitor Wikipedia article for changes (if exists)
Check Knowledge Panel for accuracy
Review external profiles for consistency

12.2 Quarterly

Comprehensive entity authority audit
Update press kit with new earned media, achievements
Refresh photos and logos if updated
Cross-check NAP across all profiles

12.3 Annually

Strategic entity review
Pursue new Wikipedia inclusion if notability has grown
Add new topical entities as the site's authority expands
Update Wikidata with significant year's developments

12.4 Event-Driven

Address change → update everywhere within 7 days
Founder change → update Wikidata, Knowledge Panel, schema
New significant earned media → add to press kit, update Wikidata reference
New award/certification → update credentials in Wikidata, schema, About page

13. Cross-Reference to the 14-Tier Framework

Knowledge Graph implementation touches:

Tier 3 KGO — Knowledge Graph Optimization is named for this exact work
Tier 3 WIK — Wikipedia & Wikidata Optimization is the foundational work this framework specifies
Tier 1 SDO — Structured Data Optimization implements schema sameAs for KG reconciliation
Tier 1 EEA — E-E-A-T Entity Optimization with Person/Organization schema
Tier 4 PBO — Personal Brand Optimization extends founder entity work
Tier 4 CHO — Citation/Honors Optimization documents the awards and recognitions that build entity authority

14. Implementation/Audit Report Templates

14.1 Implementation Report Template

# Knowledge Graph Implementation Report

**Site**: {{BUSINESS_NAME}}
**Implementation Date**: {{TODAY}}

## Wikidata Entries Created
- Business: {{QID}} — {{COMPLETENESS_PERCENTAGE}}% properties populated
- Founder: {{QID}} — {{COMPLETENESS_PERCENTAGE}}% properties populated
- Custom methodologies: {{LIST_OF_QIDS}}

## External Reconciliation Status
- Schema sameAs links: {{COUNT}}
- External profiles claimed: {{COUNT}}
- NAP consistency: {{PERCENTAGE}}% across all profiles

## Knowledge Panel Status
- Business: {{APPEARS/DOES_NOT_APPEAR}}, {{CLAIMED/UNCLAIMED}}
- Founder: {{APPEARS/DOES_NOT_APPEAR}}, {{CLAIMED/UNCLAIMED}}

## Wikipedia Status
- Notability assessment: {{ASSESSMENT}}
- Action: {{NONE/ARTICLE_CREATED/ARTICLE_AWAITED}}

## Topical Entity Coverage
{{LIST_OF_TOPICS_AND_QIDS}}

## Press Kit Established
{{STATUS}}

## Sign-Off

14.2 Audit Report Template

# Knowledge Graph Audit Report

**Site**: {{BUSINESS_NAME}}
**Audit Date**: {{TODAY}}

## Overall KG Status
{{ESTABLISHED / RECOGNIZED_PARTIAL / MINIMAL / NONE}}

## KG Status Score
{{X}}/15

## Entity Authority Strength
- Business: {{X}}/21
- Founder: {{X}}/21
- Primary topics: {{ASSESSMENT}}

## Wikidata Findings
{{DETAILED_FINDINGS}}

## Wikipedia Findings
{{DETAILED_FINDINGS}}

## External Reconciliation Findings
{{DETAILED_FINDINGS}}

## Knowledge Panel Findings
{{DETAILED_FINDINGS}}

## Critical Failures
{{LIST}}

## Recommended Implementation Order
{{PRIORITIZED_LIST}}

## Sign-Off

End of Framework Document

Document version: 1.0
Last updated: 2026-04-29
Maintained by: ThatDeveloperGuy

Knowledge Graph inclusion is foundational entity authority infrastructure for 2026. Without it, entities operate at a permanent confidence disadvantage in search rankings, AI citations, and brand recognition. With it, every other quality signal compounds — E-E-A-T is stronger when the entity is recognized, content ranks better when its primary entity is authoritative, AI engines cite the entity preferentially.

The work is methodical. Wikidata first. External reconciliation. Wikipedia when notable. Knowledge Panel claim. Then maintain. The compound returns over time are substantial.

Companion documents:

framework-eeat.md
framework-ymyl.md
framework-hcs.md
framework-sqrg.md
framework-coreupdates.md
framework-infogain.md
framework-entitysalience.md
framework-aicitations.md

About this framework library

Companion 14-tier Engine Optimization stack (each tier is its own article):

Need this framework implemented on your site? See the Engine Optimization service or hire through ThatDevPro contact.

Google's 18 spam policies and how to comply

Joseph Anady — Sun, 24 May 2026 01:03:28 +0000

Originally published at thatdevpro.com. Part of ThatDevPro's open SEO + AI framework library. ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.

Google's Explicit Anti-Spam Policies — What Gets Punished, How to Avoid It, and How to Recover

A comprehensive installation and audit reference for understanding Google's documented spam policies, identifying spam policy violations on a website, remediating violations, recovering from spam updates and manual actions, and building structural defenses against accidentally violating spam policies through scale or third-party content. This document is dual-purpose: installation manual and audit document.

Cross-stack implementation note: the code samples in this framework are written in plain HTML for clarity. For React, Vue, Svelte, Next.js, Nuxt, SvelteKit, Astro, Hugo, 11ty, Remix, WordPress, Shopify, and Webflow equivalents of every pattern below, see framework-cross-stack-implementation.md. For pure client-rendered SPAs (no SSR/SSG) see framework-react.md. For Tailwind-specific concerns (purge, dynamic classes, dark-mode CLS, focus accessibility) see framework-tailwind.md.

1. Document Purpose & How to Use This Document

1.1 What This Document Is

This is the canonical reference for Google's spam policies — the documented rules at developers.google.com/search/docs/essentials/spam-policies that define what Google considers manipulative practices, what triggers algorithmic spam updates, and what triggers manual actions. While the rest of the foundational framework library focuses on what to do to earn rankings and citations, this document focuses on what not to do — the practices that result in ranking suppression, deindexing, or manual penalties regardless of how strong other signals are.

Spam policies are operationally distinct from quality frameworks. A site can score 130/130 on E-E-A-T, satisfy YMYL standards perfectly, and still get hit by a spam policy violation that suppresses or removes it from search entirely. Conversely, a site can have weak E-E-A-T and still avoid spam violations. The two systems run in parallel — quality frameworks affect where you rank; spam policies affect whether you can rank at all.

The 2024-2026 evolution of Google's spam policies has been significant. The March 2024 update added three new spam policies (scaled content abuse, site reputation abuse, expired domain abuse) and integrated existing policies more aggressively into core ranking. The May 2024 spam update enforced these policies with substantial site impact. Continuing through 2025 and into 2026, spam updates have run alongside core updates with increasing frequency, and manual action issuance has accelerated for the new policy categories.

This document specifies every documented spam policy, the patterns Google uses to detect violations, defensive structural patterns to prevent accidental violations, response procedures when violations are detected, and recovery protocols for both algorithmic suppression and manual actions.

1.2 Three Operating Modes

Mode A — Install Mode: Building defensive infrastructure into a site to prevent spam policy violations. Follow Sections 2 → 14.

Mode B — Audit Mode: Evaluating an existing site for spam policy compliance. Skip to Section 11.

Mode C — Hybrid Mode: Audit then install for failing items.

1.3 How Claude Code CLI Should Consume This Document

Read Section 2 — collect client variables, especially historical penalty status
Read Section 3 — understand the difference between spam updates, manual actions, and core updates
Apply Section 4 — work through every documented spam policy systematically
Apply Section 5 — special focus on the three policies added in March 2024 (most active enforcement)
Install defensive patterns — Sections 6-9
Validate — Section 11
If active violation suspected — go directly to Section 10 (response and recovery)
Generate report — Section 14

1.4 Conflict Resolution Rules

Conflict	Rule
Existing manual action	Stop all other work. Section 10.3 takes priority.
Suspected scaled content abuse	Audit immediately. Stop publishing AI content until audit complete.
Existing site reputation abuse via subdomain/subfolder leasing	Terminate the arrangement. No remediation works while it's active.
Existing expired domain abuse	Either commit to substantively continuing original purpose or migrate to new domain.
Existing link schemes	Disavow + cease + document for any reconsideration request.
Aggressive SEO contractor recommending policy-violating practices	Do not implement. Document advice in writing for accountability.

1.5 Required Tools

Google Search Console — primary source for manual action notifications and spam-related ranking data
Google Search Console Disavow Tool — for disavowing toxic backlinks
Bing Webmaster Tools — parallel monitoring for Bing manual actions
The actual spam policies documentation — developers.google.com/search/docs/essentials/spam-policies
Originality.ai or similar — AI content detection for scaled content abuse audit
Ahrefs/Semrush/Majestic — backlink profile auditing for link scheme detection
Wayback Machine — historical site state research, especially for expired domain audit
Server logs — to detect cloaking, sneaky redirects, hacked content

2. Client Variables Intake

# ============================================
# SPAM POLICIES FRAMEWORK CLIENT VARIABLES
# ============================================

# --- Business Identity (REQUIRED) ---
business_name: ""
primary_domain: ""
domain_age_years: 0
domain_acquired_from_someone_else: false  # Critical — if true, expired domain abuse risk
previous_domain_owner_known: ""
previous_domain_purpose: ""

# --- Penalty History (REQUIRED) ---
has_received_manual_action: false
manual_action_history: []            # List of past manual actions and dates
has_filed_reconsideration_request: false
reconsideration_request_outcome: ""
historical_spam_update_impacts: []    # Past spam updates that affected this site

# --- Content Creation Patterns (REQUIRED — be honest) ---
publishes_ai_generated_content: false
ai_content_publication_volume: ""    # "low" (<5/month), "medium" (5-50/month), "high" (>50/month)
ai_content_review_quality: ""        # "expert_review", "editor_review", "minimal_review", "none"
ai_content_disclosure: false
publishes_at_high_volume: false      # >10 articles per week
content_outsourced_to_freelancers: false
content_outsourced_volume: ""

# --- Site Architecture (REQUIRED) ---
has_subdomains: false
subdomain_list: []
has_subfolders_with_external_content: false  # Critical for site reputation abuse
external_partners_publishing_on_site: []
allows_user_generated_content: false
ugc_moderation_level: ""             # "none", "post_hoc", "pre_publication", "vetted_only"

# --- Linking Patterns (REQUIRED) ---
has_outbound_paid_links: false
paid_links_use_rel_sponsored: false
has_link_exchange_arrangements: false
has_purchased_links: false
has_used_link_building_services: false
sponsored_content_disclosed: false
affiliate_links_use_rel_sponsored: false

# --- Technical Spam Vectors (REQUIRED) ---
serves_different_content_to_googlebot: false  # Cloaking risk
uses_user_agent_detection: false
has_redirect_chains: false
has_meta_refresh_redirects: false
has_javascript_redirects_obscuring_destination: false
has_doorway_pages: false             # Many pages targeting variations of same intent
has_thin_pages_targeting_keywords: false

# --- Content Quality Signals (REQUIRED) ---
has_scraped_or_syndicated_content_without_value_add: false
has_duplicated_content_across_pages: false
has_machine_translated_content_without_review: false
has_auto_generated_text_filler: false
has_keyword_stuffed_content: false
has_invisible_or_misleading_text: false

# --- Hacking & Security (REQUIRED) ---
last_security_audit_date: ""
has_been_hacked_historically: false
hack_remediation_complete: false
has_2fa_on_admin_accounts: false
has_security_monitoring: false

# --- Affiliate & Monetization (REQUIRED) ---
business_model_includes_affiliate: false
affiliate_content_adds_value_beyond_links: false  # Honest answer
affiliate_disclosure_present: false
affiliate_disclosure_clear_and_conspicuous: false

# --- E-Commerce Specific (if applicable) ---
sells_user_data: false
displays_misleading_product_information: false
deceptive_pricing_practices: false
fake_reviews_present: false
review_acquisition_methods: []        # How reviews are obtained

# --- Compliance Documentation (REQUIRED) ---
has_documented_anti_spam_policies: false
has_third_party_content_review_process: false
has_link_acquisition_policy: false
has_ai_content_policy: false
quarterly_spam_audit_performed: false

After variables are gathered, save as spam-policies-variables.yml.

3. What Spam Policies Are

Google's spam policies are explicit rules documented at developers.google.com/search/docs/essentials/spam-policies that define manipulative practices Google does not allow in search results. These are operationally distinct from quality frameworks like E-E-A-T or HCS.

3.1 The Three Enforcement Mechanisms

Algorithmic Spam Updates — Periodic updates to Google's spam-detection algorithms. Like core updates, they roll out over days to weeks, are publicly named, and affect rankings broadly. Sites violating spam policies see ranking suppression, sometimes severe. Recovery requires remediation plus time. Recent named spam updates include:

May 2024 Spam Update (enforcement of the new March 2024 policies)
October 2024 Spam Update
December 2024 Spam Update
June 2025 Spam Update
November 2025 Spam Update

Manual Actions — Human-issued penalties communicated via Search Console under Security & Manual Actions. Manual actions can be partial (specific pages or sections affected) or sitewide. Some are reconsideration-eligible (after demonstrating remediation), some are not. Manual action types include:

Site abused with third-party spam
User-generated spam
Spammy free hosts
Structured data issue
Unnatural links to your site
Unnatural links from your site
Thin content with little or no added value
Cloaking and/or sneaky redirects
Pure spam
Cloaked images
Hidden text and/or keyword stuffing
AMP content mismatch
Sneaky mobile redirects
News and Discover policy violations

Algorithmic Demotion (No Manual Action) — Some spam-detection happens algorithmically without manual review, resulting in ranking suppression without an explicit manual action notification. Sites may experience traffic loss without knowing the cause. These cases require diagnostic investigation against spam policy criteria.

3.2 What Distinguishes Spam from Low Quality

Quality issues (low E-E-A-T, weak HCS) are matters of degree — content can be more or less helpful, more or less authoritative. Spam violations are matters of category — content either is or isn't keyword stuffed, scraped, cloaked. Spam policies define bright lines.

The practical implication: improving quality moves rankings up gradually. Eliminating spam violations may unlock sudden ranking restoration once Google's systems re-evaluate the site post-remediation.

3.3 The 2024 Policy Expansions

In March 2024, Google added three new spam policies that have driven substantial enforcement activity:

Scaled Content Abuse — Producing pages at scale primarily for ranking purposes, regardless of whether AI, human, or mixed authorship. Replaced the older "automatically generated content" policy with a broader definition focused on intent and pattern rather than method.

Site Reputation Abuse — Third parties publishing content on a host site primarily to leverage that site's ranking signals. Common pattern: established media sites leasing subdomains or subfolders to coupon, casino, or supplement marketers.

Expired Domain Abuse — Repurposing expired domains with prior authority to host content unrelated to the prior purpose, primarily for ranking benefit from inherited trust signals.

These three policies represent the largest spam policy expansion in years and continue to drive significant enforcement through 2026.

3.4 What Spam Policies Don't Cover

Spam policies don't cover:

Quality issues — addressed via core updates and HCS, not spam policies
Mistakes or accidents — Google distinguishes between intentional manipulation and good-faith errors
Personal preference disagreements — practices Google might not love but doesn't classify as spam
Legal compliance issues — copyright, defamation, etc. are addressed through other mechanisms

When something isn't a spam policy violation, addressing it requires the relevant quality framework.

4. Documented Spam Policies — Comprehensive Reference

This section catalogs every documented spam policy, what it covers, detection patterns, and avoidance requirements.

4.1 Cloaking

What it is: Presenting different content to search engine crawlers than to human users.

Common patterns:

User-agent detection serving different HTML to Googlebot vs browsers
IP-based content swapping
JavaScript that hides content from users that Googlebot sees as text
Reverse cloaking — keyword-stuffed text visible to bots, "cleaner" version to users
Geographic cloaking serving different content based on visitor location for ranking manipulation

Detection:

Google fetches with browser-like user agents and compares
Googlebot also runs in different network locations
Discrepancies between rendered DOM and HTML sent to crawlers flagged

Avoidance requirements:

Serve identical content to all visitors (with legitimate exceptions for personalization, A/B testing through proper Google-supported methods, paywall/login walls properly declared)
If using A/B testing, use Google's recommended approach (canonical to original, no rel=canonical pointing to test variant)
Personalization based on user signals must not differ for Googlebot in ways that would change ranking signals
Geographic content variations must use proper hreflang
Verify with Google's URL Inspection Tool — what Googlebot sees should match what users see

Code pattern (anti-cloaking):

<!-- Same HTML for all visitors -->
<!-- Personalization happens client-side AFTER initial render -->
<!-- Or via Google-recognized signals like cookies, not user-agent -->

4.2 Doorway Pages

What it is: Pages created primarily to rank for specific queries that funnel users to a different destination of less direct utility.

Common patterns:

Multiple landing pages for slight variations of the same query (e.g., "cheap car rental Austin," "affordable car rental Austin," "low cost car rental Austin" all leading to same booking page)
Geographic doorway pages with thin city-specific content but identical service offering
Pages that exist solely to rank, then redirect or funnel users elsewhere
Templated pages with minor keyword variations across each instance

Distinction from legitimate location pages: A genuine local landing page provides location-specific information (local team, local hours, local context, local testimonials). A doorway page just swaps the city name in templated content.

Detection:

Pattern recognition across page templates
Bounce-and-redirect behavior monitoring
Lack of unique value per page in a series

Avoidance requirements:

Each page must offer substantive unique value beyond keyword targeting
Location-specific pages must include genuinely location-specific content
Don't create variations targeting query stems that resolve to the same intent
Consolidate query variations into single comprehensive pages

Programmatic SEO consideration: Programmatic city pages (such as those covering 4,715 city/service combinations) are not automatically doorway pages. They're doorway pages when they're thin and offer no location-specific value. They're legitimate when each page offers genuinely useful location-specific information — local team contact, local pricing variations, local case studies, local testimonials, local regulatory considerations, etc.

4.3 Hacked Content

What it is: Content placed on a site without permission, typically through security vulnerabilities, that's used for spam, phishing, or malware distribution.

Common patterns:

Injected pages selling unrelated products (pharmaceuticals, gambling)
Hidden content (cloaked) only visible to search engines
Redirected pages sending users to malicious destinations
Modified existing pages with injected spam content
Created admin accounts using compromised credentials

Detection:

Google security systems flag known hack patterns
Search Console issues "Hacked" warning
Sudden appearance of pages on unfamiliar topics
Server logs show unusual activity

Avoidance requirements:

Keep all software (CMS, plugins, themes, server stack) current
Use 2FA on all admin accounts
Strong unique passwords (password manager)
Limit admin account count
Regular security scanning (Wordfence, Sucuri, Patchstack for WordPress; equivalent for other stacks)
Web Application Firewall (Cloudflare, Sucuri, Wordfence)
File integrity monitoring
Intrusion detection on server level
Off-site backups for rapid recovery

Response if hacked: See Section 10.5.

4.4 Hidden Text and Links

What it is: Text or links placed in a way that human users can't see but search engines can read.

Common patterns:

White text on white background
Text positioned off-screen (text-indent: -9999px)
Text behind images
Tiny font sizes (1px font, 0px line-height)
Display:none or visibility:hidden on text containing keywords
Hiding text with CSS that's recoverable by crawlers
Links in characters like commas or single periods
1×1 pixel images linking to other sites

Detection:

Google rendering identifies hidden content
Comparison of rendered vs HTML content reveals hidden elements
Pattern recognition on common hiding techniques

Avoidance requirements:

All text on the page should be visible to users
Don't use CSS to hide content for ranking purposes
Legitimate cases where content is hidden until user interaction (accordions, tabs, collapsible sections) are acceptable but content should still be visible/accessible upon interaction
Modal/popup content acceptable when triggered by user action
Skip-to-content links acceptable if standard accessibility pattern

Code pattern (legitimate progressive disclosure):

<details>
  <summary>Click to expand</summary>
  <p>Content visible after click. This is acceptable — user can access.</p>
</details>

Code pattern (spam):

<style>.hidden { display: none; }</style>
<div class="hidden">
  Keyword stuffed text invisible to users but indexed by search engines.
</div>

4.5 Keyword Stuffing

What it is: Loading pages with keywords or numbers in attempts to manipulate ranking, especially when it harms user experience.

Common patterns:

Lists of phone numbers without substantive value
Blocks of text listing cities or regions where the page wants to appear
Repeating same words or phrases unnaturally
Hidden keyword lists in meta tags or alt text
Stuffing alt attributes with keyword variations rather than describing images
Awkward sentences padded with keyword variations

Detection:

Keyword density relative to surrounding context
Unnatural phrasing patterns
Disproportionate keyword frequency
Patterns that match known stuffing approaches

Avoidance requirements:

Use keywords naturally in service of communication
Alt attributes describe images, don't list keywords
Meta descriptions describe content, don't pack keywords
Don't list cities/regions/services as plain text blocks
Vary language naturally; let topic-relevant terms appear organically
Write for humans first; if it reads awkwardly, it's stuffed

Word count consideration: Stuffing is about pattern, not absolute frequency. A long article on a specific topic will naturally include the topic term frequently — that's fine. A short article repeating the same phrase 30 times is stuffing.

4.6 Link Schemes

What it is: Links intended to manipulate ranking that aren't editorial in nature.

Common patterns:

Buying or selling links for ranking:

Purchasing dofollow links
Selling dofollow links
Trading goods or services for links
Sending free products in exchange for links without rel="sponsored"

Excessive link exchanges:

"Link to us, we'll link to you" reciprocal arrangements
Triangular link schemes (A→B→C→A)
Link exchange directories purpose-built for SEO

Large-scale article marketing or guest posting with optimized anchor text:

Guest posts where the primary purpose is dropping a link
Optimized anchor text in guest content
Single-author guest posting on dozens of sites
Guest posts with author bios containing manipulated anchor text

Automated link building:

Using software to create links across forums, blog comments, profiles
Paid services that generate links at scale
Link injection through hacked sites

Forum signatures and comments with optimized anchor text:

Strategic forum participation primarily for link drops
Blog comment links with money-anchor text

PBNs (Private Blog Networks):

Network of sites primarily existing to link to a money site
Often built on expired domains
Often interlinked in patterns that reveal coordination

Detection:

Backlink profile analysis showing unnatural patterns
Anchor text distribution analysis
Velocity analysis (sudden link spikes)
Link source quality signals
Pattern matching against known PBN footprints

Avoidance requirements:

Earn links through valuable content, not solicitation
Mark sponsored/paid links with rel="sponsored"
Mark guest post author bio links with rel="ugc" or rel="nofollow" if unrelated to content
Never participate in link exchanges for SEO purposes
Never purchase links for ranking
Never use link building services that promise dofollow links at volume

If unnatural inbound links are discovered:

Disavow via Google's Disavow Tool
Document disavow file in Search Console
File reconsideration request if manual action issued

4.7 Machine-Generated Traffic

What it is: Automated queries or bot traffic to Google or to a site that doesn't reflect real user behavior.

Common patterns:

Sending automated queries to Google (rank checking at high volume)
Bot-driven traffic to a site to manipulate engagement signals
Click manipulation services purchasing bot clicks on search results

Detection:

Pattern analysis of query and click behavior
Unusual session patterns
Click-through patterns not matching organic behavior

Avoidance requirements:

Use Google's official APIs for any automated query needs
Don't use rank-tracking services that send unauthorized queries to Google (most reputable services use their own indexes)
Never use traffic generation services
Never use click-bot services

4.8 Malware and Malicious Behaviors

What it is: Software that harms users — viruses, trojans, ransomware, unwanted software, drive-by downloads.

Common patterns:

Direct malware distribution
Misleading downloads (claiming to be one thing, actually another)
Software that modifies browser settings without consent
Drive-by downloads triggered by visiting a page
Sites distributing pirated software with bundled malware

Detection:

Google Safe Browsing scans
Detected malware triggers Search Console alerts and search result warnings

Avoidance requirements:

All downloads must accurately describe what's being downloaded
No bundled software users haven't consented to
No browser modification scripts
Maintain site security to prevent malware injection
Verify all third-party scripts and ads

4.9 Misleading Functionality

What it is: Sites that don't work as advertised — fake login forms, fake software, fake services.

Common patterns:

Pretending to be a brand the site isn't (phishing)
Promising functionality the site doesn't deliver
Fake "free PDF generator" or similar tools that don't work
Bait-and-switch products or services

Avoidance requirements:

Sites must accurately represent themselves and their function
Promised features must work
Brand impersonation prohibited
Deceptive product descriptions prohibited

4.10 Scaled Content Abuse (Added March 2024)

What it is: Producing many pages whose primary purpose is search ranking manipulation rather than helping users — regardless of whether the content was created by AI, humans, or both.

This is one of the most actively enforced policies in 2025-2026.

Common patterns:

AI-generated articles published at high volume with minimal review
Content farms producing hundreds or thousands of articles per month
Spinning existing content into many variations
Programmatic page generation without genuine per-page value
Templated content with minor variations to target keyword variations
"AI in, content out" workflows with no editorial layer

Critical clarification: AI use isn't automatically scaled content abuse. The violation is scale + low value + ranking primary purpose. AI can be used responsibly as a research and drafting assistant for content that adds genuine value. AI cannot be used to mass-produce content that exists primarily to occupy SERP space.

Detection:

Pattern recognition across publication volume
Content originality and value analysis
Engagement signals indicating low user satisfaction
Linguistic patterns common to AI generation when not edited
Site-wide content quality distribution
Rate of publication relative to organizational capacity

The December 2024 core update specifically targeted scaled content abuse patterns. Many content farms saw 40-80% organic traffic loss. The pattern continues — sites publishing high-volume AI content with minimal review face increasing risk through 2026.

Avoidance requirements:

Publication volume should be proportional to genuine editorial capacity
Every published article must add genuine value beyond what's already available
AI-assisted content requires meaningful human review and editing
Establish editorial review process: research → AI-assisted draft → expert revision → fact-check → publish
Disclose AI use per E-E-A-T framework Section 4.4.6
Maintain author accountability — real bylines, real responsibility for accuracy
Apply Information Gain principles per framework-infogain.md — every article must contribute novelty
Apply HCS principles per framework-hcs.md — content for users, not for search

Quantitative guideline: There's no fixed "publish less than X articles per month" rule. The relevant ratio is editorial capacity to publication volume. A team of 1 reviewing 5 AI-assisted articles per month is reasonable. A team of 1 publishing 100 AI articles per month is not. A team of 20 with rigorous editorial workflow can publish more without violation. Google's systems evaluate the quality outcome, not the input method.

4.11 Site Reputation Abuse (Added March 2024)

What it is: Third-party content published on a host site primarily to take advantage of the host's existing ranking signals, where the third-party content has little oversight from the host site.

Common patterns:

Parasite SEO arrangements:

Major news sites hosting "coupon code" subdirectories run by third parties
Established sites leasing subdomains to gambling, crypto, supplement marketers
Educational sites carrying commercial review sections operated by external SEO firms
Government or non-profit sites hosting commercial content for revenue

Common host targets:

News publications with high domain authority
Educational institutions (.edu)
Government sites (.gov)
Long-established commercial sites with strong ranking signals
Wikipedia-adjacent properties

The May 2024 spam update aggressively enforced this policy. Many high-profile examples of parasite SEO arrangements were de-ranked. Enforcement continues actively through 2026.

Detection:

Subdomain or subfolder content disconnected from main site purpose
Content quality and topic mismatch with host site
Editorial oversight gaps (different bylines, different editorial standards, different design patterns)
Pattern of similar parasite arrangements across multiple host sites

Avoidance requirements:

For host sites:

Don't lease subdomains or subfolders to third parties for content unrelated to your site's purpose
All content under your domain should be editorially controlled by your organization
If accepting sponsored content, treat as such with proper disclosure (rel="sponsored")
Affiliate content should be created under your editorial standards
Brand partnerships should be clearly disclosed and editorially vetted
Coupon/deals sections, if present, should be operated under main editorial oversight

For sites attempting to use parasite SEO:

Don't. The strategy is documented and enforced.
Build authority on your own domain
Use legitimate guest contribution to other sites with rel="sponsored" or rel="ugc" where appropriate

Edge cases:

Press releases distributed via wire services: Acceptable when properly attributed and not optimized solely for ranking
Job listings, classified ads: Acceptable when relevant to host site purpose
Forum content from real community members: Acceptable with moderation
Guest articles: Acceptable when editorially vetted and contributing genuine value
Affiliate review sections: Risk depends on editorial control — content created and vetted by host editorial team is acceptable; content provided by affiliate partners and published with minimal review is parasite SEO

Specific test for site reputation abuse:

Is the content created by the host site's editorial team? If yes, not parasite SEO.
Is the content created externally but rigorously edited by the host's team to its standards? Probably acceptable.
Is the content created externally and published with minimal host editorial involvement, primarily for ranking benefit? Likely site reputation abuse.

4.12 Expired Domain Abuse (Added March 2024)

What it is: Acquiring expired domains with prior authority and repurposing them with content unrelated to the prior site's purpose, primarily to leverage inherited ranking signals.

Common patterns:

Buying expired domain previously used by a non-profit, repurposing for commercial content
Buying expired domain previously a small business site, repurposing as a content site on unrelated topic
Acquiring multiple expired domains to build PBN
Building content sites on expired domains that have nothing to do with original purpose

Detection:

Wayback Machine analysis showing dramatic content shifts
Backlink profile inconsistency with current site purpose
Patterns matching known expired domain reseller markets
Sudden ranking improvements without commensurate content quality

Avoidance requirements:

If acquiring an expired domain:

Continue the original site's purpose if at all possible
If different purpose, build genuinely from scratch and don't expect inherited ranking benefits
Submit reconsideration request if needed clarifying domain purpose change
Be prepared for ranking signals to be re-evaluated post-acquisition

If domain history is unclear:

Wayback Machine review reveals prior content
Major content shifts justify Google's re-evaluation
Disavow inherited backlinks if they're spammy
Build new authority from current activity

Best practice: Build on new domains for new businesses. The "buying an aged domain for SEO benefit" strategy is now actively penalized. The domain age signal that this strategy targeted has been re-weighted to require continuity of purpose.

4.13 Scraped Content

What it is: Content republished from other sources without adding meaningful value.

Common patterns:

Auto-generated scraping of RSS feeds republished as own content
Content "spinning" — taking original content and using software to substitute synonyms
Republishing other sites' content with minor modifications
Aggregator pages with snippets but no substantial value add
Content "rewriting" services that produce technically-different but substantively-identical content

Distinction from legitimate aggregation: Aggregation that adds substantial value (curation, expert commentary, synthesis) is acceptable. Aggregation that adds nothing beyond republishing is scraping.

Detection:

Content similarity matching against original sources
Pattern recognition on spinning techniques
Originality analysis

Avoidance requirements:

All content should be substantively original to the publishing site
Quotes and excerpts permitted with attribution
Curated lists permitted with substantial original commentary
Syndication agreements permitted when properly canonicalized to original
Synthesis across sources permitted when synthesis itself is the contribution

4.14 Sneaky Redirects

What it is: Redirects that send users to a different destination than they expected.

Common patterns:

User clicks search result expecting one type of content, redirected to commercial offer
Mobile users redirected to different content than desktop users expecting the same page
Redirects from one search result to entirely unrelated destination
JavaScript redirects that mask the destination
Conditional redirects based on referrer (only redirect when from Google)

Detection:

Mobile vs desktop content comparison
User-experience signals (bounce rate, behavior)
Crawl path analysis

Avoidance requirements:

Redirects must lead to content matching what the search snippet promised
Mobile and desktop should reach equivalent content for the same URL
Use 301/302 redirects appropriately, not JavaScript redirects to mask destinations
Don't redirect users based on referrer for ranking manipulation

4.15 Spammy Automatically-Generated Content

What it is: Content produced by automated systems primarily for ranking, without value to users. Largely subsumed by the broader Scaled Content Abuse policy.

Common patterns:

Markov chain generated text
Translated text without human review
Automatically combined content from multiple sources
Automatically-created content stitching together database content with templates

Note: This older policy has been broadened into Scaled Content Abuse (Section 4.10). The narrow technical definition of "automatically generated" is now less relevant than the broader "content created at scale primarily for ranking." Same defensive patterns apply.

4.16 Thin Affiliate Pages

What it is: Affiliate marketing pages with little original content beyond the affiliate offers.

Common patterns:

Product review pages that just describe what the product's manufacturer says
Comparison pages with no actual testing or evaluation
"Top 10" lists ranked by affiliate commission rather than user benefit
Pages with no value beyond the affiliate links

Distinction from legitimate affiliate content: Affiliate marketing isn't prohibited. Thin affiliate content is. The standard: would this page be valuable even without the affiliate links? If not, it's thin.

Avoidance requirements:

Affiliate content must add substantial value beyond the affiliate program
Real product testing or experience documented
Evaluation criteria honest and useful
Recommendations based on user benefit, not commission rate
Affiliate disclosure prominent (FTC requirement and quality signal)
Use rel="sponsored" on affiliate links

4.17 User-Generated Spam

What it is: Spam content posted by third parties on a site, often through comments, forums, or open user-content systems.

Common patterns:

Comment spam with promotional links
Profile pages created solely to host links
Forum signatures with money-anchor links
Review spam (fake reviews, paid reviews)
Marketplace listings designed for SEO rather than genuine commerce

Detection:

Pattern recognition on common spam content
Volume and velocity of UGC posting
Author signal analysis

Avoidance requirements:

For sites with UGC:

Implement moderation (pre-publication ideally, post-publication minimum)
Require account creation with verification
Use rel="ugc" on links from user-generated content
Implement spam filters (Akismet for WordPress, etc.)
Manual review of high-volume posters
Remove spam content promptly when discovered
Don't allow comments to remain on old posts indefinitely if not moderated
Consider closing comments on older posts if moderation isn't sustainable

If site is hit by user-generated spam manual action:

Audit all UGC for spam patterns
Remove confirmed spam
Strengthen moderation processes
File reconsideration request demonstrating remediation

5. Special Focus: The Three Policies Added March 2024

The three new spam policies introduced in March 2024 represent the most active enforcement areas in 2025-2026. Most penalties issued through this period fall into one of these three categories.

5.1 Scaled Content Abuse — Defensive Implementation

Audit current state:

# Scaled content abuse audit
publication_volume_per_month: 0
authors_per_published_article_average: 0
review_time_per_article_hours: 0
ai_assisted_articles_per_month: 0
ai_unassisted_articles_per_month: 0
content_outsourcing_volume: 0

# Honesty check
publishing_at_capacity: false  # Are we publishing more than we can genuinely review?
each_article_adds_genuine_value: false  # Honest answer
review_process_is_substantive: false  # Honest answer

Risk assessment:

Pattern	Risk Level
<10 articles/month, expert authors, comprehensive review	Very Low
10-50/month, mix of human and AI-assisted, full editorial review	Low
50-200/month, primarily AI-assisted, light editorial review	Medium-High
>200/month, primarily AI-generated, minimal review	Critical
>50/month, single editor reviewing all, no expert input	High

Defensive structural patterns:

Editorial capacity matched to volume: If team can rigorously review N articles per month, publication volume should not exceed N (with margin)
Documented editorial process: Research → Outline → Draft (AI-assisted or not) → Expert review → Fact-check → Edit → Publish
Author accountability: Real bylines, real Person schema with credentials, real responsibility for accuracy
Per-article value gating: Pre-publish check requiring articulation of what the article adds (Information Gain framework)
AI use disclosure: Site-wide policy + per-article disclosure when applicable
Quality monitoring: Track engagement metrics; remove or significantly improve underperforming content
Topical focus discipline: Don't publish on topics outside genuine site authority

If currently exceeding safe patterns:

Stop publishing AI content immediately until audit complete
Audit existing AI content — identify articles with insufficient value
Remove or significantly improve identified articles
Restructure publication cadence to match genuine editorial capacity
Document new process for any reconsideration needs

5.2 Site Reputation Abuse — Defensive Implementation

Audit current state:

# Site reputation abuse audit
hosts_third_party_subdomain_content: false
subdomain_third_parties: []  # List with editorial control level

hosts_third_party_subfolder_content: false
subfolder_third_parties: []  # List with editorial control level

allows_external_publishing_arrangements: false
external_arrangement_details: []  # Description and editorial control level

editorial_control_over_all_subdomains: ""  # "full", "partial", "none"
editorial_control_over_all_subfolders: ""

Acceptable arrangements:

Sponsored content: Clearly disclosed, rel="sponsored", produced or rigorously vetted by host editorial
Guest contributions: Vetted by host editorial team, fits topical focus
Affiliate partnerships: Content created by host team, with affiliate links properly disclosed
Coupon/deals: Operated by host team or under direct host editorial supervision
Press releases: Through proper PR/wire mechanisms with proper attribution
Job listings: Relevant to host site purpose, properly structured

Unacceptable arrangements:

Subdomain leased to third party for content unrelated to host purpose
Subfolder where third party publishes with minimal host editorial involvement
Coupon section run entirely by external SEO agency
Casino/gambling content on educational or news sites
Supplement marketing on health information sites
Any "we'll pay you to host our content" arrangement

Defensive structural patterns:

All content under main domain editorially controlled by main organization
Subdomains used for legitimate technical separation (status.example.com, blog.example.com when run by same team) not for third-party content
Editorial standards applied uniformly across all site content
Sponsored content distinctly marked with rel="sponsored" and visible disclosure
Third-party content prohibited unless rigorously vetted

If currently has parasite SEO arrangement:

Terminate the arrangement — no remediation works while it's active
Remove or migrate the third-party content off the host domain
301 redirect to third party's own domain if appropriate (with proper communication)
Document termination for any reconsideration request
Audit broader site for similar patterns

5.3 Expired Domain Abuse — Defensive Implementation

Audit current state:

# Expired domain abuse audit
domain_acquired_from_someone_else: false
acquisition_date: ""
prior_owner_known: ""
prior_site_purpose: ""

current_site_purpose: ""
purpose_continuity_with_prior: ""  # "same", "related", "unrelated", "completely_different"

wayback_machine_review_completed: false
inherited_backlinks_audited: false
problematic_inherited_backlinks_disavowed: false

Risk assessment:

Pattern	Risk Level
Domain registered from scratch, never previously used	None
Acquired domain, continuing original purpose	Low
Acquired domain, related but evolved purpose	Medium
Acquired domain, completely different purpose	High
Multiple acquired domains in same network	Critical
Acquired domain with documented prior ranking, repurposed	High

Defensive structural patterns:

For new businesses, use new domains — don't acquire aged domains for SEO benefit
For business name acquisitions, focus on the brand value not the SEO equity
If acquiring expired domain, evaluate continuity carefully — substantial purpose continuity is the safe path
If purpose changes substantially, treat as new domain — don't expect inherited ranking benefits
Audit inherited backlink profile — disavow toxic backlinks immediately
Wayback Machine review — document the prior site for context

If domain has expired domain abuse risk:

Wayback Machine audit — what was the prior content?
Backlink audit — what does the inherited link profile look like?
Disavow toxic backlinks through Google Search Console
Make domain change explicit — About page acknowledges the change with substantive purpose explanation
Build current authority through current work — don't rely on inherited signals
Be prepared for slow ranking initially — Google will re-evaluate

6. Defensive Site Architecture

Beyond avoiding specific violations, structural patterns reduce risk of accidental violations.

6.1 Content Publishing Workflow

A workflow that prevents scaled content abuse and thin content:

Topic identification
  → "Why are we covering this?" gate
  → "What can we contribute?" gate (Information Gain)
  → If yes to both, proceed

Research
  → Primary sources gathered
  → Subject matter expert input

Drafting
  → AI-assisted or human-written (either acceptable)
  → Draft completed by named author

Expert review
  → Subject matter expert reviews accuracy
  → Reviewer takes professional responsibility
  → Reviewer signs off with name and credentials

Fact-checking
  → Every factual claim verified against primary source
  → Citations verified to actually support claims
  → Statistics double-checked

Editorial review
  → Quality assessment
  → Information Gain confirmation
  → Style and tone

Pre-publication check
  → Author byline with credentials present
  → Reviewer credit if YMYL
  → Disclosures present (AI use, affiliate, sponsored)
  → Schema valid
  → Internal links appropriate
  → Original imagery

Publication
  → Real bylines with author accountability
  → AI use disclosed if applicable
  → Refresh schedule set

6.2 Link Acquisition Policy

# {{BUSINESS_NAME}} Link Acquisition Policy

## What We Do

- Earn links through valuable content
- Cite primary sources in our content (creating natural inbound interest)
- Participate in industry communities authentically
- Build relationships with relevant publications

## What We Don't Do

- Buy or sell links for ranking purposes
- Participate in link exchange schemes
- Use link building services that promise volume
- Stuff guest post bylines with optimized anchor text
- Manipulate forum signatures or comment links
- Operate or participate in PBNs

## Sponsored Content

- Sponsored relationships disclosed with rel="sponsored"
- Sponsored content visibly marked
- Editorial integrity maintained

## Affiliate Links

- All affiliate links use rel="sponsored"
- Affiliate disclosure present on all affiliate content
- Affiliate recommendations based on user benefit, not commission

## When We Discover Toxic Inbound Links

- Document via backlink audit
- Disavow through Google Search Console
- Update Disavow file as needed

6.3 Third-Party Content Review Process

If the site allows any external content:

# Third-Party Content Review Process

## What We Accept

- Guest contributions from credentialed experts on our topical focus areas
- Sponsored content clearly identified as such
- User-generated content through approved channels

## What We Don't Accept

- Subdomain or subfolder leasing
- Content from external SEO agencies
- Content disconnected from our editorial focus
- Content with manipulated anchor text

## Vetting Process

1. Author/contributor identity verified
2. Content topic fits our editorial focus
3. Quality matches our standards
4. Editorial review by our team
5. Fact-checking through our process
6. Disclosure requirements met
7. Schema and metadata applied per our standards

6.4 AI Content Policy

# {{BUSINESS_NAME}} AI Content Policy

## How We Use AI

- Research assistance and source gathering
- First-draft generation reviewed by humans
- Grammar and style editing
- Outline and structure assistance

## How We Don't Use AI

- Mass-producing articles for SEO
- Publishing AI content without expert review
- Generating fabricated quotes, statistics, or experiences
- Replacing the need for genuine subject matter expertise

## Editorial Standards for AI-Assisted Content

- Every AI-assisted article reviewed by named subject matter expert
- Reviewer takes professional responsibility
- All factual claims verified against primary sources
- AI use disclosed per article when applicable
- Same quality bar as human-written content

## Volume Discipline

- Publication volume matches editorial capacity
- We don't publish more than we can rigorously review
- Quality over quantity is the principle

6.5 Security Posture

Documented at /admin/security-posture.md:

# Security Posture

## Current Configuration
- 2FA enabled on all admin accounts
- Strong unique passwords (password manager required)
- Limited admin account count
- Web Application Firewall active (Cloudflare)
- File integrity monitoring (Wordfence/equivalent)
- Daily off-site backups
- Quarterly security audit

## Monitoring
- Search Console for "Hacked" warnings
- Server logs reviewed weekly for unusual activity
- Malware scanning weekly
- SSL certificate expiration monitoring

## Incident Response
- Hacked content discovered → Section 10.5 protocol
- Credential compromise → password rotation across all accounts
- Successful intrusion → forensic analysis required before remediation

7. Red Flags and Early Warning Signs

Patterns that suggest spam policy violation risk before formal penalty.

7.1 Content Red Flags

Publication volume increasing without staffing increase
AI content disclosure conversations being avoided
Pressure to publish "just to have content" on topics
Articles published that the team hasn't read in full
Topical drift into areas outside genuine expertise
Word count targets driving content padding
Refresh dates being updated without content updates

7.2 Linking Red Flags

Sudden inbound link velocity increases
Inbound links from sites with unrelated topics
Inbound links with optimized anchor text patterns
Outbound link targets the team can't explain
"Link building" budget line items
Email outreach offers for "guaranteed dofollow links"

7.3 Architecture Red Flags

Subdomain or subfolder activity not familiar to main team
Pages indexed that the team didn't create
Geographic content variations beyond legitimate localization
Server log entries showing crawl patterns to unknown URLs
File system changes the team didn't make

7.4 Search Console Red Flags

Manual action notifications (immediate priority)
Security issue notifications
Sudden indexing decreases without explanation
Sudden indexing increases without explanation
"Hacked" warnings
Coverage report errors increasing

7.5 Traffic Pattern Red Flags

Sudden traffic loss without identified core update
Specific page sections losing traffic while others stable
Branded query traffic dropping (suggests manual action)
Sudden traffic gains that seem too good to be true (often precede manipulation detection)

8. Stack-Specific Spam Policy Considerations

8.1 WordPress

High-risk patterns:

Plugins generating content automatically
Themes with hidden links to plugin developer
Comment moderation off by default
Outdated plugins creating security vulnerabilities
"SEO" plugins that recommend stuffing keywords or hiding text

Defensive practices:

Akismet or similar comment spam filtering
Wordfence or equivalent security
Content publishing workflow plugins (Editorial Calendar, PublishPress)
Schema validation through Rank Math or Yoast
Regular plugin and theme updates

8.2 Programmatic SEO Sites (Next.js, custom)

High-risk patterns:

City pages or category pages with templated content lacking unique per-page value
Database-driven pages with insufficient editorial layer
Faceted navigation creating thousands of low-value URLs
Auto-generated pages from third-party data feeds

Defensive practices:

Per-page minimum content threshold enforced at build time
Per-page unique value validation
Robots.txt or noindex on pages below quality threshold
Editorial review of programmatic page templates
Genuinely location-specific or category-specific content per page

8.3 E-commerce Platforms (Shopify, WooCommerce, custom)

High-risk patterns:

Auto-generated product description from manufacturer feeds
Manufacturer review content republished without value-add
Faceted navigation creating duplicate content URLs
Affiliate review sites disguised as e-commerce
Fake or incentivized reviews

Defensive practices:

Original product descriptions per product (or properly canonicalized to manufacturer)
Genuine customer reviews with verification
Faceted URLs properly handled with canonicals or noindex
Clear distinction between affiliate and direct sales

8.4 News and Media Sites

High-risk patterns:

Coupon or deals subdirectories operated by third parties (parasite SEO risk)
Sponsored content not clearly marked
Aggregated wire content republished without value-add
AI-generated breaking news without verification
Programmatic local pages with thin content

Defensive practices:

All editorial sections under direct editorial control
Sponsored content clearly marked and disclosed
AI use restricted to editorial assistance, not authoritative content
Local journalism backed by genuine local presence

9. Cross-Reference to the 14-Tier Framework

Spam Policies compliance interacts with multiple tiers:

Tier 1 SSO — Site Security Optimization prevents hacked content
Tier 1 GCO — Google Compliance Optimization includes spam policies
Tier 2 OBL — Outbound Link strategies must follow link scheme policies
Tier 2 IBL — Inbound Link management must follow link scheme policies
Tier 3 LLMO — AI use must follow scaled content abuse policies
Tier 6 OCO — Original Content Optimization is the inverse of scraped/scaled abuse

Spam Policies compliance is a gate — sites failing here can't benefit from optimization in any other tier.

10. Detection, Response, and Recovery

10.1 Manual Action Detection

Check Search Console at Search Console > Security & Manual Actions > Manual actions weekly.

When a manual action appears:

Read the description carefully
Note whether it's site-wide or partial
Document the action type and date
Begin immediate investigation per Section 10.3

10.2 Algorithmic Spam Update Detection

Use the same protocol as core update detection (see framework-coreupdates.md Section 4):

Monitor SERP volatility trackers
Watch for Google announcements about spam updates
Compare site performance to industry signals
72-hour hold rule before reactive action

When a spam update appears to be active:

Audit site against spam policies (Sections 4-5)
Identify likely violation pattern
Begin remediation

10.3 Manual Action Response Protocol

When manual action received:

Day 1:

Read action description thoroughly
Identify what triggered it
Document current state for "before" reference
Begin remediation immediately

Days 1-7:

Comprehensive site audit per relevant Section 4 policy
Identify all violating content/patterns
Remediate or remove
Document every remediation action with dates

Days 7-14:

Verify remediation is complete
Audit for any missed instances
Strengthen processes to prevent recurrence
Prepare reconsideration request

Reconsideration request structure:

# Reconsideration Request — {{ACTION_TYPE}}

## Manual Action Details
- Action type: {{TYPE}}
- Notification date: {{DATE}}
- Affected pages/sections: {{SCOPE}}

## What Caused the Violation
{{HONEST_DESCRIPTION_OF_THE_PATTERN}}

## What We Have Done to Fix It
1. {{REMEDIATION_ACTION_1_WITH_DATE}}
2. {{REMEDIATION_ACTION_2_WITH_DATE}}
3. {{REMEDIATION_ACTION_3_WITH_DATE}}

## Evidence of Remediation
- {{EVIDENCE_TYPE_1}}: {{LINK_OR_DESCRIPTION}}
- {{EVIDENCE_TYPE_2}}: {{LINK_OR_DESCRIPTION}}

## Steps We Have Taken to Prevent Recurrence
1. {{PROCESS_CHANGE_1}}
2. {{PROCESS_CHANGE_2}}
3. {{POLICY_DOCUMENT_LINK}}

## Acknowledgment
We acknowledge the violation, understand why our prior practices violated Google's policies, and are committed to maintaining compliance going forward.

Submitted by: {{NAME}}
Date: {{DATE}}
Search Console verified property: {{DOMAIN}}

Submit through Search Console > Manual actions > Request a review.

Response timeline: Typically days to weeks. Sometimes longer for complex cases.

10.4 Reconsideration Request Best Practices

Be honest about the violation: Google's reviewers know what happened. Trying to deny or minimize is counterproductive.
Show specific remediation: Concrete actions with dates, not vague statements.
Demonstrate understanding: Show you understand why the practice was prohibited.
Provide evidence: Links to changed pages, screenshots of removed content, documentation of process changes.
Don't promise; demonstrate: "We have removed 247 articles" is better than "We will remove low-quality articles."
Address root cause: Process changes, not just symptom remediation.
Be patient: Multiple rounds of review possible. Don't keep filing requests during review periods.

10.5 Hacked Content Response Protocol

When hacked content is detected:

Hour 1:

Take site offline if compromise is severe (better than serving malware to users)
Document the compromise (screenshots, server log copies)
Notify hosting provider if applicable

Hours 1-24:

Forensic analysis — how did they get in?
Identify all compromised files and pages
Restore from clean backup if available (verified pre-compromise)
Apply security patches that addressed the vulnerability
Rotate all credentials (passwords, API keys, SSH keys)
Add 2FA to all admin accounts if not already
Review user accounts; remove unauthorized accounts

Days 1-7:

Comprehensive site scan for residual compromise
Submit hacked content notice in Search Console
Request review once cleaned
Strengthen security posture per Section 6.5

Long-term:

Document the incident
Review security practices
Implement monitoring to detect future compromises faster

10.6 Link Penalty Response

For unnatural links to your site:

Comprehensive backlink audit
Identify toxic links (spammy domains, manipulated anchor text, link farms)
Attempt outreach to remove (often unsuccessful at scale)
Disavow remaining toxic links via Google Search Console Disavow Tool
Document the disavow file for any reconsideration request
File reconsideration if manual action

For unnatural links from your site:

Audit all outbound links
Add rel="nofollow" or rel="sponsored" where appropriate
Remove links acquired through link schemes
Document remediation
File reconsideration

11. Audit Mode

11.1 Comprehensive Spam Policy Audit

Score the site against every documented policy:

#	Policy Area	Pass/Fail	Notes
SP1	Cloaking
SP2	Doorway Pages
SP3	Hacked Content
SP4	Hidden Text and Links
SP5	Keyword Stuffing
SP6	Link Schemes (inbound)
SP7	Link Schemes (outbound)
SP8	Machine-Generated Traffic
SP9	Malware and Malicious Behaviors
SP10	Misleading Functionality
SP11	Scaled Content Abuse
SP12	Site Reputation Abuse
SP13	Expired Domain Abuse
SP14	Scraped Content
SP15	Sneaky Redirects
SP16	Spammy Auto-Generated Content
SP17	Thin Affiliate Pages
SP18	User-Generated Spam

Score: 18 policies. World-class compliance: 18/18 with zero risks identified.

A site failing any single policy is at substantial risk regardless of other strengths.

11.2 Defensive Infrastructure Audit

#	Criterion	Pass/Fail
DI1	Content publishing workflow documented and enforced
DI2	Link acquisition policy documented
DI3	Third-party content review process exists if applicable
DI4	AI content policy documented
DI5	Security posture documented and current
DI6	Quarterly spam audit performed
DI7	Backlink profile audited within last 6 months
DI8	UGC moderation active if applicable
DI9	Editorial capacity matched to publication volume
DI10	Author accountability infrastructure in place

Score: 10. World-class: 10/10.

12. Maintenance Schedule

12.1 Daily

Monitor Search Console for new manual actions
Watch for security warnings
Spam alert monitoring on user-generated content

12.2 Weekly

Review server logs for unusual patterns
Check for new comment spam or UGC spam
Monitor SERP volatility for spam update signals

12.3 Monthly

Backlink profile review for unnatural patterns
Sample content audit for scaled content patterns
Outbound link audit
Disavow file review

12.4 Quarterly

Full spam policy compliance audit
Security audit
Defensive infrastructure audit
Process documentation review and refresh

12.5 Annually

Comprehensive review against current spam policies (policies evolve)
Strategic compliance posture assessment
Update internal policies for any changes
Reconsideration request review for sites with manual action history

13. Common Mistakes & Anti-Patterns

13.1 Treating Spam Policies as Optional

Anti-pattern: Following SEO advice that violates spam policies because "everyone does it."

Why it fails: Penalties happen. Recovery is hard. The "everyone does it" sites disappear regularly.

Fix: Treat spam policies as bright lines. Don't cross them regardless of competitive pressure.

13.2 AI Content Strategy Ignoring Scaled Content Abuse

Anti-pattern: "We can publish 100 AI articles per month for cheap." Mass production with minimal review.

Why it fails: Active enforcement target. Detection improving rapidly. Penalty severity high.

Fix: Editorial capacity matched to volume. Quality over quantity. Real review process.

13.3 "Renting" Authority Through Parasite SEO

Anti-pattern: Buying space on high-authority site to rank for commercial queries.

Why it fails: Site reputation abuse policy targets exactly this. Both host site and parasite content suffer.

Fix: Build authority on own domain. No parasite SEO arrangements.

13.4 Aged Domain Acquisitions for SEO

Anti-pattern: Buying expired domains with prior authority to skip the authority-building process.

Why it fails: Expired domain abuse policy. Re-evaluation removes the inherited authority.

Fix: Build on new domains. Earn authority through current work.

13.5 Programmatic SEO Without Per-Page Value

Anti-pattern: Generating thousands of city/category pages with templated content lacking unique value.

Why it fails: Doorway pages plus thin content. Multiple policy risks.

Fix: Programmatic pages must have genuine per-page value. Local content must be genuinely local.

13.6 Ignoring Manual Actions

Anti-pattern: Manual action received, ignored or addressed slowly.

Why it fails: Penalties compound. Reconsideration becomes harder over time.

Fix: Manual actions are top priority. Stop other work; address immediately.

13.7 Assuming Algorithmic Demotion Isn't Spam-Related

Anti-pattern: Traffic loss assumed to be core update; spam policy violation never investigated.

Why it fails: Misdiagnosis. Spam-policy-related demotion requires different remediation than core update response.

Fix: Check spam policies first when traffic loss occurs. Manual action notification doesn't always accompany algorithmic demotion.

13.8 Defensive Disavow Without Backlink Audit

Anti-pattern: Disavowing all backlinks indiscriminately "to be safe."

Why it fails: Disavowing legitimate authoritative links damages rankings.

Fix: Audit-driven disavow. Only disavow demonstrably toxic links.

13.9 No Quarterly Audit Cadence

Anti-pattern: Spam compliance treated as one-time setup, never revisited.

Why it fails: Sites drift. New violations creep in. Policies evolve.

Fix: Quarterly audits per Section 12.

13.10 Reconsideration Requests Without Real Remediation

Anti-pattern: Filing reconsideration request with vague claims and no concrete remediation.

Why it fails: Reviewers see this constantly. Request denied. Future requests get stricter scrutiny.

Fix: Concrete remediation, documented evidence, real process changes. Then file.

14. Implementation/Audit Report Templates

14.1 Spam Policy Implementation Report Template

# Spam Policies Framework Implementation Report

**Site**: {{BUSINESS_NAME}}
**Implementation Date**: {{TODAY}}

## Comprehensive Audit Results
{{TABLE_OF_18_POLICIES_WITH_FINDINGS}}

## Critical Issues Identified and Remediated
{{LIST}}

## Defensive Infrastructure Installed
- Content publishing workflow: {{STATUS}}
- Link acquisition policy: {{STATUS}}
- Third-party content process: {{STATUS}}
- AI content policy: {{STATUS}}
- Security posture documentation: {{STATUS}}

## Process Changes Implemented
{{LIST_WITH_DATES}}

## Items Requiring Ongoing Monitoring
{{LIST}}

## Sign-Off
Implementation complete: {{DATE}}
Implementer: {{NAME}}

14.2 Spam Policy Audit Report Template

# Spam Policies Audit Report

**Site**: {{BUSINESS_NAME}}
**Audit Date**: {{TODAY}}

## Executive Summary
{{ASSESSMENT}}

## Compliance Status
- Policies in compliance: {{X}}/18
- Critical violations identified: {{COUNT}}
- High-risk patterns identified: {{COUNT}}
- Defensive infrastructure score: {{X}}/10

## Per-Policy Findings
{{DETAILED_PER_POLICY_FINDINGS}}

## Critical Issues Requiring Immediate Action
{{LIST_WITH_REMEDIATION_PLANS}}

## Risk Patterns Identified
{{LIST}}

## Defensive Infrastructure Gaps
{{LIST}}

## Recommended Remediation Order
{{PRIORITIZED_LIST_WITH_TIMELINES}}

## Manual Action Status
{{NONE / ACTIVE_ACTION_TYPE / HISTORICAL_ACTIONS}}

## Sign-Off
Audit complete: {{DATE}}
Auditor: {{NAME}}

14.3 Manual Action Reconsideration Request Template

# Reconsideration Request — {{ACTION_TYPE}}

## Manual Action Acknowledgment

We received a manual action notification on {{DATE}} for {{ACTION_TYPE}}. We acknowledge the violation and have completed remediation.

## What Caused the Violation

{{HONEST_AND_SPECIFIC_DESCRIPTION_OF_WHAT_HAPPENED_INCLUDING_WHY_IT_HAPPENED}}

## Specific Remediation Actions

### {{REMEDIATION_AREA_1}}
- {{DATE}}: {{ACTION_TAKEN}}
- {{DATE}}: {{ACTION_TAKEN}}
- Evidence: {{LINK_OR_DESCRIPTION}}

### {{REMEDIATION_AREA_2}}
- {{DATE}}: {{ACTION_TAKEN}}
- Evidence: {{LINK_OR_DESCRIPTION}}

## Process Changes to Prevent Recurrence

1. {{NEW_POLICY_OR_PROCESS}}: {{LINK_TO_DOCUMENTED_POLICY}}
2. {{NEW_POLICY_OR_PROCESS}}: {{LINK_TO_DOCUMENTED_POLICY}}
3. {{NEW_POLICY_OR_PROCESS}}: {{LINK_TO_DOCUMENTED_POLICY}}

## Supporting Evidence

- {{EVIDENCE_DOC_1}}: {{LINK}}
- {{EVIDENCE_DOC_2}}: {{LINK}}
- {{EVIDENCE_DOC_3}}: {{LINK}}

## Commitment Going Forward

We understand why our prior practices violated Google's spam policies. We have implemented systematic changes to prevent recurrence. We are committed to maintaining policy compliance and serving users with high-quality content.

---
Submitted by: {{NAME}}
Title: {{TITLE}}
Date: {{DATE}}
Search Console verified property: {{DOMAIN}}
Contact: {{EMAIL}}

End of Framework Document

Document version: 1.0
Last updated: 2026-04-29
Maintained by: ThatDeveloperGuy

Spam policies are the defensive half of search visibility. The frameworks that focus on quality (E-E-A-T, HCS, YMYL, Information Gain) tell you how to earn rankings. This framework tells you how not to lose them. A site that scores perfectly on quality frameworks but violates spam policies will be penalized regardless. A site that maintains spam policy compliance but lacks quality won't rank well but won't be removed.

The 2024-2026 spam policy expansion — scaled content abuse, site reputation abuse, expired domain abuse — represents Google's most aggressive anti-manipulation enforcement in years. Sites that haven't audited against these new policies are at risk regardless of historical compliance. The work in this framework is defensive but essential.

Compliance is a continuous practice, not a one-time setup. Quarterly audits per Section 12 are the minimum. Sites with growth, new content patterns, new partnerships, or new authors require more frequent review. The cost of a penalty — both ranking damage and remediation work — is dramatically higher than the cost of compliance.

Companion documents in this library:

framework-eeat.md — Foundational E-E-A-T (the quality counterpart to spam policies)
framework-ymyl.md — Your Money or Your Life elevated standards
framework-hcs.md — Helpful Content System
framework-sqrg.md — Search Quality Rater Guidelines
framework-coreupdates.md — Google Core Updates
framework-infogain.md — Information Gain
framework-entitysalience.md — Entity Salience
framework-knowledgegraph.md — Knowledge Graph
framework-aicitations.md — AI Citations

About this framework library

Companion 14-tier Engine Optimization stack (each tier is its own article):

Need this framework implemented on your site? See the Engine Optimization service or hire through ThatDevPro contact.