npm - @softspark/ai-toolkit - Versions diffs - 2.4.0 → 2.5.0 - Mend

@softspark/ai-toolkit 2.4.0 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (52) hide show

package/AGENTS.md +32 -19
package/CHANGELOG.md +45 -0
package/README.md +13 -12
package/app/.claude-plugin/plugin.json +1 -1
package/app/ARCHITECTURE.md +2 -2
package/app/agents/code-reviewer.md +6 -7
package/app/agents/frontend-specialist.md +33 -2
package/app/agents/seo-specialist.md +1 -1
package/app/personas/frontend-lead.md +48 -5
package/app/skills/a11y-validate/SKILL.md +377 -0
package/app/skills/a11y-validate/reference/aria-patterns.md +259 -0
package/app/skills/a11y-validate/reference/eaa-compliance.md +252 -0
package/app/skills/a11y-validate/reference/mobile-eaa.md +329 -0
package/app/skills/a11y-validate/reference/wcag-2-1-aa.md +285 -0
package/app/skills/a11y-validate/reference/wcag-2-2-aa.md +221 -0
package/app/skills/a11y-validate/scripts/a11y-scanner.py +639 -0
package/app/skills/clean-code/reference/python.md +3 -3
package/app/skills/design-engineering/SKILL.md +2 -5
package/app/skills/review/SKILL.md +30 -6
package/app/skills/seo-validate/SKILL.md +460 -0
package/app/skills/seo-validate/reference/core-web-vitals.md +445 -0
package/app/skills/seo-validate/reference/geo-aeo-patterns.md +259 -0
package/app/skills/seo-validate/reference/geo-guidelines.md +248 -0
package/app/skills/seo-validate/reference/schema-types.md +465 -0
package/app/skills/seo-validate/reference/spa-ssg-patterns.md +351 -0
package/app/skills/seo-validate/reference/w3c-guidelines.md +289 -0
package/app/skills/seo-validate/scripts/seo-scanner.py +549 -0
package/bin/ai-toolkit.js +32 -5
package/kb/reference/architecture-overview.md +3 -3
package/kb/reference/cli-reference.md +1 -1
package/kb/reference/codex-cli-compatibility.md +4 -0
package/kb/reference/comparison.md +1 -1
package/kb/reference/extension-api.md +2 -0
package/kb/reference/skills-catalog.md +3 -1
package/llms-full.txt +16 -6
package/manifest.json +3 -3
package/package.json +2 -2
package/scripts/config_cli.py +4 -10
package/scripts/config_resolver.py +23 -5
package/scripts/doctor.py +76 -4
package/scripts/hook_sources.py +3 -0
package/scripts/inject_hook_cli.py +74 -1
package/scripts/install.py +34 -3
package/scripts/install_steps/ai_tools.py +79 -16
package/scripts/install_steps/install_state.py +25 -0
package/scripts/install_steps/markers.py +2 -1
package/scripts/install_steps/project_registry.py +9 -0
package/scripts/plugin.py +1 -1
package/scripts/propagate_global.py +92 -0
package/scripts/rule_sources.py +3 -2
package/scripts/update_projects.py +7 -1
package/scripts/url_fetch.py +5 -0

package/app/skills/seo-validate/reference/spa-ssg-patterns.md ADDED Viewed

@@ -0,0 +1,351 @@
+# SPA / SSR / SSG / CSR / ISR Patterns
+Reference for `seo-validate` Category 7. How to detect rendering mode, identify SPA pitfalls, and flag crawlability issues per framework.
+## Rendering Mode Decision Tree
+```
+Is content server-rendered before the client gets it?
+├── YES (server returns meaningful HTML)
+│   ├── At request time?   → SSR (Server-Side Rendering)
+│   ├── At build time?     → SSG (Static Site Generation)
+│   └── Cached + revalidated periodically? → ISR (Incremental Static Regeneration)
+└── NO (server returns a shell; client renders)
+    └── CSR (Client-Side Rendering) / SPA — CRAWLABILITY RISK
+```
+For SEO:
+- **SSG / SSR / ISR**: safe — crawlers see content immediately.
+- **CSR / SPA**: risky — most crawlers see an empty shell.
+- **Hybrid** (SSR/SSG for public routes, CSR for dashboards): check each route type.
+---
+## Why CSR SPAs Fail SEO
+Modern crawlers (Googlebot) can execute JS, but:
+1. **Other engines lag**: Bing, DuckDuckGo, Yandex, Baidu have limited/no JS execution.
+2. **LLM answer engines** (ChatGPT, Perplexity, Bing Copilot) typically ingest raw HTML — they don't wait for hydration.
+3. **Social scrapers** (Facebook, LinkedIn, Slack, Twitter/X) don't execute JS — OG tags in `<head>` must be present at initial response, not injected by React.
+4. **Googlebot delays JS rendering** — two-wave indexing can delay discovery by days/weeks.
+5. **Hash routes (`/#/about`)** are fragments — not indexed as separate URLs.
+6. **Unique per-route meta is impossible without SSR/SSG/prerender** — the static `index.html` has the same `<title>` and `<meta description>` for every route.
+**Bottom line**: a CSR-only SPA with public marketing content is effectively invisible to half the SEO ecosystem. This is a HIGH-severity finding.
+---
+## Framework Detection Patterns
+### Next.js
+Detection: `next` in `package.json` deps.
+Config: `next.config.js` / `next.config.mjs` / `next.config.ts`.
+Rendering per route (App Router, Next.js 13+):
+- Static by default (SSG).
+- `export const dynamic = 'force-dynamic'` → SSR.
+- `export const revalidate = 60` → ISR.
+- `'use client'` at top of component → component runs client-side, but page can still be SSR/SSG.
+- `dynamic(() => import(...), { ssr: false })` → that specific component is CSR only.
+Flags:
+- `next.config.*` with `output: 'export'` → forced SSG. Dynamic features (API routes, ISR, middleware) won't work.
+- Page file with `'use client'` at top: page still pre-renders but becomes a client component boundary.
+- `dynamic(..., { ssr: false })` wrapping LCP element → HIGH severity.
+Per-route metadata:
+- App Router: `export const metadata = { ... }` or `export async function generateMetadata() { ... }`.
+- Pages Router: `<Head>` from `next/head`.
+### Nuxt
+Detection: `nuxt` in `package.json` deps.
+Config: `nuxt.config.ts`.
+Rendering:
+- Default: SSR.
+- `ssr: false` → SPA mode (dangerous for SEO).
+- `nitro.prerender.routes: [...]` → SSG routes.
+- `nuxt generate` command → full SSG export.
+Per-route metadata:
+- `useHead({ title: ..., meta: [...] })` composable.
+- `definePageMeta({ ... })`.
+### Astro
+Detection: `astro` in `package.json` deps.
+Config: `astro.config.mjs`.
+Rendering:
+- `output: 'static'` (default) → SSG.
+- `output: 'server'` → SSR (with adapter like `@astrojs/node`, `@astrojs/vercel`).
+- `output: 'hybrid'` → mostly static, opt-in SSR per page.
+Component-level:
+- `client:load` / `client:idle` / `client:visible` → islands hydrate on client, but initial HTML is rendered.
+- `client:only="react"` → component is CSR only. Flag when on hero/above-the-fold content.
+Per-page metadata: direct `<meta>` tags in layout or frontmatter.
+### Gatsby
+Detection: `gatsby` in `package.json` deps.
+Config: `gatsby-config.js`.
+Rendering: SSG by default. `gatsby build` creates static HTML per page.
+Modern Gatsby (4+) supports SSR (`getServerData`) and DSG (Deferred Static Generation).
+Per-page metadata:
+- `react-helmet` or `gatsby-plugin-react-helmet`.
+- Gatsby Head API: `export const Head = () => (<><title>...</title></>)`.
+### SvelteKit
+Detection: `@sveltejs/kit` in `package.json` deps.
+Config: `svelte.config.js`.
+Rendering per route:
+- `export const ssr = true` (default) — SSR.
+- `export const ssr = false` — CSR only.
+- `export const prerender = true` — SSG for that route.
+- `export const prerender = 'auto'` — prerender unless dynamic data.
+Adapter determines deployment:
+- `@sveltejs/adapter-static` → pure SSG.
+- `@sveltejs/adapter-node` → Node server, SSR.
+- `@sveltejs/adapter-vercel` / `@sveltejs/adapter-cloudflare` → serverless.
+Per-route metadata: `<svelte:head>` block.
+### Remix
+Detection: `@remix-run/*` in `package.json` deps.
+Rendering: SSR by default. Loader functions run server-side, deliver HTML.
+Per-route metadata: `export const meta: MetaFunction = () => [...]`.
+No built-in SSG — always SSR.
+### Angular
+Detection: `@angular/core` in `package.json` deps.
+Rendering:
+- Default: CSR only → HIGH-severity for content sites.
+- With `@angular/ssr` (Angular 17+) or `@nguniversal/*` (older): SSR.
+Check `angular.json` for `ssr` builder config.
+Per-page metadata: inject `Meta` and `Title` services from `@angular/platform-browser`.
+### Vue (non-Nuxt SPA)
+Detection: `vue` in deps without `nuxt`.
+Rendering: CSR unless using:
+- Vite SSR (`vite-plugin-ssr` → now `vike`).
+- Vue Storefront or similar custom SSR.
+- `@vue/server-renderer` explicitly.
+Default Vue SPA from `create-vue` / `@vue/cli` is CSR-only → HIGH severity for content sites.
+### React SPA (Vite)
+Detection: `react` + `vite` in deps, no `next`, no `@remix-run/*`.
+Rendering: CSR only unless:
+- `vike` (formerly vite-plugin-ssr) → SSR.
+- `vite-plugin-prerender` / `@preact/preset-vite` with prerender option → build-time prerender.
+- `@tanstack/router` with SSR plugin.
+Default Vite + React is CSR → HIGH severity for content sites.
+### Create React App (CRA)
+Detection: `react-scripts` in deps.
+Rendering: CSR only.
+Mitigations (rare — CRA is deprecated):
+- `react-snap` plugin → build-time prerender crawl.
+Default CRA is CSR → HIGH severity. Also: recommend migrating to Next.js / Remix / Vite+Vike.
+---
+## Detection Signals
+### Entry HTML inspection
+Read `public/index.html`, `index.html`, `src/app.html`, or framework entry:
+**Empty mount point (SPA signal)**:
+```html
+<body>
+  <div id="root"></div>
+  <script src="/main.js"></script>
+</body>
+```
+**Prerendered content (SSG/SSR signal)**:
+```html
+<body>
+  <div id="root">
+    <main>
+      <h1>Actual content here</h1>
+      ...
+    </main>
+  </div>
+  <script src="/main.js"></script>
+</body>
+```
+Rule of thumb: if `<div id="root">` / `<div id="app">` / `<div id="__next">` contains only whitespace or tiny loader markup, it's a SPA shell — flag.
+### Runtime-only meta detection
+Look for:
+- `react-helmet-async` usage without `HelmetProvider` in SSR server entry.
+- `vue-meta` / `@vueuse/head` without SSR plugin.
+- Direct `document.title = ...` / `document.querySelector('meta[name=description]').content = ...` writes.
+If meta is only set at runtime, it won't be in the initial response → crawlers miss it.
+### HashRouter detection
+```jsx
+// React Router HashRouter
+import { HashRouter } from 'react-router-dom';
+<HashRouter>...</HashRouter>
+// Vue Router hash mode
+createRouter({ history: createWebHashHistory(), ... })
+```
+Hash routes like `/#/about` are fragments — Google does NOT index them as separate URLs.
+Always use `BrowserRouter` / `createWebHistory()` for public routes.
+### Hydration mismatch signals
+```jsx
+// Red flag: different output based on environment
+function Component() {
+  if (typeof window !== 'undefined') {
+    return <ClientVariant />;
+  }
+  return <ServerVariant />;
+}
+// Red flag: overuse of suppressHydrationWarning
+<div suppressHydrationWarning>
+  {Math.random()}  {/* Masking a real bug */}
+</div>
+```
+The skill flags `>3` occurrences of `suppressHydrationWarning` in the codebase as a heuristic WARN.
+---
+## Prerendering Strategies for SPAs
+When migration to Next.js / Remix isn't feasible, SPA prerendering is the fallback:
+### react-snap (CRA, Vite-React)
+Runs a headless browser against the SPA at build time, snapshots the DOM per route, writes static HTML.
+```json
+// package.json
+{
+  "scripts": {
+    "postbuild": "react-snap"
+  },
+  "reactSnap": {
+    "source": "build",
+    "include": ["/", "/about", "/pricing"]
+  }
+}
+```
+Works for: static content sites. Breaks on: dynamic/authenticated routes.
+### vite-plugin-prerender
+Same approach for Vite projects.
+### vike (formerly vite-plugin-ssr)
+Full SSR for Vite projects. More invasive than prerender plugins but more capable.
+### prerender-spa-plugin (Webpack)
+Older Webpack-based solution for Vue/React SPAs.
+### Dynamic rendering (legacy — Google deprecated)
+`prerender.io`, `rendertron`: intercept requests from crawler user agents, serve prerendered HTML.
+Google's recommendation as of 2024: use SSR/SSG instead. Dynamic rendering is a fallback, not a solution — detected as INFO severity, not HIGH.
+---
+## Quick Detection Reference (for seo-validate Category 7)
+| Check | Signal | Severity |
+|-------|--------|----------|
+| `public/index.html` mount div empty | CSR confirmed | HIGH (if content site) |
+| `package.json` has `react-scripts` + no `react-snap` | CRA SPA no prerender | HIGH |
+| `react` + `vite` + no `vike`/`vite-plugin-ssr`/prerender | Vite SPA no prerender | HIGH |
+| `@angular/core` + no `@angular/ssr` + no `@nguniversal/*` | Angular SPA no SSR | HIGH |
+| `vue` + no `nuxt` + no SSR plugin | Vue SPA no SSR | HIGH |
+| `HashRouter` or `createWebHashHistory` on public route | Hash routing | HIGH |
+| `dynamic(..., { ssr: false })` on hero component | LCP blocked + CSR | HIGH |
+| `ssr: false` in `nuxt.config` | Nuxt SPA mode | WARN |
+| `export const ssr = false` in SvelteKit route | Route is CSR | WARN |
+| `client:only` on Astro hero component | Component is CSR | WARN |
+| `'use client'` at top of Next.js page with no server-side logic | Forced CSR boundary | WARN |
+| `react-helmet-async` without `HelmetProvider` in server entry | Meta only client-side | HIGH |
+| `document.title = ...` in component code | Runtime-only title | HIGH |
+| `suppressHydrationWarning` ≥4 occurrences | Likely masked mismatch | WARN |
+| `prerender.io` / `rendertron` config | Legacy dynamic rendering | INFO |
+---
+## When to NOT Flag
+Not every SPA needs SEO. The skill should NOT flag rendering-mode HIGH for:
+- Auth-gated dashboards, admin panels (no public routes to index).
+- Internal tools, intranet apps.
+- Mobile app backends with no web UI.
+- Electron/desktop apps.
+Heuristic: if no public routes exist (check `robots.txt`, presence of marketing pages, landing page in a layout), downgrade SPA findings to INFO.
+For mixed cases (Next.js app with marketing routes + dashboard routes), flag per-route: marketing routes should be SSG/SSR; dashboard can be CSR-heavy.
+---
+## References
+- Google Search Central on JavaScript SEO: https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics
+- web.dev rendering patterns: https://web.dev/rendering-on-the-web/
+- Next.js rendering: https://nextjs.org/docs/app/building-your-application/rendering
+- Nuxt rendering: https://nuxt.com/docs/guide/concepts/rendering
+- Astro rendering: https://docs.astro.build/en/guides/rendering/
+- Gatsby rendering: https://www.gatsbyjs.com/docs/conceptual/rendering-options/
+- SvelteKit rendering: https://kit.svelte.dev/docs/page-options
+- Angular SSR: https://angular.dev/guide/ssr
+- vike (vite-plugin-ssr): https://vike.dev/
+- react-snap: https://github.com/stereobooster/react-snap

package/app/skills/seo-validate/reference/w3c-guidelines.md ADDED Viewed

@@ -0,0 +1,289 @@
+# W3C HTML Guidelines (SEO-Relevant Subset)
+Reference for `seo-validate` Category 1 (HTML Semantics & W3C) and Category 2 (Meta & Open Graph).
+Sources: W3C HTML Living Standard (HTML5), WCAG 2.2, IETF RFC 5646 (BCP 47), Open Graph Protocol, Twitter Card spec.
+## Document Structure
+### DOCTYPE
+HTML5 §8.1.1 — the document MUST begin with `<!DOCTYPE html>` (case-insensitive). Missing doctype triggers quirks mode in older browsers and breaks modern CSS behavior — effectively a HIGH-severity issue.
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>...</head>
+  <body>...</body>
+</html>
+```
+### lang attribute
+HTML5 §3.2.6 — the `<html>` element SHOULD have a `lang` attribute using a BCP 47 language tag.
+- Required for screen reader pronunciation (WCAG 3.1.1).
+- Signals primary language to search engines.
+- Feeds into hreflang correctness checks.
+Valid examples:
+- `lang="en"` — English (generic)
+- `lang="en-US"` — English (United States)
+- `lang="pl"` — Polish
+- `lang="zh-Hant"` — Chinese (Traditional)
+Invalid examples (flag these):
+- `lang="en_US"` — underscore, not hyphen
+- `lang="english"` — not an ISO code
+- `lang="EN"` — case irrelevant per RFC but inconsistent; prefer lowercase
+### charset
+HTML5 §4.2.5.5 — `<meta charset="utf-8">` MUST appear in `<head>` as early as possible, within the first 1024 bytes. UTF-8 is the only accepted encoding for new content.
+```html
+<head>
+  <meta charset="utf-8">
+  <!-- other meta tags follow -->
+</head>
+```
+### viewport
+Not formally W3C but required for mobile-first indexing:
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1">
+```
+Missing viewport = mobile rendering breaks = Google ranks the page lower.
+## Document Outline
+### Heading hierarchy
+HTML5 §4.3.6 defines heading semantics. Current best practice:
+- **Exactly one `<h1>`** per page/route component.
+- **Sequential levels**: `h1` → `h2` → `h3`, never skip (e.g., `h1` → `h3`).
+- **Semantic, not decorative**: heading level should reflect content hierarchy, not visual size. Use CSS for styling.
+### Landmarks
+HTML5 §4.3 + ARIA Landmarks. Every page should have at minimum:
+- `<header>` — site/page header
+- `<nav>` — primary navigation
+- `<main>` — main content (exactly one per page)
+- `<footer>` — site/page footer
+Optionally: `<aside>`, `<section>` (requires accessible name), `<article>`.
+Using `<div>` for these is a WARN — semantic HTML aids both screen readers and AI/LLM parsers.
+## Meta Tags
+### Title
+HTML5 §4.2.2. Required element inside `<head>`.
+- Recommended length: **50–60 characters** including brand/separator. Google truncates at ~600 pixels (~50–60 chars).
+- Unique per page.
+- Format: `Primary Keyword - Brand` or `Primary Keyword | Secondary | Brand`.
+- Avoid keyword stuffing.
+```html
+<title>SEO Audit Tool - Free Analyzer | ExampleCo</title>
+```
+### Description
+HTML `<meta name="description">`.
+- Recommended length: **150–160 characters**. Google truncates at ~155 chars (mobile narrower).
+- Unique per page.
+- Include primary keyword naturally.
+- Write as a SERP call-to-action.
+```html
+<meta name="description" content="Free SEO audit tool. Instantly analyze your site's title tags, meta descriptions, and Core Web Vitals. Fix issues before Google indexes them.">
+```
+### Canonical
+HTML5 §4.2.4 + Google Search Central canonicalization.
+- Required on indexable pages.
+- Must be an absolute URL.
+- Self-referencing canonical on canonical version.
+- Points to preferred version when multiple URLs return the same content (tracking params, pagination, sort orders).
+```html
+<link rel="canonical" href="https://example.com/blog/post-slug">
+```
+#### Canonical + URL parameters
+Query parameters create duplicate URLs unless handled explicitly. After Google deprecated the Search Console URL Parameters tool (April 2022), the only remaining signals are `rel="canonical"`, `robots.txt`, and `<meta name="robots">`.
+**Tracking parameters** (`utm_source`, `utm_medium`, `utm_campaign`, `gclid`, `fbclid`, `msclkid`, `ref`):
+Every variant must canonical to the clean URL:
+```html
+<!-- User lands on: https://example.com/page?utm_source=newsletter&utm_campaign=apr26 -->
+<link rel="canonical" href="https://example.com/page">
+```
+**Faceted navigation** (filters, sort, pagination on category/product listing pages):
+```html
+<!-- URL: /products?category=shoes&color=red&sort=price-asc&page=2 -->
+<!-- Strategy A: canonical to clean base, let Google dedup -->
+<link rel="canonical" href="https://example.com/products">
+<!-- Strategy B: canonical to first page + rel=prev/next (deprecated as signal but still used by some engines) -->
+<link rel="canonical" href="https://example.com/products?category=shoes">
+```
+For facet combinations that are NOT genuinely different content (e.g., `?sort=name` vs `?sort=price`), always canonical to the clean URL. For facets that ARE different content (e.g., `/products?category=shoes` is a distinct shoe listing), the facet URL itself is canonical.
+**Search result pages (SRPs)**:
+Internal search results are thin, user-specific content. Google's Search Essentials explicitly lists SRPs as content to keep out of the index.
+Two valid strategies:
+```html
+<!-- Strategy A: noindex, allow crawl (discovers outbound links) -->
+<meta name="robots" content="noindex, follow">
+<link rel="canonical" href="https://example.com/search">
+```
+```
+# Strategy B: robots.txt Disallow — blocks crawl entirely
+User-agent: *
+Disallow: /search?*
+Disallow: /*?q=*
+```
+Never combine Disallow + noindex — a disallowed URL will never be fetched, so the noindex directive is never read.
+**Pagination**:
+Modern Google treats paginated content as individual URLs. Each page self-canonicals:
+```html
+<!-- /blog?page=2 -->
+<link rel="canonical" href="https://example.com/blog?page=2">
+```
+`rel="prev"` and `rel="next"` are deprecated as a Google signal (2019) but remain valid HTML and are used by other engines/accessibility tools.
+### Robots
+Controls indexing and following per-page.
+```html
+<!-- Indexable, links followed (default — usually omitted) -->
+<meta name="robots" content="index, follow">
+<!-- Block indexing (confirm intent!) -->
+<meta name="robots" content="noindex, nofollow">
+<!-- Common production mistake: leftover from dev -->
+<meta name="robots" content="noindex">
+```
+`noindex` on production routes is a HIGH-severity finding unless explicitly intentional (admin pages, thank-you pages, search-results pages).
+## Open Graph Protocol
+`https://ogp.me/` — used by Facebook, LinkedIn, Slack, Discord, Teams, WhatsApp.
+Required for rich social cards:
+```html
+<meta property="og:title" content="Page Title">
+<meta property="og:description" content="Page description">
+<meta property="og:image" content="https://example.com/og-image.jpg">  <!-- ABSOLUTE URL -->
+<meta property="og:url" content="https://example.com/page">
+<meta property="og:type" content="article">  <!-- or website, product, profile -->
+<meta property="og:site_name" content="ExampleCo">
+```
+Image specs:
+- Recommended: 1200×630 px (1.91:1 aspect ratio).
+- Maximum: 8 MB.
+- JPEG or PNG. WebP has limited platform support for OG.
+Relative URLs for `og:image` are a definitive WARN — many scrapers don't resolve them.
+## Twitter Card
+```html
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:site" content="@example">
+<meta name="twitter:creator" content="@author">
+<meta name="twitter:title" content="Page Title">
+<meta name="twitter:description" content="Page description">
+<meta name="twitter:image" content="https://example.com/twitter-image.jpg">
+```
+When OG tags are present, Twitter falls back to them for most fields — but `twitter:card` is still required.
+## hreflang
+RFC 5646 (BCP 47) language tags + ISO 3166-1 alpha-2 region codes.
+### Format
+```
+<language-subtag>[-<region-subtag>]
+```
+Valid:
+- `en`, `en-US`, `en-GB`, `pl`, `pt-BR`, `zh-Hant`, `sr-Cyrl`
+Invalid:
+- `en_US` (underscore)
+- `EN-us` (case inconsistent — prefer lowercase language, uppercase region)
+- `english` (not a code)
+- `uk` is **Ukrainian**, not "UK English" (common confusion — `en-GB` is correct for British English)
+### Implementation
+Every locale version MUST include hreflang for every other locale, including itself, plus `x-default`:
+```html
+<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="pl"    href="https://example.com/pl/page">
+<link rel="alternate" hreflang="x-default" href="https://example.com/en-us/page">
+```
+### Bidirectionality
+If page A links to page B via hreflang, page B MUST link back to page A. Broken bidirectionality is ignored by Google — a HIGH-severity issue.
+### x-default
+Fallback for users whose language doesn't match any listed locale. Usually points to the default/main version (often English).
+## Validation
+The W3C provides an online validator: https://validator.w3.org/ — but the `seo-validate` skill targets static source analysis, not rendered HTML validation.
+For runtime validation, use:
+- `html-validate` (npm)
+- `htmlhint`
+- Built-in linters in Next.js, Nuxt, Astro
+## References
+- HTML Living Standard: https://html.spec.whatwg.org/
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- BCP 47 (RFC 5646): https://datatracker.ietf.org/doc/html/rfc5646
+- ISO 3166-1: https://www.iso.org/iso-3166-country-codes.html
+- Open Graph Protocol: https://ogp.me/
+- Google Search Central (title/description/canonical): https://developers.google.com/search/docs