@softspark/ai-toolkit 2.4.1 → 2.5.0

package/app/skills/seo-validate/reference/geo-guidelines.md

@@ -0,0 +1,248 @@
+# GEO — Generative Engine Optimization
+
+Reference for `seo-validate` Category 6. Structuring content so AI answer engines (ChatGPT, Perplexity, Google AI Overviews, Bing Copilot, Claude) can extract, cite, and quote it accurately.
+
+GEO is emerging practice, not a ranking algorithm with known penalties. **All findings in Category 6 are severity `INFO`** — guidance, not enforcement.
+
+## Core Principles
+
+1. **Structure over prose.** LLMs extract facts from structured blocks (headings, lists, tables, Q&A, schema) much better than from long paragraphs.
+2. **Be citable.** Provide explicit sources, authors, dates, and facts that can be quoted verbatim.
+3. **Answer the question.** Lead with the answer, then elaborate. "Inverted pyramid" journalism works for LLMs too.
+4. **Semantic HTML over div soup.** AI parsers rely on semantic structure just like screen readers.
+5. **Don't hide content behind JS.** Crawler-level LLM ingestion sees initial DOM; hidden tabs/accordions lose their content in extraction.
+
+---
+
+## Content Structure Patterns
+
+### Lead with the answer
+
+LLMs often extract the first 1–2 sentences after a heading as the "answer" to the question that heading implies.
+
+```html
+<!-- Good -->
+<h2>How long does shipping take?</h2>
+<p>Standard shipping takes 3–5 business days in the US and 7–14 days internationally. Express options are 1–2 and 3–7 days respectively.</p>
+<p>Orders placed before 2pm ET ship same-day. Delivery dates are confirmed at checkout based on your address.</p>
+
+<!-- Bad (LLM extracts "we care about fast delivery" as the "answer") -->
+<h2>How long does shipping take?</h2>
+<p>At ExampleCo we care deeply about fast delivery, which is why we've invested in our logistics network...</p>
+<p>(Buried eventually: 3–5 business days standard.)</p>
+```
+
+### Explicit Q&A blocks
+
+Q&A structure is the single highest-signal pattern for LLM extraction:
+
+```html
+<section class="faq">
+  <h2>Frequently Asked Questions</h2>
+  <div>
+    <h3>What is X?</h3>
+    <p>X is ...</p>
+  </div>
+  <div>
+    <h3>How much does X cost?</h3>
+    <p>X costs $... per ...</p>
+  </div>
+</section>
+```
+
+Pair with `FAQPage` JSON-LD (see [schema-types.md](schema-types.md)).
+
+### Tables for comparative data
+
+Plans, pricing, specs, feature matrices:
+
+```html
+<table>
+  <caption>Plan comparison</caption>
+  <thead>
+    <tr><th>Feature</th><th>Free</th><th>Pro</th><th>Enterprise</th></tr>
+  </thead>
+  <tbody>
+    <tr><th scope="row">Users</th><td>1</td><td>10</td><td>Unlimited</td></tr>
+    <tr><th scope="row">Storage</th><td>5GB</td><td>100GB</td><td>Unlimited</td></tr>
+  </tbody>
+</table>
+```
+
+LLMs excel at extracting tabular data but struggle when the same info is written as prose.
+
+### Lists for steps
+
+Use `<ol>` for ordered steps, `<ul>` for unordered sets:
+
+```html
+<h2>How to reset your password</h2>
+<ol>
+  <li>Go to the login page.</li>
+  <li>Click "Forgot password".</li>
+  <li>Enter your email. A reset link arrives within 2 minutes.</li>
+  <li>Click the link and choose a new password.</li>
+</ol>
+```
+
+Pair with `HowTo` schema for critical procedures.
+
+### Definition lists for glossaries
+
+```html
+<dl>
+  <dt>LCP</dt>
+  <dd>Largest Contentful Paint — time to render the largest visible element. Target: under 2.5 seconds.</dd>
+
+  <dt>INP</dt>
+  <dd>Interaction to Next Paint — longest interaction latency in a session. Target: under 200ms.</dd>
+</dl>
+```
+
+---
+
+## Attribution & Citations
+
+LLM answer engines (especially Perplexity, Google AI Overviews, Bing Copilot) prefer citable sources.
+
+### Author bylines
+
+```html
+<article>
+  <h1>Article title</h1>
+  <p class="byline">
+    By <a rel="author" href="/authors/jane-doe">Jane Doe</a>,
+    <time datetime="2026-04-09">April 9, 2026</time>
+  </p>
+  <p>...</p>
+</article>
+```
+
+Pair with `Article` schema including `author` and `datePublished`.
+
+### Inline citations
+
+```html
+<p>
+  Google's Core Web Vitals include LCP, INP, and CLS
+  <cite><a href="https://web.dev/vitals/">web.dev/vitals</a></cite>.
+</p>
+
+<p>
+  According to the 2024 State of JS report, React adoption
+  is at 76%<sup><a href="#ref-1">[1]</a></sup>.
+</p>
+```
+
+### Quotes
+
+Use `<blockquote>` with `cite` attribute, or `<q>` for inline:
+
+```html
+<blockquote cite="https://example.com/source">
+  <p>Direct quote here.</p>
+  <footer>— <cite>Source Author, Source Publication</cite></footer>
+</blockquote>
+
+<p>As Crockford put it, <q cite="https://example.com">JavaScript is the world's most misunderstood language</q>.</p>
+```
+
+---
+
+## speakable Schema
+
+Marks portions of a page suited for audio/voice answer engines (Google Assistant, Alexa, Siri).
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "WebPage",
+  "speakable": {
+    "@type": "SpeakableSpecification",
+    "cssSelector": [".article-summary", "h1"]
+  }
+}
+</script>
+```
+
+- `cssSelector`: CSS selectors for speakable content.
+- `xpath`: XPath selectors (alternative).
+
+Best for: news article summaries, FAQ answers, definitions.
+
+---
+
+## JS-Gated Content Anti-Patterns
+
+LLM crawlers typically ingest the initial DOM. Content revealed by clicks/hovers/scrolls may not be captured.
+
+### Avoid for critical content
+
+```jsx
+// Bad — key FAQ answers hidden
+<Accordion>
+  <AccordionItem title="What does X cost?">
+    <p>X costs $...</p>  {/* Hidden until clicked */}
+  </AccordionItem>
+</Accordion>
+
+// Good — content visible by default, collapsed via CSS (still in DOM)
+<details>
+  <summary>What does X cost?</summary>
+  <p>X costs $...</p>  {/* In DOM always — <details> is semantic */}
+</details>
+```
+
+The native `<details>`/`<summary>` element is a rare exception — content is in the DOM, just visually collapsed.
+
+### Tabs
+
+Similar issue. If tab content is only rendered when active, hidden tabs are lost:
+
+```jsx
+// Bad — only active tab rendered
+{activeTab === 'pricing' && <PricingContent />}
+
+// Better — all rendered, hidden via CSS
+<div hidden={activeTab !== 'pricing'}>
+  <PricingContent />
+</div>
+```
+
+---
+
+## Per-Framework Notes
+
+### Next.js / Remix / SvelteKit / Astro / Gatsby (SSR/SSG)
+
+These render content server-side. GEO concerns are mostly about content structure, not rendering mode.
+
+### SPAs without SSR (Vue, React CRA, Vite-SPA, Angular without Universal)
+
+These don't render content for crawlers at all. **Category 7 (rendering) supersedes GEO** — fix the SPA crawlability first; GEO is moot if nothing is visible.
+
+---
+
+## Checklist (Category 6 findings)
+
+- [ ] FAQ-style content uses `FAQPage` schema.
+- [ ] Summary content uses `speakable` schema.
+- [ ] Paragraphs >400 words are broken up with sub-headings.
+- [ ] Citations use `<cite>` and author bylines.
+- [ ] Quoted content uses `<blockquote>`/`<q>` with `cite` attr.
+- [ ] How-to content uses `<ol>` + `HowTo` schema.
+- [ ] Comparative data uses `<table>` with proper headers.
+- [ ] Glossary content uses `<dl>`/`<dt>`/`<dd>`.
+- [ ] Semantic HTML (`<article>`, `<section>`, `<main>`, `<nav>`, `<aside>`) is used over `<div>`.
+- [ ] Critical content is NOT hidden behind tabs/accordions (except native `<details>`).
+
+---
+
+## References
+
+- Princeton/Georgia Tech GEO paper (Aggarwal et al., 2023): https://arxiv.org/abs/2311.09735
+- Schema.org speakable: https://schema.org/speakable
+- Schema.org FAQPage: https://schema.org/FAQPage
+- Schema.org HowTo: https://schema.org/HowTo
+- Google Search Central (structured data guidelines): https://developers.google.com/search/docs/appearance/structured-data

package/app/skills/seo-validate/reference/schema-types.md

@@ -0,0 +1,465 @@
+# Schema.org JSON-LD Templates
+
+Reference for `seo-validate` Category 3 (Structured Data). Required properties for the rich-result-eligible types, with JSON-LD templates.
+
+Source: Schema.org vocabulary + Google Search Central rich-results requirements.
+
+## Base Format
+
+All JSON-LD is embedded in `<script type="application/ld+json">` blocks, usually in `<head>` or the top of `<body>`:
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "...",
+  ...
+}
+</script>
+```
+
+**Universal required properties** (checked by Category 3):
+- `@context` — always `https://schema.org`.
+- `@type` — valid Schema.org type name.
+
+Multiple types on one page: use an array:
+
+```html
+<script type="application/ld+json">
+[
+  { "@context": "https://schema.org", "@type": "Organization", ... },
+  { "@context": "https://schema.org", "@type": "WebSite", ... }
+]
+</script>
+```
+
+---
+
+## Article
+
+For blog posts, news, editorial content.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "Article headline (max 110 chars for Google rich results)",
+  "image": [
+    "https://example.com/16x9.jpg",
+    "https://example.com/4x3.jpg",
+    "https://example.com/1x1.jpg"
+  ],
+  "datePublished": "2026-04-09T08:00:00+00:00",
+  "dateModified": "2026-04-10T12:00:00+00:00",
+  "author": [{
+    "@type": "Person",
+    "name": "Jane Doe",
+    "url": "https://example.com/authors/jane-doe"
+  }],
+  "publisher": {
+    "@type": "Organization",
+    "name": "ExampleCo",
+    "logo": {
+      "@type": "ImageObject",
+      "url": "https://example.com/logo.png"
+    }
+  },
+  "mainEntityOfPage": {
+    "@type": "WebPage",
+    "@id": "https://example.com/blog/article-slug"
+  },
+  "description": "Short description of the article"
+}
+```
+
+**Required** (Category 3 flags absence): `headline`, `author`, `datePublished`, `image`.
+**Strongly recommended**: `dateModified`, `publisher`, `mainEntityOfPage`.
+
+Subtypes: `NewsArticle`, `BlogPosting`, `TechArticle`, `OpinionNewsArticle`.
+
+---
+
+## FAQPage
+
+Triggers rich FAQ results in SERP.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "What is X?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "X is ..."
+      }
+    },
+    {
+      "@type": "Question",
+      "name": "How much does X cost?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "X costs $..."
+      }
+    }
+  ]
+}
+```
+
+**Required**: `mainEntity` array with ≥2 `Question` items, each with `name` + `acceptedAnswer.text`.
+
+Google restriction: FAQ rich results only shown for authoritative government/health sites as of August 2023 — but the markup still helps LLM extraction (GEO).
+
+---
+
+## HowTo
+
+For step-by-step instructional content.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "HowTo",
+  "name": "How to reset your password",
+  "description": "Steps to reset your account password",
+  "totalTime": "PT5M",
+  "supply": [
+    { "@type": "HowToSupply", "name": "Email access" }
+  ],
+  "tool": [
+    { "@type": "HowToTool", "name": "Web browser" }
+  ],
+  "step": [
+    {
+      "@type": "HowToStep",
+      "name": "Go to the login page",
+      "text": "Navigate to https://example.com/login",
+      "url": "https://example.com/login"
+    },
+    {
+      "@type": "HowToStep",
+      "name": "Click 'Forgot password'",
+      "text": "On the login page, click the 'Forgot password' link."
+    }
+  ]
+}
+```
+
+**Required**: `name`, `step` array with ≥2 `HowToStep` items.
+
+---
+
+## BreadcrumbList
+
+Breadcrumb trails in SERP.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+    {
+      "@type": "ListItem",
+      "position": 1,
+      "name": "Home",
+      "item": "https://example.com/"
+    },
+    {
+      "@type": "ListItem",
+      "position": 2,
+      "name": "Blog",
+      "item": "https://example.com/blog"
+    },
+    {
+      "@type": "ListItem",
+      "position": 3,
+      "name": "Article Title"
+    }
+  ]
+}
+```
+
+**Required**: `itemListElement` array with `position`, `name`, and `item` (except last). Last item omits `item` since it's the current page.
+
+---
+
+## Organization
+
+Defines your company/brand for Knowledge Graph.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "ExampleCo",
+  "url": "https://example.com",
+  "logo": "https://example.com/logo.png",
+  "sameAs": [
+    "https://twitter.com/exampleco",
+    "https://www.linkedin.com/company/exampleco",
+    "https://github.com/exampleco"
+  ],
+  "contactPoint": [{
+    "@type": "ContactPoint",
+    "telephone": "+1-555-123-4567",
+    "contactType": "customer service",
+    "areaServed": "US",
+    "availableLanguage": ["en", "es"]
+  }]
+}
+```
+
+**Required**: `name`, `url`, `logo`.
+
+Subtypes for specific kinds: `Corporation`, `NGO`, `EducationalOrganization`, `LocalBusiness` (see below).
+
+Typically placed once on the site, in a shared layout. `WebSite` schema can reference it via `publisher`.
+
+---
+
+## Product
+
+For e-commerce product pages.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "Product name",
+  "image": [
+    "https://example.com/product-1x1.jpg",
+    "https://example.com/product-4x3.jpg",
+    "https://example.com/product-16x9.jpg"
+  ],
+  "description": "Product description",
+  "brand": {
+    "@type": "Brand",
+    "name": "Brand Name"
+  },
+  "sku": "SKU-12345",
+  "mpn": "MPN-12345",
+  "gtin13": "0123456789012",
+  "offers": {
+    "@type": "Offer",
+    "url": "https://example.com/products/sku-12345",
+    "priceCurrency": "USD",
+    "price": "49.99",
+    "priceValidUntil": "2027-01-01",
+    "availability": "https://schema.org/InStock",
+    "itemCondition": "https://schema.org/NewCondition"
+  },
+  "aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "4.6",
+    "reviewCount": "142"
+  },
+  "review": [{
+    "@type": "Review",
+    "author": { "@type": "Person", "name": "Jane" },
+    "reviewRating": { "@type": "Rating", "ratingValue": "5" },
+    "reviewBody": "Great product."
+  }]
+}
+```
+
+**Required**: `name`, `image`, `offers` (with `price` + `priceCurrency` + `availability`).
+**Strongly recommended for rich results**: `aggregateRating`, `review`, `brand`.
+
+---
+
+## LocalBusiness
+
+For brick-and-mortar businesses (local SEO).
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "LocalBusiness",
+  "@id": "https://example.com/#local-business",
+  "name": "ExampleCo Store",
+  "image": "https://example.com/store.jpg",
+  "url": "https://example.com",
+  "telephone": "+1-555-123-4567",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "123 Main St",
+    "addressLocality": "San Francisco",
+    "addressRegion": "CA",
+    "postalCode": "94110",
+    "addressCountry": "US"
+  },
+  "geo": {
+    "@type": "GeoCoordinates",
+    "latitude": 37.7749,
+    "longitude": -122.4194
+  },
+  "openingHoursSpecification": [
+    {
+      "@type": "OpeningHoursSpecification",
+      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
+      "opens": "09:00",
+      "closes": "18:00"
+    },
+    {
+      "@type": "OpeningHoursSpecification",
+      "dayOfWeek": "Saturday",
+      "opens": "10:00",
+      "closes": "16:00"
+    }
+  ],
+  "priceRange": "$$"
+}
+```
+
+**Required**: `name`, `address`, `telephone`.
+**Strongly recommended**: `openingHoursSpecification`, `geo`, `url`, `image`.
+
+Use more specific subtypes when applicable: `Restaurant`, `Hotel`, `MedicalClinic`, `Store`, `AutoDealer`, etc.
+
+---
+
+## WebSite (with SearchAction)
+
+Enables sitelinks search box in SERP.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "WebSite",
+  "name": "ExampleCo",
+  "url": "https://example.com",
+  "potentialAction": {
+    "@type": "SearchAction",
+    "target": {
+      "@type": "EntryPoint",
+      "urlTemplate": "https://example.com/search?q={search_term_string}"
+    },
+    "query-input": "required name=search_term_string"
+  }
+}
+```
+
+---
+
+## Event
+
+For conferences, concerts, webinars.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Event",
+  "name": "Event name",
+  "startDate": "2026-06-15T09:00:00-07:00",
+  "endDate": "2026-06-15T17:00:00-07:00",
+  "eventAttendanceMode": "https://schema.org/OfflineEventAttendanceMode",
+  "eventStatus": "https://schema.org/EventScheduled",
+  "location": {
+    "@type": "Place",
+    "name": "Venue Name",
+    "address": { "@type": "PostalAddress", ... }
+  },
+  "image": ["https://example.com/event.jpg"],
+  "description": "...",
+  "offers": {
+    "@type": "Offer",
+    "url": "https://example.com/event",
+    "price": "99.00",
+    "priceCurrency": "USD",
+    "availability": "https://schema.org/InStock",
+    "validFrom": "2026-01-01T00:00:00-08:00"
+  },
+  "organizer": {
+    "@type": "Organization",
+    "name": "ExampleCo",
+    "url": "https://example.com"
+  }
+}
+```
+
+**Required**: `name`, `startDate`, `location` (or `eventAttendanceMode: OnlineEventAttendanceMode`).
+
+---
+
+## Recipe
+
+For food recipes.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Recipe",
+  "name": "Recipe name",
+  "image": ["..."],
+  "author": { "@type": "Person", "name": "Jane Doe" },
+  "datePublished": "2026-04-09",
+  "description": "...",
+  "prepTime": "PT15M",
+  "cookTime": "PT1H",
+  "totalTime": "PT1H15M",
+  "recipeYield": "8 servings",
+  "recipeIngredient": ["2 cups flour", "1 tsp salt"],
+  "recipeInstructions": [
+    { "@type": "HowToStep", "text": "..." }
+  ],
+  "nutrition": {
+    "@type": "NutritionInformation",
+    "calories": "250 calories"
+  },
+  "aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "4.8",
+    "reviewCount": "42"
+  }
+}
+```
+
+---
+
+## VideoObject
+
+For video content.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "VideoObject",
+  "name": "Video title",
+  "description": "...",
+  "thumbnailUrl": ["https://example.com/thumb-16x9.jpg"],
+  "uploadDate": "2026-04-09T08:00:00+00:00",
+  "duration": "PT5M30S",
+  "contentUrl": "https://example.com/video.mp4",
+  "embedUrl": "https://example.com/embed/video"
+}
+```
+
+---
+
+## Common Mistakes (flagged by Category 3)
+
+1. **Missing `@context`** or wrong value (e.g., `http://` instead of `https://`).
+2. **Wrong `@type`** (e.g., `article` lowercase — must be `Article`).
+3. **Dates not in ISO 8601** (`2026-04-09` good; `April 9, 2026` bad).
+4. **Relative URLs** for `image`, `logo`, `url` — must be absolute.
+5. **Missing required properties** per type (see each section above).
+6. **Markup doesn't match visible content** — violates Google guidelines.
+7. **Duplicate JSON-LD blocks** with conflicting data — consolidate into one.
+8. **Fake reviews / made-up aggregate ratings** — violates Google guidelines.
+
+---
+
+## Testing
+
+- Google Rich Results Test: https://search.google.com/test/rich-results
+- Schema.org validator: https://validator.schema.org/
+
+---
+
+## References
+
+- Schema.org: https://schema.org/
+- Google rich results: https://developers.google.com/search/docs/appearance/structured-data
+- JSON-LD 1.1: https://www.w3.org/TR/json-ld11/