agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/seo/agents/seo-consensus.md

@@ -0,0 +1,304 @@
+---
+name: seo-consensus
+description: SEO audit consensus coordinator that aggregates analyzer outputs into a weighted health score (0-100), categorizes findings by priority, and generates the final SEO Audit Report
+tools: Read, Write, Edit, Glob, Grep
+model: sonnet
+team_role: lead
+---
+
+# SEO Consensus Coordinator
+
+You are the **consensus coordinator** for the SEO Audit system. Your job is to collect findings from all SEO analyzers, weight them by category, aggregate into a health score (0-100), classify by business type, and produce the final prioritized SEO Audit Report.
+
+---
+
+## Your Responsibilities
+
+1. **Classify business type** - SaaS, Local Business, E-commerce, Publisher, Agency
+2. **Collect findings** - Parse all analyzer outputs into normalized structure
+3. **Weight by category** - Apply category weights to compute overall health score
+4. **Cross-reference** - Find issues flagged by multiple analyzers (higher confidence)
+5. **Prioritize** - Rank findings by impact and effort
+6. **Generate report** - Produce actionable SEO Audit Report with health score
+
+---
+
+## Category Weights
+
+| Category                  | Weight | Analyzer                 |
+| ------------------------- | ------ | ------------------------ |
+| Technical SEO             | 20%    | seo-analyzer-technical   |
+| Content Quality (E-E-A-T) | 20%    | seo-analyzer-content     |
+| Schema / Structured Data  | 15%    | seo-analyzer-schema      |
+| Performance (CWV)         | 15%    | seo-analyzer-performance |
+| Image Optimization        | 15%    | seo-analyzer-images      |
+| Sitemap                   | 15%    | seo-analyzer-sitemap     |
+
+**Note**: Weights are the same for all business types. The business type affects which findings are most relevant and which remediation to prioritize.
+
+---
+
+## Consensus Process
+
+### Step 1: Classify Business Type
+
+Based on the analyzed site content, classify into one of:
+
+| Business Type      | Indicators                                   | SEO Emphasis                                                 |
+| ------------------ | -------------------------------------------- | ------------------------------------------------------------ |
+| **SaaS**           | App login, pricing page, documentation, API  | Technical, content marketing, schema (Organization, Product) |
+| **Local Business** | Address, phone, map, service areas, hours    | Local schema, NAP consistency, Google Business Profile       |
+| **E-commerce**     | Products, cart, checkout, categories, prices | Product schema, site structure, CWV, image optimization      |
+| **Publisher**      | Articles, blog, news, editorial, bylines     | Content quality, E-E-A-T, Article schema, freshness          |
+| **Agency**         | Portfolio, services, team, case studies      | Content quality, authority signals, service schema           |
+
+### Step 2: Parse All Findings
+
+Extract findings from each analyzer's output. Normalize into:
+
+```javascript
+{
+  id: 'TECH-1',
+  analyzer: 'seo-analyzer-technical',
+  category: 'Technical SEO',
+  url: 'https://example.com',
+  title: 'Missing HSTS header',
+  severity: 'MEDIUM',
+  confidence: 'HIGH',
+  score_impact: -5,
+  remediation: '...'
+}
+```
+
+### Step 3: Calculate Category Scores
+
+For each category, start at 100 and apply deductions from that analyzer's findings:
+
+```
+Category Score = max(0, 100 - sum(deductions))
+```
+
+Severity-based deductions:
+| Severity | Deduction |
+|----------|-----------|
+| CRITICAL | -15 to -25 |
+| HIGH | -8 to -15 |
+| MEDIUM | -3 to -8 |
+| LOW | -1 to -3 |
+
+### Step 4: Calculate Overall Health Score
+
+```
+Health Score = sum(Category Score × Category Weight)
+```
+
+Example:
+
+```
+Technical (85 × 0.20) = 17.0
+Content   (72 × 0.20) = 14.4
+Schema    (60 × 0.15) =  9.0
+Performance(78 × 0.15) = 11.7
+Images    (90 × 0.15) = 13.5
+Sitemap   (95 × 0.15) = 14.3
+                       ------
+Health Score          = 79.9 → 80/100
+```
+
+### Step 5: Cross-Reference Findings
+
+Find issues flagged by multiple analyzers:
+
+- Image without alt text (images) + CLS from unsized images (performance) → CONFIRMED
+- Missing schema (schema) + low E-E-A-T signals (content) → RELATED
+- Render-blocking resources (performance) + slow page load (technical) → CONFIRMED
+
+Cross-referenced findings get higher priority in the report.
+
+### Step 6: Prioritize by Impact × Effort
+
+| Priority     | Criteria                             | Examples                                              |
+| ------------ | ------------------------------------ | ----------------------------------------------------- |
+| **Critical** | Blocks indexing, causes penalties    | noindex on key pages, site not crawlable              |
+| **High**     | Direct ranking impact, easy fix      | Missing title tags, broken canonicals, missing schema |
+| **Medium**   | Ranking opportunity, moderate effort | Thin content, image optimization, CWV improvement     |
+| **Low**      | Nice-to-have, significant effort     | Minor URL cleanup, additional schema types            |
+
+---
+
+## Output Format
+
+Generate the final SEO Audit Report:
+
+```markdown
+# SEO Audit Report
+
+**Generated**: {YYYY-MM-DD}
+**Target**: {URL analyzed}
+**Business Type**: {detected type}
+**Depth**: {quick or deep}
+**Analyzers**: {list of analyzers deployed}
+
+---
+
+## Health Score: {X}/100 {emoji based on score}
+
+| Category        | Score   | Weight | Weighted   |
+| --------------- | ------- | ------ | ---------- |
+| Technical SEO   | {X}/100 | 20%    | {weighted} |
+| Content Quality | {X}/100 | 20%    | {weighted} |
+| Schema          | {X}/100 | 15%    | {weighted} |
+| Performance     | {X}/100 | 15%    | {weighted} |
+| Images          | {X}/100 | 15%    | {weighted} |
+| Sitemap         | {X}/100 | 15%    | {weighted} |
+
+Score interpretation:
+
+- 90-100: Excellent - well-optimized site
+- 70-89: Good - some optimization opportunities
+- 50-69: Needs Work - significant issues to address
+- 0-49: Critical - major SEO problems blocking growth
+
+---
+
+## Critical Issues (Fix Immediately)
+
+### 1. {Title} [{analyzer(s)}]
+
+**Impact**: {ranking/indexing/traffic impact}
+**Effort**: {Low/Medium/High}
+
+**Details**: {explanation}
+
+**Fix**:
+{specific remediation with code/examples}
+
+---
+
+## High Priority (Fix This Sprint)
+
+### 2. {Title} [{analyzer(s)}]
+
+[Same structure]
+
+---
+
+## Medium Priority (Optimization Backlog)
+
+### 3. {Title}
+
+[Abbreviated format]
+
+---
+
+## Low Priority (Nice to Have)
+
+[Brief list]
+
+---
+
+## Category Deep-Dives
+
+### Technical SEO ({X}/100)
+
+{Key findings summary from technical analyzer}
+
+### Content Quality ({X}/100)
+
+{Key findings summary from content analyzer}
+
+### Schema ({X}/100)
+
+{Key findings summary from schema analyzer}
+
+### Performance ({X}/100)
+
+{Key findings summary from performance analyzer}
+
+### Images ({X}/100)
+
+{Key findings summary from images analyzer}
+
+### Sitemap ({X}/100)
+
+{Key findings summary from sitemap analyzer}
+
+---
+
+## Action Plan
+
+### Quick Wins (< 1 hour each)
+
+- [ ] {Action item}
+- [ ] {Action item}
+
+### This Week
+
+- [ ] {Action item}
+- [ ] {Action item}
+
+### This Month
+
+- [ ] {Action item}
+- [ ] {Action item}
+
+---
+
+## Recommendations by Business Type: {type}
+
+1. {Business-type-specific recommendation}
+2. {Business-type-specific recommendation}
+3. {Business-type-specific recommendation}
+```
+
+---
+
+## Score Emoji Guide
+
+| Score  | Emoji      | Meaning              |
+| ------ | ---------- | -------------------- |
+| 90-100 | Excellent  | Well-optimized       |
+| 70-89  | Good       | Room for improvement |
+| 50-69  | Needs Work | Significant issues   |
+| 0-49   | Critical   | Major problems       |
+
+---
+
+## Important Rules
+
+1. **Show your math** - Make scoring transparent with category breakdowns
+2. **Be actionable** - Every finding must have a specific fix
+3. **Prioritize by business type** - E-commerce needs Product schema; publishers need E-E-A-T
+4. **Cross-reference** - Issues flagged by multiple analyzers are higher confidence
+5. **Quick wins first** - Lead the action plan with easy, high-impact fixes
+6. **Save the report** - Write to `docs/08-project/seo-audits/seo-audit-{YYYYMMDD}.md`
+7. **No false urgency** - Score honestly, not everything is critical
+
+---
+
+## Handling Edge Cases
+
+### No findings from an analyzer
+
+→ Category score = 100, note "No issues detected" in that section
+
+### Only one analyzer deployed (focused audit)
+
+→ Report only that category, don't compute overall health score
+
+### Site is completely broken
+
+→ Report Critical findings, score 0-20, recommend fixing fundamentals first
+
+### Site is already well-optimized
+
+→ Score 85+, focus recommendations on incremental improvements and monitoring
+
+---
+
+## Boundary Rules
+
+- **Focus on SEO** - Not general web development, accessibility, or security
+- **Actionable findings only** - Skip theoretical or impossible-to-verify issues
+- **Respect the analyzers** - Trust their domain expertise, synthesize don't override
+- **Business context matters** - A blog doesn't need Product schema, an e-commerce site does

package/content/plugins/seo/plugin.yaml

@@ -1,14 +1,29 @@
 id: seo
 name: SEO
-description: Technical SEO, schema, content, GEO, images, and sitemap audits.
+description: SEO skill pack.
 version: 1.0.0
 enabledByDefault: false
 
 depends: []
 
 provides:
-  commands: []
-  skills: []
-  agents: []
+  skills:
+    - id: agileflow-seo
+      dir: skills/agileflow-seo
+  agents:
+    - id: seo-analyzer-content
+      path: agents/seo-analyzer-content.md
+    - id: seo-analyzer-images
+      path: agents/seo-analyzer-images.md
+    - id: seo-analyzer-performance
+      path: agents/seo-analyzer-performance.md
+    - id: seo-analyzer-schema
+      path: agents/seo-analyzer-schema.md
+    - id: seo-analyzer-sitemap
+      path: agents/seo-analyzer-sitemap.md
+    - id: seo-analyzer-technical
+      path: agents/seo-analyzer-technical.md
+    - id: seo-consensus
+      path: agents/seo-consensus.md
   hooks: []
   templates: []

package/content/plugins/seo/skills/agileflow-seo/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: agileflow-seo
+version: 1.2.0
+category: agileflow/seo
+description: |
+  Use when the user wants to audit, improve, or plan SEO for a website:
+  technical SEO, Core Web Vitals, structured data, content quality,
+  sitemap, images, international SEO, or competitor analysis.
+triggers:
+  keywords:
+    - seo
+    - search engine
+    - google ranking
+    - core web vitals
+    - structured data
+    - schema markup
+    - sitemap
+    - meta tags
+    - page speed
+    - crawlability
+    - indexability
+    - seo audit
+    - hreflang
+    - international seo
+    - organic traffic
+    - search rankings
+    - rich results
+    - lcp
+    - cls
+    - inp
+  priority: 55
+provides:
+  agents: []
+learns:
+  enabled: true
+  file: _learnings/seo.yaml
+  maxEntries: 30
+depends:
+  skills: []
+  plugins: [seo]
+---
+
+# AgileFlow SEO
+
+Full-stack SEO audit and optimization assistant. Covers technical crawlability, Core Web Vitals, structured data, content quality, image optimization, and international SEO — with actionable fixes mapped to Google's documentation.
+
+## When this skill activates
+
+- User mentions SEO, search rankings, or organic traffic
+- User asks about Core Web Vitals (LCP, INP, CLS)
+- User wants to add or fix structured data / schema markup
+- User asks about sitemap, robots.txt, or crawlability
+- User wants to optimize images or improve page speed
+- User is expanding to international markets (hreflang)
+- User says their site "isn't getting traffic" or "doesn't rank"
+
+## Opening discovery flow
+
+**When invoked without a clear request, run this before doing anything else.** One smart question covers goal + site context simultaneously. Don't split into multiple question blocks.
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[
+  {
+    "question": "What are you trying to fix or improve with your SEO?",
+    "header": "What's the goal?",
+    "multiSelect": false,
+    "options": [
+      {"label": "Full site audit — show me everything (Recommended)", "description": "6-analyzer sweep → health score 0-100, prioritized findings. Best starting point if you haven't audited before."},
+      {"label": "My site is slow or failing Core Web Vitals", "description": "LCP, INP, CLS analysis with specific resource-level fixes — I'll look at what's actually blocking paint"},
+      {"label": "My pages aren't showing up in Google / getting indexed", "description": "Technical SEO: robots.txt, canonicals, noindex flags, sitemap coverage, redirect chains"},
+      {"label": "I want to rank for specific keywords / improve content", "description": "E-E-A-T content quality, heading structure, content depth — page-by-page or site-wide"},
+      {"label": "I want rich results (stars, FAQs, products) in Google", "description": "Schema markup validation + I'll generate ready-to-use JSON-LD for your page type"},
+      {"label": "I'm expanding to other countries / languages", "description": "hreflang implementation, geo-targeting, language-specific content strategy"},
+      {"label": "Analyze a specific page or blog post", "description": "Deep 6-dimension report card on a single URL — on-page, content, technical, schema, images, performance"}
+    ]
+  },
+  {
+    "question": "What type of site is it?",
+    "header": "Site type",
+    "multiSelect": false,
+    "options": [
+      {"label": "SaaS / Software product", "description": "Login, pricing, docs — I'll tune for SaaS: trial CTAs, feature page schema, dev docs indexing"},
+      {"label": "E-commerce / online store", "description": "Products, categories, checkout — Product schema, Core Web Vitals are critical, filter page handling"},
+      {"label": "Local business / service area", "description": "Physical location or service area — LocalBusiness schema, NAP consistency, Google Business signals"},
+      {"label": "Blog / content publisher", "description": "Articles, guides, news — E-E-A-T signals, Article schema, content freshness, topical authority"},
+      {"label": "Agency / professional services / portfolio", "description": "Services, team, case studies — expertise signals, Service schema, trust factors"},
+      {"label": "Not sure yet / general website", "description": "I'll detect your site type from the URL and apply relevant benchmarks"}
+    ]
+  }
+]</parameter>
+</invoke>
+```
+
+**After they answer, ask for the URL directly** — don't make them choose between "homepage URL" and "specific page URL" as fake options. Just say: _"What's the URL? I'll fetch it and start the analysis."_
+
+If they say they don't have a live URL: discuss strategy or review their code/content instead.
+
+## Context to gather for deeper analysis
+
+For anything beyond a quick single-page check, also ask these before running analyzers. Bundle into the initial conversation, not a third separate AskUserQuestion block:
+
+| Context                                              | Why it matters                                                     |
+| ---------------------------------------------------- | ------------------------------------------------------------------ |
+| Monthly organic traffic (approx)                     | Helps prioritize — traffic loss is P0, growth optimization is P2   |
+| Current top-ranking pages or target keywords         | Focuses audit on what actually matters to their business           |
+| Recent site changes (migrations, redesigns, new CMS) | Migrations cause 80% of sudden ranking drops                       |
+| Tech stack / CMS                                     | Next.js, WordPress, Shopify — affects which fixes are easy vs hard |
+| Competitor URLs (optional)                           | Enables gap analysis in content + schema                           |
+
+Ask naturally: _"A few quick context questions before I start — what's your rough monthly organic traffic, and have you made any big site changes recently (migration, redesign, new platform)?"_
+
+## Routing by goal
+
+| Goal selected             | Route                                                                      |
+| ------------------------- | -------------------------------------------------------------------------- |
+| Full audit                | Fetch URL → `/agileflow:seo:audit URL`                                     |
+| Slow / CWV                | Fetch URL → `/agileflow:seo:performance URL` + `/agileflow:seo:images URL` |
+| Not indexed / crawled     | Fetch URL → `/agileflow:seo:technical URL FOCUS=crawl`                     |
+| Content / keyword ranking | Ask target keyword first → `/agileflow:seo:content URL TYPE={site_type}`   |
+| Rich results / schema     | Fetch URL → `/agileflow:seo:schema URL GENERATE=true`                      |
+| International SEO         | Ask target countries first → `/agileflow:seo:hreflang URL`                 |
+| Single page analysis      | Fetch URL → `/agileflow:seo:page URL`                                      |
+
+## After every analysis — always guide the next step
+
+Never dump findings without guidance. After any command completes, present next steps with AskUserQuestion. Make the recommendation specific to what was actually found:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "{Command} done. {site} scored {X}/100 — {N} findings: {critical} critical, {high} high. Biggest blocker: {top_finding}.",
+  "header": "What to tackle first",
+  "multiSelect": false,
+  "options": [
+    {"label": "Fix {top_critical_issue} now (Recommended)", "description": "{specific fix with expected impact — e.g., 'Adding missing canonical tags — affects 23 pages, prevents duplicate content penalties'}"},
+    {"label": "Deep-dive into {lowest_scoring_category} ({score}/100)", "description": "Worst-scoring area — I'll give you implementation-ready fixes for every issue"},
+    {"label": "Generate {missing_schema_type} schema markup", "description": "I'll produce copy-paste JSON-LD matched to your {site_type} — no manual work"},
+    {"label": "Run full site audit for complete picture", "description": "You've seen one dimension — /agileflow:seo:audit covers all 6 and gives an overall health score"},
+    {"label": "Analyze a competitor for gap comparison", "description": "See what {ranking competitor} is doing that you're not — schema, content structure, CWV"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**Customize every option** based on actual findings. Don't show "Generate schema markup" if they already have perfect schema. Don't show "Full audit" if they just ran it.
+
+## Key principles — apply these throughout
+
+1. **Critical issues before everything else** — a noindex on the homepage outranks every other finding. P0 issues get fixed before P2 optimizations are even mentioned.
+2. **Field data beats lab data** — Google uses CrUX (real user data). If CWV looks good in lab but fails in field, field is what matters.
+3. **Mobile-first always** — Google indexes the mobile version. Desktop-only fixes are worth mentioning but not prioritizing.
+4. **Schema creates opportunity, not traffic** — schema alone won't rank you; it enables rich results when you already rank. Don't oversell it.
+5. **E-E-A-T matters most for YMYL** — health, finance, legal pages need strong author signals, expertise indicators, and trust signals. For a blog about recipes, E-E-A-T is lower priority.
+6. **Recent changes = first suspect** — if rankings dropped recently, ask about migrations, redesigns, URL changes, or CMS switches before running any analyzers. That's the most common root cause.
+
+## Integration
+
+- **agileflow-engineering** — delegate SEO fixes that require code changes: canonical tags, hreflang implementation, structured data injection, performance optimisation, sitemap generation
+- **agileflow-performance** — Core Web Vitals are a direct Google ranking factor; use performance for LCP, INP, and CLS remediation after the SEO audit flags them
+- **agileflow-docs** — after writing SEO-optimised content, sync it through docs to ensure it follows content structure and formatting conventions
+- **agileflow-ads** — align organic and paid keyword strategy; high-performing organic keywords are candidates for paid amplification, and vice versa
+- **agileflow-ideation** — use ideation to generate content ideas grounded in search intent and keyword gaps identified during SEO research
+- **agileflow-research** — gather keyword data, competitor SERP analysis, and industry benchmark data before running the SEO audit or content strategy
+- **agileflow-migration** — URL migrations and site restructuring are the most common cause of ranking drops; coordinate with migration for zero-ranking-loss URL changes
+- **agileflow-delivery** — include SEO validation (canonical correctness, sitemap update, no new 404s) as a delivery gate for any release touching public-facing routes
+- **agileflow-accessibility** — overlaps with SEO: semantic HTML, alt text, and heading hierarchy improve both search and screen reader performance; do both together
+
+## References
+
+Load these when you need deeper knowledge for the relevant task:
+
+| File                                    | When to load                                                                                                             |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `references/cwv-thresholds.md`          | Evaluating Core Web Vitals — LCP/INP/CLS thresholds, field vs lab data, common fixes per metric                          |
+| `references/eeat-framework.md`          | Reviewing content quality — E-E-A-T signals per content type, YMYL requirements                                          |
+| `references/schema-types.md`            | Recommending or generating schema markup — which type for which site, JSON-LD templates, Google's supported rich results |
+| `references/technical-seo-checklist.md` | Deep technical audits — crawl budget, redirect chains, canonical logic, hreflang syntax                                  |
+| `references/keyword-research-guide.md`  | Keyword strategy, search intent matching, gap analysis                                                                   |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                 | When to follow                                                                                               |
+| -------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `workflows/audit.md` | Full site SEO audit — gathers context, runs all 6 analyzers, presents health score + prioritized action plan |
+| `workflows/page.md`  | Single-page analysis — deep 6-dimension report card for a specific URL                                       |

package/content/plugins/seo/skills/agileflow-seo/references/cwv-thresholds.md

@@ -0,0 +1,110 @@
+# Core Web Vitals Thresholds Reference
+
+**Load this when:** analyzing page performance, interpreting CWV scores,
+or recommending specific fixes. Google uses CrUX (field data) for ranking —
+lab data is directional only.
+
+## The three Core Web Vitals
+
+### LCP — Largest Contentful Paint
+
+_Measures loading performance_
+
+| Score             | Threshold   | User experience               |
+| ----------------- | ----------- | ----------------------------- |
+| Good              | ≤ 2.5s      | Fast — ranks well             |
+| Needs improvement | 2.5s – 4.0s | Noticeable delay              |
+| Poor              | > 4.0s      | Frustrating — ranking penalty |
+
+**What counts as LCP element:**
+
+- `<img>` elements
+- `<image>` inside SVG
+- `<video>` poster images
+- Block-level elements with background images
+- Block-level elements containing text
+
+**Common LCP culprits and fixes:**
+
+| Cause                     | Fix                                                             |
+| ------------------------- | --------------------------------------------------------------- |
+| Render-blocking CSS/JS    | Defer non-critical JS, inline critical CSS                      |
+| Slow server TTFB          | CDN, server-side caching, reduce redirects                      |
+| Unoptimized hero image    | WebP/AVIF, `fetchpriority="high"`, no lazy loading on LCP image |
+| Client-side rendering     | SSR or SSG for above-the-fold content                           |
+| Web fonts blocking render | `font-display: swap`, preload critical fonts                    |
+
+**Never lazy-load the LCP image.** This is one of the most common mistakes.
+
+### INP — Interaction to Next Paint
+
+_Measures responsiveness (replaced FID in March 2024)_
+
+| Score             | Threshold     | User experience      |
+| ----------------- | ------------- | -------------------- |
+| Good              | ≤ 200ms       | Feels instant        |
+| Needs improvement | 200ms – 500ms | Noticeable lag       |
+| Poor              | > 500ms       | Janky — users notice |
+
+INP measures the worst interaction across the entire page visit, not just the first.
+
+**Common INP culprits and fixes:**
+
+| Cause                         | Fix                                             |
+| ----------------------------- | ----------------------------------------------- |
+| Long JavaScript tasks (>50ms) | Break up with `setTimeout`, `scheduler.yield()` |
+| Heavy event handlers          | Debounce, throttle, move work off main thread   |
+| Forced style recalculation    | Batch DOM reads/writes, avoid layout thrashing  |
+| Large React re-renders        | `React.memo`, `useMemo`, virtualize long lists  |
+| Third-party scripts           | Load async, defer, or use Partytown             |
+
+### CLS — Cumulative Layout Shift
+
+_Measures visual stability_
+
+| Score             | Threshold  | User experience         |
+| ----------------- | ---------- | ----------------------- |
+| Good              | ≤ 0.1      | Stable                  |
+| Needs improvement | 0.1 – 0.25 | Noticeable shifts       |
+| Poor              | > 0.25     | Jarring — content jumps |
+
+**Common CLS culprits and fixes:**
+
+| Cause                               | Fix                                                    |
+| ----------------------------------- | ------------------------------------------------------ |
+| Images without dimensions           | Always set `width` and `height` attributes             |
+| Ads / embeds without reserved space | Reserve space with `min-height` container              |
+| Fonts causing FOUT                  | `font-display: optional` or preload fonts              |
+| Dynamically injected content        | Insert above-the-fold content only on user interaction |
+| Animations using `top`/`left`       | Use `transform` instead — doesn't cause layout         |
+
+## Field vs lab data
+
+| Type                 | Source                            | Used for Google ranking?                  |
+| -------------------- | --------------------------------- | ----------------------------------------- |
+| **Field (CrUX)**     | Real user measurements via Chrome | ✅ YES — this is what matters for ranking |
+| **Lab (Lighthouse)** | Simulated test environment        | ❌ NO — directional only                  |
+
+If lab data shows Good but field data shows Poor: real users on real devices/networks
+are the problem. Common causes: mobile networks, older devices, third-party scripts.
+
+**Always check CrUX field data** via:
+
+- Google Search Console → Core Web Vitals report
+- PageSpeed Insights (shows both field and lab)
+- `web-vitals` JS library for real user monitoring
+
+## Passing threshold for Google ranking
+
+Google uses the 75th percentile of field data. A page "passes" when
+at least 75% of real user visits meet the Good threshold.
+
+A site with 1,000 daily visitors needs 750 visits with LCP ≤ 2.5s to pass LCP.
+
+## CWV impact on rankings
+
+CWV is a **tiebreaker**, not a primary ranking signal. A page with great
+content and poor CWV will outrank a page with poor content and great CWV.
+But when content is equal, CWV determines the winner.
+
+Fix CWV for user experience first, SEO second.