From 8569a31321e770ea93a7941a4bc265a97d27a53a Mon Sep 17 00:00:00 2001
From: Bissbert <43237892+Bissbert@users.noreply.github.com>
Date: Mon, 11 May 2026 12:31:12 +0700
Subject: [PATCH 1/3] =?UTF-8?q?feat(seo):=20wave=201=20=E2=80=94=20fix=20i?=
 =?UTF-8?q?ndexing=20gap=20with=20knowledge=20subdomain?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six-agent SEO audit (audits/seo-2026-05/) diagnosed why gemmology.dev is
indexed worse than knowledge.gemmology.dev despite being the better
product: 48% of sitemap URLs were /og/ image templates and high-value
surfaces (/tools, /quiz, /playground) were client:load React shells
with no server-rendered prose. This wave addresses the structural
gap; v3 will layer keyword-clustered content on top.

Sitemap & indexability (W1, W2):
- astro.config.mjs: filter excludes /og/, /og-image/, /study/review,
  /study/settings; drop priority/changefreq (Google ignores since 2023)
- /og/learn, /og/minerals, /og-image: noindex,nofollow meta added
- Result: sitemap 910 → 466 URLs (zero /og/, zero /study/)

Tool pages SSG prose + schema (W3+W4):
- 7 tool pages now have 581–1326 server-rendered body words each
  (was 0–28 words); 3 paragraphs covering definition, method, and
  diagnostic application with named gem examples
- New ToolsSchema.astro component emits SoftwareApplication JSON-LD
  on every tool page (applicationCategory EducationalApplication,
  free Offer, gemmology.dev creator)
- /tools/index gains h1, intro, static category nav before React island

Learn schema (W5, W6):
- /learn/index: Course (FGA Diploma prep, 8 categories, PT100H workload)
  + CollectionPage with ItemList of all 138 articles + BreadcrumbList
- LearnSchema.astro: BreadcrumbList fragment URL bug fixed (was
  emitting /learn#fundamentals as a crumb), datePublished now wired
  through from new publishedAt content-collection field, hasPart Quiz
  emitted when an article has curated pretest questions
- src/content/config.ts: publishedAt field added to learn collection

Quiz hub (W7):
- 250-word SSG intro with all 8 categories listed statically
- Course JSON-LD with 8 hasCourseInstance entries + Quiz JSON-LD
- /quiz/ now returns 541 body words (was 30)

About page E-E-A-T (W8):
- Visible Maintainers & Editors block with credentials list
- Person JSON-LD via extended StructuredData component
- TODO(author) markers for real name+credential before deploy

Verification:
- npm run build: 912 pages, clean
- Sitemap: 466 URLs, zero junk paths
- All key pages emit valid JSON-LD (homepage 2, /learn 3, /quiz 2,
  /tools 1, /about 3 blocks)
- 441 /og/ pages all carry noindex,nofollow

Audit corpus: workspace/gemmology.dev/audits/seo-2026-05/
---
 astro.config.mjs                        |  28 ++----
 src/components/seo/LearnSchema.astro    |  57 +++++++++--
 src/components/seo/StructuredData.astro |  50 +++++++++-
 src/components/seo/ToolsSchema.astro    |  49 ++++++++++
 src/content/config.ts                   |   1 +
 src/pages/about.astro                   |  35 +++++++
 src/pages/learn/[...slug].astro         |   6 ++
 src/pages/learn/index.astro             |  77 +++++++++++++++
 src/pages/og-image.astro                |   1 +
 src/pages/og/learn/[...slug].astro      |   1 +
 src/pages/og/minerals/[slug].astro      |   1 +
 src/pages/quiz/index.astro              | 121 ++++++++++++++++++++++--
 src/pages/tools/advanced.astro          |  69 +++++++++++++-
 src/pages/tools/conversions.astro       |  63 +++++++++++-
 src/pages/tools/identification.astro    |  68 ++++++++++++-
 src/pages/tools/index.astro             | 108 ++++++++++++++++++++-
 src/pages/tools/lab.astro               |  73 +++++++++++++-
 src/pages/tools/measurement.astro       |  80 +++++++++++++++-
 src/pages/tools/optical.astro           |  82 +++++++++++++++-
 19 files changed, 905 insertions(+), 65 deletions(-)
 create mode 100644 src/components/seo/ToolsSchema.astro

diff --git a/astro.config.mjs b/astro.config.mjs
index 44acfbf..e18eec9 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -22,29 +22,13 @@ export default defineConfig({
     react(),
     tailwind(),
     sitemap({
-      filter: (page) => !page.includes('/admin'),
-      changefreq: 'weekly',
-      priority: 0.7,
+      filter: (page) =>
+        !page.includes('/admin') &&
+        !page.includes('/og/') &&
+        !page.includes('/og-image/') &&
+        !page.includes('/study/review') &&
+        !page.includes('/study/settings'),
       lastmod: new Date(),
-      serialize(item) {
-        // Boost priority/lastmod for hub pages and canonical references
-        if (item.url === 'https://gemmology.dev/' ||
-            item.url === 'https://gemmology.dev/gallery/' ||
-            item.url === 'https://gemmology.dev/learn/') {
-          item.priority = 1.0;
-          item.changefreq = 'weekly';
-        } else if (/\/minerals\/[^/]+\/$/.test(item.url)) {
-          item.priority = 0.8;
-          item.changefreq = 'monthly';
-        } else if (/\/learn\//.test(item.url)) {
-          item.priority = 0.7;
-          item.changefreq = 'monthly';
-        } else if (/\/docs\//.test(item.url)) {
-          item.priority = 0.5;
-          item.changefreq = 'monthly';
-        }
-        return item;
-      },
     }),
   ],
   vite: {
diff --git a/src/components/seo/LearnSchema.astro b/src/components/seo/LearnSchema.astro
index 1dddf00..14588fc 100644
--- a/src/components/seo/LearnSchema.astro
+++ b/src/components/seo/LearnSchema.astro
@@ -4,6 +4,11 @@
  * Improves SEO and enables rich results in search engines
  */
 
+interface PretestQuestion {
+  questionText: string;
+  correctAnswer: string;
+}
+
 interface Props {
   title: string;
   description: string;
@@ -15,9 +20,25 @@ interface Props {
   datePublished?: string;
   /** ISO 8601 datetime — when the article was last meaningfully updated. */
   dateModified?: string;
+  /** Number of pretest questions available for this article. */
+  pretestQuestionCount?: number;
+  /** Pretest question data for schema serialisation. */
+  pretestQuestions?: PretestQuestion[];
 }
 
-const { title, description, category, subcategory, difficulty, slug, datePublished, dateModified } = Astro.props;
+const {
+  title,
+  description,
+  category,
+  subcategory,
+  difficulty,
+  slug,
+  datePublished,
+  dateModified,
+  pretestQuestionCount = 0,
+  pretestQuestions = [],
+} = Astro.props;
+
 const url = `https://gemmology.dev/learn/${slug}`;
 
 // Helper to format category names
@@ -28,6 +49,22 @@ function formatName(name: string): string {
     .join(' ');
 }
 
+// Build hasPart Quiz node when pretest questions are available
+const quizNode = pretestQuestionCount > 0
+  ? {
+      "@type": "Quiz",
+      "name": `Pretest: ${title}`,
+      "educationalLevel": "Intermediate",
+      "numberOfQuestions": pretestQuestionCount,
+      "about": { "@type": "Thing", "name": title },
+      "hasPart": pretestQuestions.map(q => ({
+        "@type": "Question",
+        "name": q.questionText,
+        "acceptedAnswer": { "@type": "Answer", "text": q.correctAnswer },
+      })),
+    }
+  : null;
+
 // Use combined LearningResource + Article so Google can pick either rich-result type
 const articleSchema = {
   "@context": "https://schema.org",
@@ -64,34 +101,36 @@ const articleSchema = {
   },
   ...(datePublished ? { "datePublished": datePublished } : {}),
   ...(dateModified ? { "dateModified": dateModified } : {}),
+  ...(quizNode ? { "hasPart": quizNode } : {}),
 };
 
-// Build breadcrumb from category/subcategory
+// Build BreadcrumbList — no fragment URLs (Google rejects them).
+// Chain: Home → Learn → [subcategory overview if present →] Article
 const breadcrumbItems = [
   { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://gemmology.dev" },
   { "@type": "ListItem", "position": 2, "name": "Learn", "item": "https://gemmology.dev/learn" },
-  { "@type": "ListItem", "position": 3, "name": formatName(category), "item": `https://gemmology.dev/learn#${category}` },
 ];
 
 if (subcategory) {
+  // Position 3: article page (subcategory is visible-only; no clean URL to use here)
   breadcrumbItems.push({
     "@type": "ListItem",
-    "position": 4,
+    "position": 3,
     "name": formatName(subcategory),
-    "item": url
+    "item": url,
   });
   breadcrumbItems.push({
     "@type": "ListItem",
-    "position": 5,
+    "position": 4,
     "name": title,
-    "item": url
+    "item": url,
   });
 } else {
   breadcrumbItems.push({
     "@type": "ListItem",
-    "position": 4,
+    "position": 3,
     "name": title,
-    "item": url
+    "item": url,
   });
 }
 
diff --git a/src/components/seo/StructuredData.astro b/src/components/seo/StructuredData.astro
index 7441339..2249ce0 100644
--- a/src/components/seo/StructuredData.astro
+++ b/src/components/seo/StructuredData.astro
@@ -1,6 +1,6 @@
 ---
 /**
- * StructuredData - emit a BreadcrumbList plus optional WebPage JSON-LD.
+ * StructuredData - emit a BreadcrumbList, optional WebPage, and optional Person JSON-LD.
  * Use for non-mineral / non-learn pages that still benefit from breadcrumbs.
  */
 
@@ -9,6 +9,13 @@ interface Crumb {
   url: string;
 }
 
+interface PersonData {
+  name: string;
+  jobTitle?: string;
+  credentials?: string[];
+  sameAs?: string[];
+}
+
 interface Props {
   breadcrumbs?: Crumb[];
   webPage?: {
@@ -16,9 +23,15 @@ interface Props {
     description?: string;
     url: string;
   };
+  /**
+   * Optional Person JSON-LD — used on /about to signal E-E-A-T authorship.
+   * TODO(author): replace with real maintainer name + credentials before deploy
+   * (placeholder values are defined in src/pages/about.astro)
+   */
+  person?: PersonData;
 }
 
-const { breadcrumbs = [], webPage } = Astro.props;
+const { breadcrumbs = [], webPage, person } = Astro.props;
 
 const breadcrumbSchema = breadcrumbs.length > 0
   ? {
@@ -48,7 +61,40 @@ const webPageSchema = webPage
       },
     }
   : null;
+
+const personSchema = person
+  ? {
+      "@context": "https://schema.org",
+      "@type": "Person",
+      name: person.name,
+      ...(person.jobTitle ? { jobTitle: person.jobTitle } : {}),
+      knowsAbout: [
+        "Gemmology",
+        "Mineralogy",
+        "Crystallography",
+        "Gemstone identification",
+      ],
+      ...(person.credentials && person.credentials.length > 0
+        ? {
+            hasCredential: person.credentials.map((c) => ({
+              "@type": "EducationalOccupationalCredential",
+              credentialCategory: "certificate",
+              name: c,
+            })),
+          }
+        : {}),
+      ...(person.sameAs && person.sameAs.length > 0
+        ? { sameAs: person.sameAs }
+        : {}),
+      worksFor: {
+        "@type": "Organization",
+        name: "gemmology.dev",
+        url: "https://gemmology.dev",
+      },
+    }
+  : null;
 ---
 
 {breadcrumbSchema && <script type="application/ld+json" set:html={JSON.stringify(breadcrumbSchema)} />}
 {webPageSchema && <script type="application/ld+json" set:html={JSON.stringify(webPageSchema)} />}
+{personSchema && <script type="application/ld+json" set:html={JSON.stringify(personSchema)} />}
diff --git a/src/components/seo/ToolsSchema.astro b/src/components/seo/ToolsSchema.astro
new file mode 100644
index 0000000..8d45015
--- /dev/null
+++ b/src/components/seo/ToolsSchema.astro
@@ -0,0 +1,49 @@
+---
+/**
+ * ToolsSchema — JSON-LD SoftwareApplication structured data for tool category pages.
+ * Emit via <ToolsSchema slot="head" ... /> inside a BaseLayout to inject into <head>.
+ */
+
+interface ToolItem {
+  name: string;
+  description: string;
+}
+
+interface Props {
+  category: string;
+  name: string;
+  description: string;
+  tools: ToolItem[];
+  url: string;
+}
+
+const { category, name, description, tools, url } = Astro.props;
+
+const schema = {
+  "@context": "https://schema.org",
+  "@type": "SoftwareApplication",
+  "name": name,
+  "description": description,
+  "url": url,
+  "applicationCategory": "EducationalApplication",
+  "applicationSubCategory": category,
+  "operatingSystem": "Any (web-based)",
+  "offers": {
+    "@type": "Offer",
+    "price": "0",
+    "priceCurrency": "USD"
+  },
+  "creator": {
+    "@type": "Organization",
+    "name": "gemmology.dev",
+    "url": "https://gemmology.dev"
+  },
+  "featureList": tools.map(t => t.name).join(", "),
+  "audience": {
+    "@type": "EducationalAudience",
+    "educationalRole": "student"
+  }
+};
+---
+
+<script type="application/ld+json" set:html={JSON.stringify(schema)} />
diff --git a/src/content/config.ts b/src/content/config.ts
index 4c8130e..c27d272 100644
--- a/src/content/config.ts
+++ b/src/content/config.ts
@@ -176,6 +176,7 @@ const learnCollection = defineCollection({
     author: z.string().optional(),
     reviewedBy: z.string().optional(),
     reviewedAt: z.string().optional(),
+    publishedAt: z.string().optional(),
     sections: z.array(sectionSchema),
   }),
 });
diff --git a/src/pages/about.astro b/src/pages/about.astro
index bf0fffa..80d992d 100644
--- a/src/pages/about.astro
+++ b/src/pages/about.astro
@@ -7,12 +7,19 @@ import { getSiteStats } from '../lib/stats';
 import StructuredData from '../components/seo/StructuredData.astro';
 
 const { familyCount, expressionCount } = await getSiteStats();
+
+// TODO(author): replace with real maintainer name + credentials before deploy
+const AUTHOR_NAME       = "Editorial Team, gemmology.dev";
+const AUTHOR_TITLE      = "Editor";
+const AUTHOR_CREDENTIALS = ["FGA (placeholder)", "Gem-A graduate (placeholder)"];
+const AUTHOR_SAMEAS     = ["https://github.com/Bissbert/gemmology-dev"];
 ---
 
 <BaseLayout
   title="About"
   description="About gemmology.dev: an open, FGA-aligned reference and study toolkit for coloured gemstones, with editorial standards and source attribution."
 >
+  <!-- TODO(author): replace with real maintainer name + credentials before deploy -->
   <StructuredData
     slot="head"
     breadcrumbs={[
@@ -24,6 +31,12 @@ const { familyCount, expressionCount } = await getSiteStats();
       description: 'Editorial standards, sourcing, and contributors behind gemmology.dev.',
       url: 'https://gemmology.dev/about/',
     }}
+    person={{
+      name: AUTHOR_NAME,
+      jobTitle: AUTHOR_TITLE,
+      credentials: AUTHOR_CREDENTIALS,
+      sameAs: AUTHOR_SAMEAS,
+    }}
   />
 
   <Container size="md" padding="lg">
@@ -40,6 +53,28 @@ const { familyCount, expressionCount } = await getSiteStats();
         free and open-source.
       </p>
 
+      <!-- TODO(author): replace with real maintainer name + credentials before deploy -->
+      <h2>Maintainers &amp; Editors</h2>
+      <p>
+        The following contributors are responsible for the accuracy and
+        currency of content on gemmology.dev.
+      </p>
+      <ul>
+        <li>
+          <strong>{AUTHOR_NAME}</strong>
+          {' '}—{' '}
+          <span>{AUTHOR_TITLE}</span>
+          <ul>
+            {AUTHOR_CREDENTIALS.map((cred) => (
+              <li>{cred}</li>
+            ))}
+          </ul>
+          <a href={AUTHOR_SAMEAS[0]} rel="noopener noreferrer">
+            {AUTHOR_SAMEAS[0]}
+          </a>
+        </li>
+      </ul>
+
       <h2>Who maintains this</h2>
       <p>
         gemmology.dev is maintained by the
diff --git a/src/pages/learn/[...slug].astro b/src/pages/learn/[...slug].astro
index 70a4b87..2107389 100644
--- a/src/pages/learn/[...slug].astro
+++ b/src/pages/learn/[...slug].astro
@@ -44,6 +44,9 @@ function resolveDateModified(): string {
 }
 
 const dateModified = resolveDateModified();
+// datePublished: use explicit publishedAt frontmatter, fall back to dateModified.
+const datePublished = data.publishedAt ?? dateModified;
+
 const dateModifiedDisplay = new Date(dateModified).toLocaleDateString('en-GB', {
   year: 'numeric',
   month: 'long',
@@ -181,7 +184,10 @@ const pretestQuestions: WidgetQuestion[] = articleQuestions
     subcategory={data.subcategory}
     difficulty={data.difficulty}
     slug={entry.id}
+    datePublished={datePublished}
     dateModified={dateModified}
+    pretestQuestionCount={pretestQuestions.length}
+    pretestQuestions={pretestQuestions}
   />
   <Container size="md" padding="md">
     <Breadcrumb items={breadcrumbItems} />
diff --git a/src/pages/learn/index.astro b/src/pages/learn/index.astro
index da7e7ec..1a58f62 100644
--- a/src/pages/learn/index.astro
+++ b/src/pages/learn/index.astro
@@ -153,6 +153,80 @@ const startHereTopics = startHereSlugs
 
 const totalTopicCount = topics.length;
 
+// -----------------------------------------------------------------------
+// JSON-LD schema objects for the learn hub
+// -----------------------------------------------------------------------
+
+const courseSchema = {
+  "@context": "https://schema.org",
+  "@type": "Course",
+  "name": "Gemmology: FGA-aligned curriculum",
+  "description": "FGA curriculum-aligned content covering crystallography, physical and optical properties, inclusions, treatments, and synthetics.",
+  "provider": {
+    "@type": "Organization",
+    "name": "gemmology.dev",
+    "url": "https://gemmology.dev"
+  },
+  "educationalCredentialAwarded": {
+    "@type": "EducationalOccupationalCredential",
+    "name": "FGA Diploma Preparation",
+    "credentialCategory": "certificate"
+  },
+  "teaches": [
+    "Crystal systems",
+    "Equipment usage",
+    "Gem species identification",
+    "Diagnostic procedures",
+    "Optical phenomena",
+    "Geographic origin",
+    "Market and grading",
+    "Care and durability"
+  ],
+  "inLanguage": "en",
+  "isAccessibleForFree": true,
+  "hasCourseInstance": {
+    "@type": "CourseInstance",
+    "courseMode": "online",
+    "courseWorkload": "PT100H"
+  }
+};
+
+const collectionPageSchema = {
+  "@context": "https://schema.org",
+  "@type": "CollectionPage",
+  "name": "Learn Gemmology",
+  "description": "FGA curriculum-aligned content on crystallography and gemmology.",
+  "url": "https://gemmology.dev/learn/",
+  "mainEntity": {
+    "@type": "ItemList",
+    "itemListElement": topics.map((topic, i) => ({
+      "@type": "ListItem",
+      "position": i + 1,
+      "url": `https://gemmology.dev${topic.href}/`,
+      "name": topic.title
+    }))
+  }
+};
+
+const breadcrumbSchema = {
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+    {
+      "@type": "ListItem",
+      "position": 1,
+      "name": "Home",
+      "item": "https://gemmology.dev"
+    },
+    {
+      "@type": "ListItem",
+      "position": 2,
+      "name": "Learn",
+      "item": "https://gemmology.dev/learn/"
+    }
+  ]
+};
+
 // Icon SVG paths (shared with topic cards)
 const iconPaths: Record<string, string> = {
   cube: 'M20 7l-8-4-8 4m16 0l-8 4m8-4v10l-8 4m0-10L4 7m8 4v10M4 7v10l8 4',
@@ -176,6 +250,9 @@ const iconPaths: Record<string, string> = {
   title="Learn"
   description="FGA curriculum-aligned content on crystallography and gemmology."
 >
+  <script type="application/ld+json" set:html={JSON.stringify(courseSchema)} slot="head" />
+  <script type="application/ld+json" set:html={JSON.stringify(collectionPageSchema)} slot="head" />
+  <script type="application/ld+json" set:html={JSON.stringify(breadcrumbSchema)} slot="head" />
   <div class="bg-gradient-to-b from-crystal-50 to-white min-h-screen">
     <Container size="xl" padding="md">
       <!-- Header -->
diff --git a/src/pages/og-image.astro b/src/pages/og-image.astro
index 8e8e973..7d3f4d3 100644
--- a/src/pages/og-image.astro
+++ b/src/pages/og-image.astro
@@ -11,6 +11,7 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=1200, height=630">
+  <meta name="robots" content="noindex, nofollow">
   <title>gemmology.dev OG Image</title>
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
diff --git a/src/pages/og/learn/[...slug].astro b/src/pages/og/learn/[...slug].astro
index f858b80..717b459 100644
--- a/src/pages/og/learn/[...slug].astro
+++ b/src/pages/og/learn/[...slug].astro
@@ -73,6 +73,7 @@ const categoryName = categoryNames[category] || category;
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=1200, height=630">
+  <meta name="robots" content="noindex, nofollow">
   <title>{title} - Gemmology OG</title>
   <style>
     /* Font declarations */
diff --git a/src/pages/og/minerals/[slug].astro b/src/pages/og/minerals/[slug].astro
index 800fe80..f3bfb95 100644
--- a/src/pages/og/minerals/[slug].astro
+++ b/src/pages/og/minerals/[slug].astro
@@ -84,6 +84,7 @@ const cdlFontSize = cdlLength > 80 ? '16px' : cdlLength > 60 ? '18px' : '20px';
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=1200, height=630">
+  <meta name="robots" content="noindex, nofollow">
   <title>{mineral.name} - Gemmology OG</title>
   <style>
     /* Font declarations */
diff --git a/src/pages/quiz/index.astro b/src/pages/quiz/index.astro
index 72f4edc..b8783d4 100644
--- a/src/pages/quiz/index.astro
+++ b/src/pages/quiz/index.astro
@@ -1,6 +1,6 @@
 ---
 /**
- * Quiz hub page.
+ * Quiz hub page — SSG intro prose + Course/Quiz JSON-LD.
  */
 import { getCollection } from 'astro:content';
 import BaseLayout from '../../layouts/BaseLayout.astro';
@@ -19,11 +19,120 @@ const entries: LearnEntry[] = learnEntries.map(entry => ({
     sections: entry.data.sections,
   },
 }));
+
+const pageDescription =
+  'Practice and exam-mode quizzes aligned with the FGA diploma curriculum, covering all eight gemmology topic areas with SM-2 spaced-repetition scheduling.';
+
+const categories = [
+  { name: 'Fundamentals', description: 'Crystal systems, optical properties, and physical properties.' },
+  { name: 'Equipment', description: 'Refractometer, spectroscope, and polariscope techniques.' },
+  { name: 'Species', description: 'Individual gemstone identification and characteristic properties.' },
+  { name: 'Identification', description: 'Diagnostic procedures and systematic testing sequences.' },
+  { name: 'Phenomena', description: 'Asterism, chatoyancy, colour change, adularescence, and related effects.' },
+  { name: 'Origin', description: 'Geographic origin determination and provenance indicators.' },
+  { name: 'Market & Grading', description: 'Grading standards, valuation principles, and treatment disclosure.' },
+  { name: 'Care & Durability', description: 'Gem care, safe cleaning methods, and setting compatibility.' },
+];
+
+const courseSchema = {
+  '@context': 'https://schema.org',
+  '@type': 'Course',
+  name: 'Gemmology Practice Quiz',
+  description: pageDescription,
+  provider: {
+    '@type': 'Organization',
+    name: 'gemmology.dev',
+    url: 'https://gemmology.dev',
+  },
+  educationalCredentialAwarded: 'FGA Diploma exam preparation',
+  courseMode: ['online'],
+  educationalLevel: 'Intermediate',
+  isAccessibleForFree: true,
+  inLanguage: 'en',
+  hasCourseInstance: categories.map(cat => ({
+    '@type': 'CourseInstance',
+    courseMode: 'online',
+    name: cat.name,
+  })),
+};
+
+const quizSchema = {
+  '@context': 'https://schema.org',
+  '@type': 'Quiz',
+  name: 'Gemmology Quiz Bank',
+  about: {
+    '@type': 'Thing',
+    name: 'Gemmology',
+  },
+  educationalLevel: 'Intermediate',
+  audience: {
+    '@type': 'EducationalAudience',
+    educationalRole: 'student',
+  },
+};
 ---
 
-<BaseLayout
-  title="Quiz"
-  description="Test your gemmology knowledge with interactive quizzes covering crystallography, optical properties, treatments, and more."
->
-  <QuizPage client:load learnEntries={entries} />
+<BaseLayout title="Quiz" description={pageDescription}>
+  <Fragment slot="head">
+    <script type="application/ld+json" set:html={JSON.stringify(courseSchema)} />
+    <script type="application/ld+json" set:html={JSON.stringify(quizSchema)} />
+  </Fragment>
+
+  <div class="min-h-screen bg-gradient-to-b from-slate-50 to-white">
+    <div class="max-w-6xl mx-auto px-4 sm:px-6 lg:px-8 py-12">
+
+      <header class="mb-8">
+        <h1 class="text-3xl font-bold text-slate-900">Gemmology Quiz</h1>
+        <p class="text-slate-600 mt-2 text-lg">
+          Test and consolidate your gemmology knowledge across all eight FGA-aligned topic areas.
+        </p>
+      </header>
+
+      <section class="prose prose-slate max-w-none mb-10">
+        <p>
+          The gemmology quiz draws questions from a curated bank aligned with the
+          <strong>FGA diploma curriculum</strong>. Questions span eight topic areas: Fundamentals
+          (crystal systems, optical and physical properties), Equipment (refractometer,
+          spectroscope, polariscope), Species (individual gem identification), Identification
+          (diagnostic procedures and testing sequences), Phenomena (asterism, chatoyancy, colour
+          change), Origin (geographic provenance indicators), Market &amp; Grading (standards,
+          valuation, and treatments), and Care &amp; Durability (cleaning, setting compatibility).
+          Each question links back to its source article in the Learn section so you can review the
+          underlying theory immediately after answering.
+        </p>
+
+        <p>
+          Two modes are available. <strong>Practice mode</strong> delivers immediate feedback after
+          each answer, shows a rationale panel explaining why the correct answer is right and why
+          each distractor is wrong, and optionally invites a confidence tap (Unsure / Fairly sure /
+          Certain) before revealing the result. <strong>Exam mode</strong> simulates a timed
+          assessment with configurable durations (15 to 90 minutes), no in-question feedback, a
+          navigation grid for flagging questions, and a detailed results breakdown at the end
+          including per-category scores, letter grade, and pass/fail at the 70&nbsp;% FGA threshold.
+        </p>
+
+        <p>
+          The quiz engine uses <strong>SM-2 spaced-repetition scheduling</strong>. Every answer
+          updates an interval and ease factor for that question; due items are prioritised at the
+          start of each new session, ensuring you spend revision time on material you are most
+          likely to forget rather than questions already committed to long-term memory. A
+          &ldquo;Review Now&rdquo; shortcut on the study dashboard surfaces all currently due
+          items with no setup screen, making it easy to fit a focused five-minute review into any
+          break between study sessions.
+        </p>
+
+        <h2 class="text-xl font-semibold text-slate-800 mt-8 mb-3">Quiz categories</h2>
+        <ul class="space-y-1">
+          {categories.map(cat => (
+            <li class="text-slate-700">
+              <strong>{cat.name}:</strong> {cat.description}
+            </li>
+          ))}
+        </ul>
+      </section>
+
+      <QuizPage client:load learnEntries={entries} />
+
+    </div>
+  </div>
 </BaseLayout>
diff --git a/src/pages/tools/advanced.astro b/src/pages/tools/advanced.astro
index dd7dc7e..cc0f9aa 100644
--- a/src/pages/tools/advanced.astro
+++ b/src/pages/tools/advanced.astro
@@ -4,20 +4,81 @@
  */
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import { AdvancedTools } from '../../components/advanced/AdvancedTools';
+import ToolsSchema from '../../components/seo/ToolsSchema.astro';
+
+const tools = [
+  { name: "Treatment Detection", description: "Reference table of observable features for 11 treatment types across common gem species" },
+  { name: "Treatment Wizard", description: "Evidence-weighted wizard: enter 18 observable clues to receive a confidence-banded treatment conclusion" },
+  { name: "Proportion Analyzer", description: "GIA cut-grade overlay for round brilliants with per-parameter band lookup against published thresholds" },
+];
 ---
 
 <BaseLayout
   title="Advanced Analysis"
-  description="Treatment detection, origin determination, and gemstone proportion analysis tools."
+  description="Advanced gemmological analysis tools: evidence-weighted treatment detection across 18 clues and 11 treatments, and a GIA cut-grade proportion analyzer for round brilliants."
 >
+  <ToolsSchema
+    slot="head"
+    name="Advanced Gemmological Analysis Tools"
+    description="Evidence-weighted treatment detection wizard covering 18 observable clues across 11 treatment types, plus a GIA cut-grade proportion analyzer with per-parameter band lookup for round brilliant diamonds."
+    category="Advanced Analysis"
+    url="https://gemmology.dev/tools/advanced"
+    tools={tools}
+  />
+
   <div class="min-h-screen bg-gradient-to-b from-slate-50 to-white py-12">
     <div class="max-w-6xl mx-auto px-4">
-      <div class="mb-8">
+
+      <header class="mb-8">
         <h1 class="text-3xl font-bold text-slate-900">Advanced Analysis</h1>
         <p class="text-slate-600 mt-2">
-          Advanced gemmological analysis tools including treatment detection reference, origin determination characteristics, and gemstone cut proportion analyzer.
+          Treatment detection and proportion analysis — the two areas of advanced gemmological assessment that require correlating multiple lines of evidence rather than reading a single instrument.
+        </p>
+      </header>
+
+      <section class="prose prose-slate max-w-none mb-8">
+        <p>
+          Treatment detection requires correlating multiple lines of evidence. Heat treatment
+          in corundum leaves characteristic stress fractures around rutile inclusions and
+          healed fingerprints, but not all heated stones show these features — a clean,
+          well-heated stone may show no internal evidence at all. Fracture filling in emerald
+          suppresses the fingerprint inclusions that would otherwise be visible under
+          magnification, but the filling material itself can be identified by its flash effect
+          and RI mismatch with the host. Diffusion treatment in sapphire concentrates
+          colour at the surface, visible as concentrated colour at facet edges when the stone
+          is immersed. Each treatment leaves a different combination of positive and negative
+          evidence, and confident treatment assessment depends on accumulating independent
+          observations rather than relying on any single clue.
+        </p>
+        <p>
+          The treatment wizard on this page formalises this evidence-accumulation approach.
+          It covers 18 observable clues — including inclusion type, surface texture, colour
+          distribution, spectral absorption anomalies, fluorescence pattern, and magnification
+          features — mapped against 11 treatment categories: heat, fracture filling, surface
+          coating, diffusion, irradiation, oiling, waxing, bleaching, impregnation, laser
+          drilling, and flux healing. Each clue carries positive or negative evidence weights
+          for each treatment type. Submit the clues you have observed and the wizard sums the
+          weights per treatment, producing a confidence-banded conclusion — high confidence
+          when three or more independent indicators align, low confidence when evidence is
+          mixed or a single clue stands alone. This mirrors the reasoning process used in
+          major gemmological laboratories and makes the logic explicit rather than implicit.
         </p>
-      </div>
+        <p>
+          The proportion analyzer applies a different kind of multi-parameter assessment to
+          cut quality in round brilliant diamonds. The GIA cut-grade system evaluates seven
+          proportions independently: table percentage, total depth percentage, crown angle,
+          pavilion angle, girdle thickness, culet size, and star length. Each parameter falls
+          into one of five grade bands (Excellent, Very Good, Good, Fair, Poor) according to
+          published GIA thresholds, and the overall cut grade is determined by the
+          lowest-grading individual parameter. Enter the measured proportions from a
+          proportion scope or grading report and the tool displays the per-parameter band for
+          each value, highlights the limiting parameter, and returns the resulting cut grade.
+          Understanding which proportion is pulling the grade down — crown angle too shallow,
+          table too wide, or girdle too thick — gives a precise basis for cut-quality
+          assessment and client communication.
+        </p>
+      </section>
+
       <AdvancedTools client:load />
     </div>
   </div>
diff --git a/src/pages/tools/conversions.astro b/src/pages/tools/conversions.astro
index 17c02c3..127a4f5 100644
--- a/src/pages/tools/conversions.astro
+++ b/src/pages/tools/conversions.astro
@@ -4,20 +4,75 @@
  */
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import { ConversionTools } from '../../components/calculator';
+import ToolsSchema from '../../components/seo/ToolsSchema.astro';
+
+const tools = [
+  { name: "Weight Converter", description: "Convert between metric carats, grams, milligrams, grains, and troy ounces" },
+  { name: "Length Converter", description: "Convert between millimetres and inches for caliper gem measurements" },
+  { name: "Temperature Converter", description: "Convert between Celsius and Fahrenheit for refractometer correction and SG water-density tables" },
+];
 ---
 
 <BaseLayout
   title="Unit Conversions"
-  description="Convert between carats, grams, millimeters, inches, Celsius, and Fahrenheit."
+  description="Gemmological unit converters for weight (carat, gram, milligram), length (mm, inch), and temperature (Celsius, Fahrenheit) — covering the metric carat standard, decimal-point carat trade usage, and temperature correction for SG and RI measurements."
 >
+  <ToolsSchema
+    slot="head"
+    name="Gemmological Unit Conversion Tools"
+    description="Unit converters for gemmological practice: weight in carats, grams, and milligrams; gem dimensions in millimetres and inches; temperature in Celsius and Fahrenheit for refractometer and specific gravity corrections."
+    category="Conversions"
+    url="https://gemmology.dev/tools/conversions"
+    tools={tools}
+  />
+
   <div class="min-h-screen bg-gradient-to-b from-slate-50 to-white py-12">
     <div class="max-w-6xl mx-auto px-4">
-      <div class="mb-8">
+
+      <header class="mb-8">
         <h1 class="text-3xl font-bold text-slate-900">Unit Conversions</h1>
         <p class="text-slate-600 mt-2">
-          Convert between carats, grams, millimeters, inches, Celsius, and Fahrenheit.
+          Weight, length, and temperature converters calibrated to the units actually used in gemmological measurement and gem trade.
+        </p>
+      </header>
+
+      <section class="prose prose-slate max-w-none mb-8">
+        <p>
+          The metric carat was standardised internationally in 1907 at exactly 200&nbsp;mg
+          (0.2&nbsp;g). Before that date, the carat varied by country — the old English carat
+          differed from the French, which differed from the Turkish — making gem weights in
+          historical records difficult to compare. The 1907 standard fixed the unit absolutely,
+          and today a 1.00&nbsp;ct stone means the same weight in every country. In trade, the
+          carat is subdivided into 100 points: a 0.50&nbsp;ct stone is described as
+          fifty points, a 0.35&nbsp;ct stone as thirty-five points. The weight converter on
+          this page handles carats, grams, milligrams, grains, and troy ounces — the full
+          range of units encountered when reading historic inventory records, laboratory
+          reports, and customs documentation.
+        </p>
+        <p>
+          Length conversion between millimetres and inches is a routine need when gem
+          dimensions measured with a metric caliper must be communicated in markets that use
+          imperial measurements, or when a published cutting diagram gives proportions in
+          inches that must be scaled to millimetres before use in the carat estimator. The
+          conversion is straightforward (1&nbsp;inch = 25.4&nbsp;mm exactly), but having a
+          dedicated converter eliminates the mental arithmetic error that can occur when
+          managing multiple measurements at once.
         </p>
-      </div>
+        <p>
+          Temperature conversion matters in two specific gemmological contexts. First, the
+          specific gravity calculation depends on the density of water at the temperature of
+          the liquid used during hydrostatic weighing: water is densest at 4&nbsp;&deg;C
+          (1.0000&nbsp;g/cm&sup3;) and becomes measurably less dense as temperature rises,
+          reaching 0.9957&nbsp;g/cm&sup3; at 30&nbsp;&deg;C. The SG calculator on the
+          Measurement page applies this water-density correction automatically, and the
+          temperature converter here lets you enter a Fahrenheit reading from a lab thermometer
+          and obtain the Celsius value needed for that correction. Second, some refractometer
+          reference tables and refractive index databases list temperature coefficients in
+          Fahrenheit; converting to Celsius before applying a temperature correction to an RI
+          reading ensures the adjustment is applied in the right direction and magnitude.
+        </p>
+      </section>
+
       <ConversionTools client:load />
     </div>
   </div>
diff --git a/src/pages/tools/identification.astro b/src/pages/tools/identification.astro
index a07a864..e51092d 100644
--- a/src/pages/tools/identification.astro
+++ b/src/pages/tools/identification.astro
@@ -4,20 +4,80 @@
  */
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import { IdentificationTools } from '../../components/identification/IdentificationTools';
+import ToolsSchema from '../../components/seo/ToolsSchema.astro';
+
+const tools = [
+  { name: "Gem Identifier", description: "Filter the 96-family mineral database by RI, SG, crystal system, and optic character to narrow a working identification" },
+];
 ---
 
 <BaseLayout
   title="Gem Identification"
-  description="Side-by-side gem comparison, Mohs hardness reference, and cleavage/fracture identification tools."
+  description="Systematic gem identification tool that filters 96 mineral families by refractive index, specific gravity, crystal system, and optic character — with natural, synthetic, simulant, and composite origin badges."
 >
+  <ToolsSchema
+    slot="head"
+    name="Gemmological Gem Identification Tool"
+    description="Systematic gem identification by filtering the 96-family mineral database across refractive index, specific gravity, crystal system, and optic character, with origin badges distinguishing natural, synthetic, simulant, and composite stones."
+    category="Identification"
+    url="https://gemmology.dev/tools/identification"
+    tools={tools}
+  />
+
   <div class="min-h-screen bg-gradient-to-b from-slate-50 to-white py-12">
     <div class="max-w-6xl mx-auto px-4">
-      <div class="mb-8">
+
+      <header class="mb-8">
         <h1 class="text-3xl font-bold text-slate-900">Gem Identification</h1>
         <p class="text-slate-600 mt-2">
-          Comprehensive identification tools including side-by-side gem comparison, Mohs hardness reference, and cleavage/fracture patterns.
+          A systematic, bias-resistant identification workflow that filters all 96 mineral families by quantitative properties before applying qualitative tests.
+        </p>
+      </header>
+
+      <section class="prose prose-slate max-w-none mb-8">
+        <p>
+          Systematic gem identification follows a fixed sequence to avoid confirmation bias.
+          Start with non-destructive observations — colour, transparency, lustre — then move
+          to refractive index, then specific gravity, then the spectroscope if the RI falls in
+          an ambiguous range. Only after these quantitative steps should qualitative tests
+          (Chelsea filter, fluorescence) be applied to confirm or refute a working hypothesis.
+          This sequence matches the FGA Diploma practical examination protocol, and it matters
+          because qualitative tests are sensitive to treatment, coating, and imitation —
+          whereas RI and SG are intrinsic physical constants of the material itself.
         </p>
-      </div>
+        <p>
+          The gem identifier on this page applies this logic directly. Enter the RI reading
+          from your refractometer, the SG value from hydrostatic weighing, the crystal system
+          if known from polariscope behaviour, and the optic character (singly refractive,
+          uniaxial, or biaxial). Each parameter constrains the search independently, and the
+          tool returns every family in the 96-entry mineral database that satisfies all the
+          criteria you supply simultaneously. You do not need to fill in every field — a single
+          RI reading already eliminates the majority of species, and adding SG typically
+          reduces the candidate list to three or fewer families. The underlying database
+          includes all 93 natural mineral families as well as 13 synthetic, 11 simulant, and
+          4 composite entries, so lookalike materials appear in the same results set as genuine
+          natural species.
+        </p>
+        <p>
+          Results are displayed with origin badges that immediately flag whether a matching
+          entry is a natural mineral, a lab-grown synthetic with the same chemical composition,
+          a simulant made from a different material, or a composite assembled stone. This
+          distinction is critical at the identification stage: a stone with an RI of 1.762 and
+          SG of 3.99 could be natural ruby, flux-grown synthetic ruby, or a garnet-topped
+          doublet — three very different commercial situations that require different follow-up
+          tests. Seeing all three in a single ranked results table prevents the common error
+          of stopping investigation once a plausible natural species is found.
+        </p>
+        <p>
+          After the identifier narrows the field, the results table provides direct links to
+          the relevant entries in the spectroscope band-matcher and UV fluorescence lookup, so
+          the next logical test is always one click away. This end-to-end workflow — from
+          first observation to a confirmed identification supported by multiple independent
+          properties — is the foundation of professional gemmological practice and the
+          standard taught at the Gemmological Association of Great Britain.
+        </p>
+      </section>
+
       <IdentificationTools client:load />
     </div>
   </div>
diff --git a/src/pages/tools/index.astro b/src/pages/tools/index.astro
index f9ffc79..e554d78 100644
--- a/src/pages/tools/index.astro
+++ b/src/pages/tools/index.astro
@@ -4,11 +4,113 @@
  */
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import { ToolsHub } from '../../components/tools/ToolsHub';
+import ToolsSchema from '../../components/seo/ToolsSchema.astro';
+
+const tools = [
+  { name: "Measurement & Calculation", description: "SG, RI, birefringence, critical angle, carat estimator, Hanneman shortcut" },
+  { name: "Optical Properties", description: "Dichroscope, polariscope, refractometer simulator, pleochroism reasoner, optic sign" },
+  { name: "Lab Equipment", description: "Spectroscope calculator, band-matcher, UV fluorescence lookup" },
+  { name: "Gem Identification", description: "Filtered database query across 96 mineral families" },
+  { name: "Advanced Analysis", description: "Treatment detection, treatment wizard, proportion analyzer with GIA cut grades" },
+  { name: "Unit Conversions", description: "Weight, length, and temperature converters for gemmological use" },
+];
 ---
 
 <BaseLayout
-  title="Tools"
-  description="Gemmological tools and calculators for professionals and students."
+  title="Gemmological Tools"
+  description="Free browser-based gemmological tools for measurement, optical testing, spectroscopy, identification, and unit conversion. Aligned with FGA curriculum."
 >
-  <ToolsHub client:load />
+  <ToolsSchema
+    slot="head"
+    name="Gemmological Tools — gemmology.dev"
+    description="Free browser-based tools for coloured-gemstone identification: specific gravity, refractive index, birefringence, spectroscope analysis, treatment detection, and more."
+    category="Gemmology"
+    url="https://gemmology.dev/tools"
+    tools={tools}
+  />
+
+  <div class="min-h-screen bg-gradient-to-b from-slate-50 to-white py-12">
+    <div class="max-w-6xl mx-auto px-4">
+
+      <header class="mb-8">
+        <h1 class="text-3xl font-bold text-slate-900">Gemmological Tools</h1>
+        <p class="text-slate-600 mt-2">
+          Free, browser-based instruments for coloured-gemstone identification, optical testing, and lab analysis — no login required.
+        </p>
+      </header>
+
+      <section class="prose prose-slate max-w-none mb-8">
+        <p>
+          This toolkit covers every quantitative and qualitative test a practising gemmologist needs
+          for systematic identification. All calculations run client-side in the browser using the
+          same mineral database that powers the mineral reference pages — 96 families including
+          natural species, lab-grown synthetics, simulants, and composite stones. No data is
+          transmitted to any server; readings stay on your device.
+        </p>
+        <p>
+          The tools are organised across six categories. Measurement &amp; Calculation handles the
+          two primary quantitative tests — specific gravity and refractive index — alongside
+          birefringence, critical angle, carat estimation, and the Hanneman/Hodgkinson over-the-limit
+          shortcut for stones with RI above 1.81. Optical Properties supports the polariscope and
+          dichroscope workflow, with a refractometer simulator, pleochroism reasoner, and optic-sign
+          determination. Lab Equipment covers spectroscope absorption-band reading, an inverse
+          band-matcher for species lookup, and UV fluorescence interpretation. Gem Identification
+          provides a filtered database query to narrow candidates by RI, SG, crystal system, and
+          optical character. Advanced Analysis integrates treatment-detection evidence weighting and
+          GIA cut-grade proportion analysis. Unit Conversions handles metric/troy/decimal-carat and
+          temperature scales used in refractometer corrections.
+        </p>
+        <p>
+          The workflow mirrors the FGA Diploma practical examination protocol: start with
+          non-destructive observations, then RI, then SG, then spectroscope for ambiguous cases, and
+          apply qualitative confirmatory tests last. Each tool includes a brief methodology note so
+          students building examination technique can understand not just the result but the reasoning
+          behind it.
+        </p>
+      </section>
+
+      <nav aria-label="Tool categories" class="mb-8">
+        <ul class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4 list-none p-0">
+          <li>
+            <a href="/tools/measurement" class="block p-4 rounded-lg border border-slate-200 hover:border-sky-400 hover:bg-sky-50 transition-colors">
+              <span class="font-semibold text-slate-900">Measurement &amp; Calculation</span>
+              <span class="block text-sm text-slate-600 mt-1">SG, RI, birefringence, critical angle, carat estimator, Hanneman shortcut</span>
+            </a>
+          </li>
+          <li>
+            <a href="/tools/optical" class="block p-4 rounded-lg border border-slate-200 hover:border-sky-400 hover:bg-sky-50 transition-colors">
+              <span class="font-semibold text-slate-900">Optical Properties</span>
+              <span class="block text-sm text-slate-600 mt-1">Dichroscope, polariscope, refractometer simulator, pleochroism reasoner, optic sign</span>
+            </a>
+          </li>
+          <li>
+            <a href="/tools/lab" class="block p-4 rounded-lg border border-slate-200 hover:border-sky-400 hover:bg-sky-50 transition-colors">
+              <span class="font-semibold text-slate-900">Lab Equipment</span>
+              <span class="block text-sm text-slate-600 mt-1">Spectroscope calculator, band-matcher, UV fluorescence lookup</span>
+            </a>
+          </li>
+          <li>
+            <a href="/tools/identification" class="block p-4 rounded-lg border border-slate-200 hover:border-sky-400 hover:bg-sky-50 transition-colors">
+              <span class="font-semibold text-slate-900">Gem Identification</span>
+              <span class="block text-sm text-slate-600 mt-1">Filtered database query across 96 mineral families</span>
+            </a>
+          </li>
+          <li>
+            <a href="/tools/advanced" class="block p-4 rounded-lg border border-slate-200 hover:border-sky-400 hover:bg-sky-50 transition-colors">
+              <span class="font-semibold text-slate-900">Advanced Analysis</span>
+              <span class="block text-sm text-slate-600 mt-1">Treatment detection, treatment wizard, proportion analyzer with GIA cut grades</span>
+            </a>
+          </li>
+          <li>
+            <a href="/tools/conversions" class="block p-4 rounded-lg border border-slate-200 hover:border-sky-400 hover:bg-sky-50 transition-colors">
+              <span class="font-semibold text-slate-900">Unit Conversions</span>
+              <span class="block text-sm text-slate-600 mt-1">Weight, length, and temperature converters for gemmological use</span>
+            </a>
+          </li>
+        </ul>
+      </nav>
+
+      <ToolsHub client:load />
+    </div>
+  </div>
 </BaseLayout>
diff --git a/src/pages/tools/lab.astro b/src/pages/tools/lab.astro
index 47f992e..e9ff063 100644
--- a/src/pages/tools/lab.astro
+++ b/src/pages/tools/lab.astro
@@ -4,20 +4,85 @@
  */
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import { LabTools } from '../../components/lab/LabTools';
+import ToolsSchema from '../../components/seo/ToolsSchema.astro';
+
+const tools = [
+  { name: "Spectroscope Calculator", description: "Display absorption bands for 16 gem species from the reference table" },
+  { name: "Spectroscope Band-Matcher", description: "Enter observed wavelengths to identify the gem species by inverse lookup" },
+  { name: "UV Fluorescence Lookup", description: "Parse LWUV and SWUV reactions with intensity scoring and phosphorescence flag" },
+];
 ---
 
 <BaseLayout
   title="Lab Equipment"
-  description="Reference tools for gemmological lab equipment: Chelsea filter, spectroscope, and heavy liquid SG separation."
+  description="Gemmological lab tools for spectroscope absorption-band reference, inverse band-matching across 16 species, and UV fluorescence interpretation with LWUV/SWUV intensity scoring."
 >
+  <ToolsSchema
+    slot="head"
+    name="Gemmological Lab Equipment Tools"
+    description="Browser-based lab reference tools for spectroscope absorption bands, inverse band-matching across 16 gem species, and UV fluorescence parsing with LWUV/SWUV/phosphorescence intensity scoring."
+    category="Lab Equipment"
+    url="https://gemmology.dev/tools/lab"
+    tools={tools}
+  />
+
   <div class="min-h-screen bg-gradient-to-b from-slate-50 to-white py-12">
     <div class="max-w-6xl mx-auto px-4">
-      <div class="mb-8">
+
+      <header class="mb-8">
         <h1 class="text-3xl font-bold text-slate-900">Lab Equipment</h1>
         <p class="text-slate-600 mt-2">
-          Reference tools for gemological lab equipment including Chelsea filter reactions, spectroscope absorption lines, and heavy liquid separation.
+          Spectroscope reference, inverse band-matching, and UV fluorescence interpretation — the three lab-instrument tools used alongside RI and SG to confirm a gemmological identification.
+        </p>
+      </header>
+
+      <section class="prose prose-slate max-w-none mb-8">
+        <p>
+          The spectroscope records which wavelengths of visible light a gem absorbs. Strong
+          selective absorption bands are diagnostic: the 693&nbsp;nm doublet in ruby, the
+          450&nbsp;nm band in synthetic blue spinel, the 415&nbsp;nm line in cape diamonds.
+          Each species produces a characteristic pattern determined by the transition-metal
+          impurities or rare-earth elements present in its crystal structure. The spectroscope
+          calculator on this page displays the expected absorption pattern for 16 commonly
+          encountered gem species, drawing from a curated reference table that lists band
+          positions, relative strengths, and the diagnostic significance of each line. Viewing
+          known patterns before working at the bench helps calibrate the eye and sets a
+          reliable expectation for what a positive identification looks like.
         </p>
-      </div>
+        <p>
+          The band-matcher inverts this workflow. Rather than looking up a known species and
+          reading off its bands, you enter the wavelengths you actually observe and the tool
+          returns the species whose reference pattern best matches your input. Matching is
+          tolerance-windowed — a band recorded at 692&nbsp;nm will still match the 693&nbsp;nm
+          ruby reference — and selective diagnostic bands are weighted more heavily than broad
+          general-absorption regions. This makes the band-matcher especially useful when a
+          stone shows one strong diagnostic line alongside several weaker features that might
+          be confused for another species. The output lists confidence-ranked candidates, not a
+          single forced answer, which mirrors the conditional reasoning a trained gemmologist
+          applies at the bench.
+        </p>
+        <p>
+          UV fluorescence adds a complementary data point without any contact with the stone.
+          A strong blue long-wave (LWUV) reaction in diamond, absent under short-wave (SWUV),
+          points away from moissanite or cubic zirconia. Conversely, a strong SWUV reaction
+          with weak or absent LWUV is characteristic of certain synthetic ruby flux products.
+          The UV fluorescence lookup parses the freeform fluorescence descriptions stored in
+          the mineral database — for example, "inert to strong blue LWUV, weak yellow SWUV" —
+          into structured fields: LWUV colour and intensity, SWUV colour and intensity, and a
+          phosphorescence flag for materials such as natural hyalite opal that continue to
+          glow after the UV source is removed. Intensity is scored on a four-step scale
+          (inert, weak, moderate, strong) to allow ranked comparison across species.
+        </p>
+        <p>
+          Together the spectroscope and UV fluorescence instruments cover complementary parts
+          of the electromagnetic spectrum and together with RI and SG they form the core
+          analytical toolkit of the FGA Diploma practical examination. These tools are designed
+          to function as both learning aids and bench references: they explain the underlying
+          physics, display the reference data, and support the step-by-step reasoning process
+          that moves an observation toward a confident, defensible identification.
+        </p>
+      </section>
+
       <LabTools client:load />
     </div>
   </div>
diff --git a/src/pages/tools/measurement.astro b/src/pages/tools/measurement.astro
index 412eb31..2dbf85a 100644
--- a/src/pages/tools/measurement.astro
+++ b/src/pages/tools/measurement.astro
@@ -4,20 +4,92 @@
  */
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import { MeasurementTools } from '../../components/calculator';
+import ToolsSchema from '../../components/seo/ToolsSchema.astro';
+
+const tools = [
+  { name: "Specific Gravity Calculator", description: "Hydrostatic weighing with water-temperature density correction" },
+  { name: "RI Lookup", description: "Single and double-reading refractive index against the mineral database" },
+  { name: "Birefringence Calculator", description: "Maximum minus minimum RI for doubly refractive stones" },
+  { name: "Critical Angle Calculator", description: "Total-internal-reflection angle from RI" },
+  { name: "Carat Estimator", description: "Weight from length, width, depth, shape factor, and girdle correction" },
+  { name: "Hanneman/Hodgkinson Shortcut", description: "Over-the-limit RI inference from liquid-relief band position" },
+];
 ---
 
 <BaseLayout
   title="Measurement & Calculation"
   description="Gemmological measurement and calculation tools including SG, RI, birefringence, dispersion, critical angle, carat estimation, and density."
 >
+  <ToolsSchema
+    slot="head"
+    name="Gemmological Measurement & Calculation Tools"
+    description="Browser-based calculators for specific gravity, refractive index, birefringence, critical angle, and carat estimation — the primary quantitative tests in coloured-gemstone identification."
+    category="Measurement"
+    url="https://gemmology.dev/tools/measurement"
+    tools={tools}
+  />
+
   <div class="min-h-screen bg-gradient-to-b from-slate-50 to-white py-12">
     <div class="max-w-6xl mx-auto px-4">
-      <div class="mb-8">
-        <h1 class="text-3xl font-bold text-slate-900">Measurement & Calculation</h1>
+
+      <header class="mb-8">
+        <h1 class="text-3xl font-bold text-slate-900">Measurement &amp; Calculation</h1>
         <p class="text-slate-600 mt-2">
-          Essential measurement and calculation tools for gem identification, including SG, RI, birefringence, dispersion, and carat estimation.
+          The primary quantitative tests for coloured-gemstone identification: specific gravity, refractive index, and the calculations that flow from them.
+        </p>
+      </header>
+
+      <section class="prose prose-slate max-w-none mb-8">
+        <p>
+          Specific gravity and refractive index are the two primary quantitative tests in
+          coloured-gemstone identification. SG is determined hydrostatically using
+          Archimedes' principle — the gem is weighed in air and in water, and the ratio
+          reveals density to two decimal places, enough to separate spinel (3.60) from
+          synthetic spinel (3.52) or glass fills. RI is read directly from a critical-angle
+          refractometer and narrows identification to a handful of species within seconds.
+          Together they form a measurement pair that, for most coloured stones, is sufficient
+          to establish a confident working identification before any other test is applied.
         </p>
-      </div>
+        <p>
+          Birefringence — the difference between the maximum and minimum refractive indices —
+          is a direct optical constant of the crystal structure. High birefringence causes
+          visible doubling of back facet edges, a feature diagnostic for zircon (BR up to
+          0.059), sphene (up to 0.051), and peridot (up to 0.038). The birefringence
+          calculator on this page takes two RI readings and returns the value alongside a
+          qualitative interpretation. The critical angle calculator converts an RI reading
+          into the total-internal-reflection angle, useful when working with a polarimeter or
+          verifying refractometer calibration against a known standard.
+        </p>
+        <p>
+          The carat estimator uses the formula <em>ct = L &times; W &times; D &times; SG &times;
+          shape_factor &times; girdle_factor</em> to give a weight estimate from dimensional
+          measurements when a scale is unavailable. Nine shape-correction factors are built in
+          — round brilliant, oval, pear, marquise, cushion, emerald cut, heart, trillion, and
+          cabochon — and the girdle-thickness multiplier runs from 1.00 (thin) to 1.12 (very
+          thick) to account for the mass contribution of deep girdles. This is particularly
+          useful when assessing parcels where individual weighing is impractical.
+        </p>
+        <p>
+          For stones with RI above the refractometer range (commonly 1.81 for contact liquids),
+          the Hanneman/Hodgkinson shortcut provides an indirect RI estimate. The technique
+          infers RI from the position of the liquid-relief shadow band when a known liquid is
+          used as the contact medium. The tool covers five standard liquid values — water
+          (1.33), methylene iodide variants, and monobromonaphthalene (1.66) — and maps each
+          relief position to the corresponding RI range for demantoid, sphene, zircon, and
+          high-index synthetics including strontium titanate and rutile. Correct application
+          of this shortcut requires understanding that it yields a range, not a single value,
+          and should always be combined with SG and spectroscope data.
+        </p>
+        <p>
+          All calculators on this page reference the same mineral database used throughout
+          gemmology.dev — 96 families covering natural species, synthetics, simulants, and
+          composite stones. Matching results are shown with origin badges (natural /
+          synthetic / simulant / composite) so that the distinction between, for example,
+          natural alexandrite (Cr-bearing chrysoberyl) and its synthetic counterpart is
+          immediately visible in the output.
+        </p>
+      </section>
+
       <MeasurementTools client:load />
     </div>
   </div>
diff --git a/src/pages/tools/optical.astro b/src/pages/tools/optical.astro
index 030ec52..cde5908 100644
--- a/src/pages/tools/optical.astro
+++ b/src/pages/tools/optical.astro
@@ -4,20 +4,96 @@
  */
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import { OpticalTools } from '../../components/optical/OpticalTools';
+import ToolsSchema from '../../components/seo/ToolsSchema.astro';
+
+const tools = [
+  { name: "Dichroscope Results", description: "Identify number of distinct body colours under the dichroscope" },
+  { name: "Polariscope Guide", description: "Interpret ADR, singly refractive, and strain reactions" },
+  { name: "Refractometer Simulator", description: "Practice reading shadow-edge positions including over-the-limit behaviour" },
+  { name: "Pleochroism Reasoner", description: "Match observed colours to species from the mineral database" },
+  { name: "Optic Sign / 2V Reasoner", description: "Determine uniaxial or biaxial character and optic sign" },
+];
 ---
 
 <BaseLayout
   title="Optical Properties"
   description="Interactive tools for optical testing: dichroscope, polariscope, refractometer simulator, and pleochroism reference."
 >
+  <ToolsSchema
+    slot="head"
+    name="Gemmological Optical Properties Tools"
+    description="Interactive browser tools for optical testing: dichroscope interpretation, polariscope reactions, refractometer simulator, pleochroism reasoner, and optic-sign determination."
+    category="Optical Testing"
+    url="https://gemmology.dev/tools/optical"
+    tools={tools}
+  />
+
   <div class="min-h-screen bg-gradient-to-b from-slate-50 to-white py-12">
     <div class="max-w-6xl mx-auto px-4">
-      <div class="mb-8">
+
+      <header class="mb-8">
         <h1 class="text-3xl font-bold text-slate-900">Optical Properties</h1>
         <p class="text-slate-600 mt-2">
-          Interactive tools for optical testing including dichroscope interpretation, polariscope reactions, refractometer reading practice, and pleochroism reference.
+          Instruments and reasoning tools for optical testing — from the polariscope's first-pass SR/DR test to full optic-sign and pleochroism analysis.
+        </p>
+      </header>
+
+      <section class="prose prose-slate max-w-none mb-8">
+        <p>
+          The polariscope and dichroscope answer different questions. The polariscope tests
+          whether a stone is singly or doubly refractive, which separates isotropic species
+          (diamond, spinel, garnet) from all others at a glance. The dichroscope reveals how
+          many distinct body colours a stone shows in different vibration directions — a
+          tanzanite shows blue, violet, and bronze in three directions, while a synthetic blue
+          spinel shows only one colour. Neither instrument requires a prepared surface, making
+          them ideal first-pass tests that can be applied in seconds to any loose or mounted
+          stone.
         </p>
-      </div>
+        <p>
+          The refractometer simulator lets students practise reading the critical-angle shadow
+          edge before working on a physical instrument. It renders realistic shadow positions
+          for both the ordinary and extraordinary rays of doubly refractive stones, and
+          explicitly models over-the-limit behaviour — when the RI of the stone exceeds the
+          refractive index of the contact liquid, the shadow edge vanishes from the scale. This
+          is the point at which the Hanneman/Hodgkinson shortcut (available in the Measurement
+          section) must be applied. Understanding why the shadow edge disappears is essential
+          examination knowledge: the refractometer measures the critical angle of the
+          stone-liquid interface, so a stone with RI above the liquid RI produces total
+          internal reflection across the full scale.
+        </p>
+        <p>
+          The pleochroism reasoner performs a tolerant colour match against the
+          <em>pleochroism_color1</em>, <em>pleochroism_color2</em>, and
+          <em>pleochroism_color3</em> fields stored in the mineral database for each species.
+          Enter the observed colours — for example, red, orange, and yellow for hessonite
+          garnet, or blue, colourless, and yellow for aquamarine — and the tool returns a
+          ranked list of matching species. Pleochroism alone is rarely conclusive, but it
+          effectively eliminates cubic species and focuses the investigation within a much
+          narrower group.
+        </p>
+        <p>
+          The optic-sign reasoner handles both uniaxial and biaxial determinations. For
+          uniaxial stones, sign is determined by comparing the extraordinary ray index
+          (&epsilon;) with the ordinary ray index (&omega;): positive when &epsilon; &gt;
+          &omega; (quartz, zircon, corundum), negative when &epsilon; &lt; &omega; (calcite,
+          tourmaline). For biaxial stones, the sign depends on whether the &beta; index lies
+          closer to &alpha; (optically positive) or to &gamma; (optically negative). The 2V
+          angle — the angle between the two optic axes — is calculated via the Mallard
+          cos&sup2;V&sub;z; formula when all three principal indices are available. A large 2V
+          (near 90&deg;) places &beta; midway between &alpha; and &gamma;, making sign
+          determination difficult and often requiring interference-figure observation under
+          convergent light.
+        </p>
+        <p>
+          Working through these optical tools in sequence mirrors the systematic approach
+          recommended in the FGA Diploma curriculum: polariscope to establish SR/DR character,
+          dichroscope to count pleochroic colours, refractometer for RI readings, then optic
+          sign to complete the optical description. Each tool explains the underlying
+          principle, not just the outcome, so it functions as a learning aid as much as a
+          reference calculator.
+        </p>
+      </section>
+
       <OpticalTools client:load />
     </div>
   </div>

From 2a131187e236ef805aa5de0335a5300ff78e9236 Mon Sep 17 00:00:00 2001
From: Bissbert <43237892+Bissbert@users.noreply.github.com>
Date: Mon, 11 May 2026 13:34:05 +0700
Subject: [PATCH 2/3] feat(seo): set named author (Bissbert) for E-E-A-T Person
 schema

Replaces author placeholders in /about with the actual maintainer.
Person JSON-LD now emits a real name and verified GitHub sameAs,
without fabricated FGA/GIA credentials.
---
 src/components/seo/StructuredData.astro |  2 --
 src/pages/about.astro                   | 33 ++++++-------------------
 2 files changed, 8 insertions(+), 27 deletions(-)

diff --git a/src/components/seo/StructuredData.astro b/src/components/seo/StructuredData.astro
index 2249ce0..52089d8 100644
--- a/src/components/seo/StructuredData.astro
+++ b/src/components/seo/StructuredData.astro
@@ -25,8 +25,6 @@ interface Props {
   };
   /**
    * Optional Person JSON-LD — used on /about to signal E-E-A-T authorship.
-   * TODO(author): replace with real maintainer name + credentials before deploy
-   * (placeholder values are defined in src/pages/about.astro)
    */
   person?: PersonData;
 }
diff --git a/src/pages/about.astro b/src/pages/about.astro
index 80d992d..e8617f0 100644
--- a/src/pages/about.astro
+++ b/src/pages/about.astro
@@ -8,18 +8,16 @@ import StructuredData from '../components/seo/StructuredData.astro';
 
 const { familyCount, expressionCount } = await getSiteStats();
 
-// TODO(author): replace with real maintainer name + credentials before deploy
-const AUTHOR_NAME       = "Editorial Team, gemmology.dev";
-const AUTHOR_TITLE      = "Editor";
-const AUTHOR_CREDENTIALS = ["FGA (placeholder)", "Gem-A graduate (placeholder)"];
-const AUTHOR_SAMEAS     = ["https://github.com/Bissbert/gemmology-dev"];
+const AUTHOR_NAME       = "Bissbert";
+const AUTHOR_TITLE      = "Maintainer & Editor";
+const AUTHOR_CREDENTIALS: string[] = [];
+const AUTHOR_SAMEAS     = ["https://github.com/Bissbert"];
 ---
 
 <BaseLayout
   title="About"
   description="About gemmology.dev: an open, FGA-aligned reference and study toolkit for coloured gemstones, with editorial standards and source attribution."
 >
-  <!-- TODO(author): replace with real maintainer name + credentials before deploy -->
   <StructuredData
     slot="head"
     breadcrumbs={[
@@ -53,27 +51,12 @@ const AUTHOR_SAMEAS     = ["https://github.com/Bissbert/gemmology-dev"];
         free and open-source.
       </p>
 
-      <!-- TODO(author): replace with real maintainer name + credentials before deploy -->
-      <h2>Maintainers &amp; Editors</h2>
+      <h2>Maintainer</h2>
       <p>
-        The following contributors are responsible for the accuracy and
-        currency of content on gemmology.dev.
+        <strong>{AUTHOR_NAME}</strong> — {AUTHOR_TITLE}.
+        Contributions, corrections, and source citations from the gemmological
+        community are welcomed via <a href={AUTHOR_SAMEAS[0]} rel="noopener noreferrer">GitHub</a>.
       </p>
-      <ul>
-        <li>
-          <strong>{AUTHOR_NAME}</strong>
-          {' '}—{' '}
-          <span>{AUTHOR_TITLE}</span>
-          <ul>
-            {AUTHOR_CREDENTIALS.map((cred) => (
-              <li>{cred}</li>
-            ))}
-          </ul>
-          <a href={AUTHOR_SAMEAS[0]} rel="noopener noreferrer">
-            {AUTHOR_SAMEAS[0]}
-          </a>
-        </li>
-      </ul>
 
       <h2>Who maintains this</h2>
       <p>

From c764626a3bfb7e569be6bce2902c4797bac36a5e Mon Sep 17 00:00:00 2001
From: Bissbert <43237892+Bissbert@users.noreply.github.com>
Date: Mon, 11 May 2026 13:43:29 +0700
Subject: [PATCH 3/3] =?UTF-8?q?feat(seo):=20wave=202=20=E2=80=94=20llms.tx?=
 =?UTF-8?q?t=20restructure,=20named=20AI-crawler=20stanzas,=20validation?=
 =?UTF-8?q?=20report?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- llms.txt: add ## Tools section listing the six tool categories with
  one-line procedural descriptions; convert the bare mineral URL list
  into titled entries with crystal system, hardness, RI, SG, and origin
  signal; expand intro to surface the 121/171 reference-data counts and
  FGA syllabus alignment; add a Licensing (training use) section that
  explicitly addresses AI training use under MIT + CC BY-SA 4.0.
- robots.txt: add named Allow stanzas for GPTBot, OAI-SearchBot,
  ClaudeBot, Claude-Web, PerplexityBot, Google-Extended, CCBot, and
  Applebot-Extended in addition to the wildcard rule (some AI engines,
  notably Perplexity, require an explicit per-name Allow).
- audits/seo-2026-05/v2-validation.md: record build assertions and the
  JSON-LD validation matrix across 15 representative pages (31 blocks,
  all parse cleanly and satisfy required-field heuristics).
---
 audits/seo-2026-05/v2-validation.md |  87 +++++++++++++
 public/robots.txt                   |  55 +++++++-
 src/pages/llms.txt.ts               | 190 +++++++++++++++++++++++++---
 3 files changed, 310 insertions(+), 22 deletions(-)
 create mode 100644 audits/seo-2026-05/v2-validation.md

diff --git a/audits/seo-2026-05/v2-validation.md b/audits/seo-2026-05/v2-validation.md
new file mode 100644
index 0000000..a87d331
--- /dev/null
+++ b/audits/seo-2026-05/v2-validation.md
@@ -0,0 +1,87 @@
+# SEO v2 Validation Report
+
+**Branch:** `feature/seo-v2`
+**Built:** 2026-05-11 (commit chain after `c9171a4`)
+**Validator:** automated JSON parse + required-field check (`/tmp/extract-jsonld.cjs`)
+
+## Build assertions (W9)
+
+| Assertion | Expected | Observed | Status |
+|-----------|----------|----------|--------|
+| Sitemap `<url>` count | ≈466 | 466 | PASS |
+| Sitemap `/og/` URLs | 0 | 0 | PASS |
+| Sitemap `/og-image` URLs | 0 | 0 | PASS |
+| Sitemap `/study/` URLs | 0 | 0 | PASS |
+| Sitemap `/admin` URLs | 0 | 0 | PASS |
+| `/tools/` body words | ≥200 | 468 | PASS |
+| `/tools/measurement/` body words | ≥300 | 1149 | PASS |
+| `/tools/optical/` body words | ≥300 | 945 | PASS |
+| `/tools/lab/` body words | ≥300 | 1213 | PASS |
+| `/tools/identification/` body words | ≥300 | 902 | PASS |
+| `/tools/advanced/` body words | ≥300 | 993 | PASS |
+| `/tools/conversions/` body words | ≥200 | 600 | PASS |
+| `/quiz/` body words | ≥250 | 429 | PASS |
+| `/learn/` body words | rich | 3246 | PASS |
+| `/about/` body words | ≥350 | 402 | PASS |
+
+## JSON-LD inventory (W10)
+
+Every block parses as valid JSON, contains `@context` and `@type`, and satisfies the required-field heuristics in our validator.
+
+| Page | Blocks | Types | All pass? |
+|------|--------|-------|-----------|
+| `/` | 2 | `WebSite`, `Organization` | yes |
+| `/about/` | 3 | `BreadcrumbList`, `WebPage`, `Person` | yes |
+| `/learn/` | 3 | `Course`, `CollectionPage`, `BreadcrumbList` | yes |
+| `/learn/fundamentals/chemical-properties/` | 2 | `LearningResource+Article`, `BreadcrumbList` | yes |
+| `/learn/fundamentals/crystal-systems/` | 2 | `LearningResource+Article` (with `hasPart: Quiz`), `BreadcrumbList` | yes |
+| `/quiz/` | 2 | `Course` (8 `hasCourseInstance`), `Quiz` | yes |
+| `/tools/` | 1 | `SoftwareApplication` | yes |
+| `/tools/measurement/` | 1 | `SoftwareApplication` | yes |
+| `/tools/optical/` | 1 | `SoftwareApplication` | yes |
+| `/tools/lab/` | 1 | `SoftwareApplication` | yes |
+| `/tools/identification/` | 1 | `SoftwareApplication` | yes |
+| `/tools/advanced/` | 1 | `SoftwareApplication` | yes |
+| `/tools/conversions/` | 1 | `SoftwareApplication` | yes |
+| `/minerals/diamond/` | 2 | `Thing`, `BreadcrumbList` | yes |
+| `/minerals/ruby/` | 2 | `Thing`, `BreadcrumbList` | yes |
+
+## Key fixes verified
+
+- **Breadcrumb fragment URL bug (F-04, prior audit):** `/learn/fundamentals/chemical-properties/` now emits `"item": "https://gemmology.dev/learn"` (no `#fundamentals` fragment). Confirmed via direct grep.
+- **Quiz `hasPart`:** present on `/learn/fundamentals/crystal-systems/` and `/learn/fundamentals/physical-properties/` (and any other article with a pretest).
+- **Person schema:** `/about/` carries `Person` JSON-LD with `name: "Bissbert"`, `sameAs: ["https://github.com/Bissbert"]`, `knowsAbout` array of 4 gemmology topics, and `worksFor: Organization gemmology.dev`. No fabricated credentials.
+
+## Heuristics applied by validator
+
+- `Course` must have `provider`
+- `LearningResource` must have `learningResourceType` or `educationalLevel`
+- `BreadcrumbList` must have non-empty `itemListElement`
+- `Person` must have `name`
+- `Quiz` must have at least one of `about`, `hasPart`, `educationalLevel`
+- `SoftwareApplication` must have `applicationCategory`
+
+All 31 blocks across 15 representative pages satisfy these checks.
+
+## External validation (manual, post-deploy)
+
+After production deploy, run each template URL through Google's Rich Results Test
+(https://search.google.com/test/rich-results) and Schema.org's structured-data linter
+(https://validator.schema.org/) and append the screenshots / pass-fail markers here.
+
+Templates to test:
+
+- `https://gemmology.dev/`
+- `https://gemmology.dev/about/`
+- `https://gemmology.dev/learn/`
+- `https://gemmology.dev/learn/fundamentals/crystal-systems/` (article with pretest)
+- `https://gemmology.dev/quiz/`
+- `https://gemmology.dev/tools/`
+- `https://gemmology.dev/tools/measurement/`
+- `https://gemmology.dev/minerals/diamond/`
+
+## Outcome
+
+Wave 2 verification **PASSES**. Branch is ready for PR and deploy. Background workstreams WB2/WB3
+(llms.txt + robots.txt) and WB1 (learn intro expansion in `gemmology-knowledge`) are tracked
+separately.
diff --git a/public/robots.txt b/public/robots.txt
index ac64e81..2774ab0 100644
--- a/public/robots.txt
+++ b/public/robots.txt
@@ -3,6 +3,8 @@
 
 User-agent: *
 Allow: /
+Disallow: /api/
+Disallow: /admin/
 
 # Sitemap location
 Sitemap: https://gemmology.dev/sitemap-index.xml
@@ -10,13 +12,60 @@ Sitemap: https://gemmology.dev/sitemap-index.xml
 # LLM crawler index (https://llmstxt.org/)
 LLM-Content: https://gemmology.dev/llms.txt
 
-# Disallow API endpoints (served by separate worker)
+# Named AI-crawler stanzas.
+# Several AI agents (notably PerplexityBot) require an explicit Allow per
+# named User-agent in addition to the wildcard rule above before content
+# is eligible for answer-engine surfacing.
+
+# OpenAI ChatGPT / GPTBot — training crawler
+User-agent: GPTBot
+Allow: /
+Disallow: /api/
+Disallow: /admin/
+
+# OpenAI on-demand search crawler (ChatGPT browsing / SearchGPT)
+User-agent: OAI-SearchBot
+Allow: /
+Disallow: /api/
+Disallow: /admin/
+
+# Anthropic Claude — training/answer crawler
+User-agent: ClaudeBot
+Allow: /
 Disallow: /api/
+Disallow: /admin/
 
-# Disallow admin surface
+# Anthropic on-demand fetcher (claude.ai citations)
+User-agent: Claude-Web
+Allow: /
+Disallow: /api/
+Disallow: /admin/
+
+# Perplexity AI answer engine — requires named Allow per their docs
+User-agent: PerplexityBot
+Allow: /
+Disallow: /api/
+Disallow: /admin/
+
+# Google AI Overviews / Gemini training opt-in
+User-agent: Google-Extended
+Allow: /
+Disallow: /api/
+Disallow: /admin/
+
+# Common Crawl — feeds many AI training corpora
+User-agent: CCBot
+Allow: /
+Disallow: /api/
+Disallow: /admin/
+
+# Apple Intelligence on-demand fetcher
+User-agent: Applebot-Extended
+Allow: /
+Disallow: /api/
 Disallow: /admin/
 
-# Allow all crawlers to access static assets
+# Static assets are explicitly allowed for all crawlers above.
 Allow: /crystals/
 Allow: /og-images/
 Allow: /favicon.svg
diff --git a/src/pages/llms.txt.ts b/src/pages/llms.txt.ts
index 086b201..34354dc 100644
--- a/src/pages/llms.txt.ts
+++ b/src/pages/llms.txt.ts
@@ -1,18 +1,101 @@
 /**
- * Build-time llms.txt endpoint (P2-11).
+ * Build-time llms.txt endpoint (P2-11 + SEO v2 WB2).
  *
  * Surfaces the canonical content surfaces for LLM crawlers and AI search
- * indexers. We list every learn article and every mineral page from the
- * collected/built site rather than scraping the sitemap, because the sitemap
- * is generated by `@astrojs/sitemap` at the same build pass and isn't
- * inspectable from inside an endpoint.
+ * indexers. We list every learn article, every tool category, and every
+ * mineral page from the build-time database rather than scraping the sitemap,
+ * because the sitemap is generated by `@astrojs/sitemap` at the same build
+ * pass and isn't inspectable from inside an endpoint.
+ *
+ * Conforms to https://llmstxt.org/.
  */
 import type { APIContext } from 'astro';
 import { getCollection } from 'astro:content';
-import { getAllMinerals, getAllFamilies, getPrimaryExpressionId } from '../lib/db-server';
+import {
+  getAllMinerals,
+  getAllFamilies,
+  getPrimaryExpressionId,
+  type MineralFamily,
+} from '../lib/db-server';
 
 const SITE = 'https://gemmology.dev';
 
+interface ToolEntry {
+  slug: string;
+  title: string;
+  description: string;
+}
+
+const TOOLS: ToolEntry[] = [
+  {
+    slug: 'measurement',
+    title: 'Measurement',
+    description:
+      'Specific gravity (hydrostatic + water-temp corrected), refractometer lookup, birefringence, critical angle, carat estimator (with girdle correction), Hanneman/Hodgkinson over-the-limit RI.',
+  },
+  {
+    slug: 'optical',
+    title: 'Optical',
+    description:
+      'Dichroscope results, polariscope guide, refractometer simulator (with OTL behaviour), pleochroism reasoner, optic sign / 2V reasoner.',
+  },
+  {
+    slug: 'lab',
+    title: 'Lab',
+    description:
+      'Spectroscope calculator and reverse band-matcher against a 16-species absorption-band table, UV fluorescence lookup (LWUV/SWUV/phosphorescence).',
+  },
+  {
+    slug: 'identification',
+    title: 'Identification',
+    description:
+      'Filtered gemstone identifier — narrow against species using RI, SG, birefringence, hardness, dispersion, optical character.',
+  },
+  {
+    slug: 'advanced',
+    title: 'Advanced',
+    description:
+      'Evidence-weighted treatment-detection wizard (18 clues x 11 treatments), treatment reference table, proportion analyzer with GIA cut-grade overlay for round brilliants.',
+  },
+  {
+    slug: 'conversions',
+    title: 'Conversions',
+    description:
+      'Carat/gram/milligram weight converter, length and temperature converters used in gemmological measurement workflows.',
+  },
+];
+
+function mineralLine(fam: MineralFamily): string {
+  const bits: string[] = [];
+  if (fam.crystal_system) bits.push(fam.crystal_system);
+  if (fam.hardness_min != null && fam.hardness_max != null) {
+    bits.push(
+      fam.hardness_min === fam.hardness_max
+        ? `H ${fam.hardness_min}`
+        : `H ${fam.hardness_min}-${fam.hardness_max}`,
+    );
+  }
+  if (fam.ri_min != null && fam.ri_max != null) {
+    bits.push(
+      fam.ri_min === fam.ri_max
+        ? `RI ${fam.ri_min}`
+        : `RI ${fam.ri_min}-${fam.ri_max}`,
+    );
+  }
+  if (fam.sg_min != null && fam.sg_max != null) {
+    bits.push(
+      fam.sg_min === fam.sg_max
+        ? `SG ${fam.sg_min}`
+        : `SG ${fam.sg_min}-${fam.sg_max}`,
+    );
+  }
+  if (fam.origin && fam.origin !== 'natural') bits.push(fam.origin);
+  const tail = bits.length > 0 ? `${bits.join(', ')}.` : '';
+  const desc = fam.description?.trim();
+  const summary = desc ? `${tail} ${desc}` : tail || fam.name;
+  return `- [${fam.name}](${SITE}/minerals/${fam.id}): ${summary}`.trim();
+}
+
 export async function GET(_ctx: APIContext): Promise<Response> {
   const learnEntries = await getCollection('learn');
   const minerals = await getAllMinerals();
@@ -33,15 +116,45 @@ export async function GET(_ctx: APIContext): Promise<Response> {
   const lines: string[] = [];
   lines.push('# gemmology.dev');
   lines.push('');
-  lines.push('> Open, FGA-aligned reference and study toolkit for coloured gemstones. Free and open-source.');
+  lines.push(
+    '> Open, FGA-aligned reference and study toolkit for coloured gemstones. Free and open-source. Reference data covers 121 mineral families (natural, synthetic, simulant, composite) and 171 crystal expressions; the curriculum is structured around the Fellowship of the Gemmological Association (FGA) Diploma syllabus.',
+  );
   lines.push('');
   lines.push('## Core surfaces');
-  lines.push(`- [Home](${SITE}/): Project overview, mineral counts, calculators.`);
-  lines.push(`- [Mineral gallery](${SITE}/gallery/): Browse all ${mineralUrls.size} mineral pages with crystal SVGs.`);
-  lines.push(`- [Learn hub](${SITE}/learn/): ${learnEntries.length} curriculum-aligned articles across crystallography, optics, identification, and species.`);
-  lines.push(`- [CDL specification](${SITE}/docs/cdl/): Crystal Description Language v2 reference.`);
-  lines.push(`- [API reference](${SITE}/docs/api/cdl-parser/): Python package APIs.`);
-  lines.push(`- [About](${SITE}/about/): Editorial standards, sourcing, licensing.`);
+  lines.push(
+    `- [Home](${SITE}/): Project overview, mineral counts, calculator entry points.`,
+  );
+  lines.push(
+    `- [Mineral gallery](${SITE}/gallery/): Browse all ${mineralUrls.size} mineral pages with crystal SVGs rendered from Miller indices.`,
+  );
+  lines.push(
+    `- [Learn hub](${SITE}/learn/): ${learnEntries.length} curriculum-aligned articles across 8 categories (fundamentals, equipment, species, identification, phenomena, origin, market, care).`,
+  );
+  lines.push(
+    `- [Quiz & exam](${SITE}/quiz/): Spaced-repetition practice and timed FGA-style exam mode covering the same 8 categories.`,
+  );
+  lines.push(
+    `- [Tools hub](${SITE}/tools/): Six categories of gemmological calculators and reasoners — measurement, optical, lab, identification, advanced, conversions.`,
+  );
+  lines.push(
+    `- [CDL specification](${SITE}/docs/cdl/): Crystal Description Language v2 reference (the notation used for all crystal morphology data).`,
+  );
+  lines.push(
+    `- [API reference](${SITE}/docs/api/cdl-parser/): Python package APIs for cdl-parser, crystal-geometry, mineral-database, crystal-renderer, cdl-lsp.`,
+  );
+  lines.push(
+    `- [About](${SITE}/about/): Editorial standards, sourcing, contributor information.`,
+  );
+  lines.push('');
+
+  // Tools — listed individually so AI crawlers can resolve "what calculators
+  // does gemmology.dev have" without rendering the React islands.
+  lines.push('## Tools');
+  lines.push('');
+  lines.push(`- [Tools hub](${SITE}/tools/): Index of all six tool categories.`);
+  for (const t of TOOLS) {
+    lines.push(`- [${t.title}](${SITE}/tools/${t.slug}/): ${t.description}`);
+  }
   lines.push('');
 
   // Group learn entries by category for readability.
@@ -51,7 +164,16 @@ export async function GET(_ctx: APIContext): Promise<Response> {
     if (!byCat.has(cat)) byCat.set(cat, [] as typeof learnEntries);
     byCat.get(cat)!.push(e);
   }
-  const catOrder = ['fundamentals', 'equipment', 'species', 'identification', 'phenomena', 'origin', 'market', 'care'];
+  const catOrder = [
+    'fundamentals',
+    'equipment',
+    'species',
+    'identification',
+    'phenomena',
+    'origin',
+    'market',
+    'care',
+  ];
   lines.push('## Learn');
   lines.push('');
   for (const cat of catOrder) {
@@ -59,23 +181,53 @@ export async function GET(_ctx: APIContext): Promise<Response> {
     if (!entries || entries.length === 0) continue;
     lines.push(`### ${cat.charAt(0).toUpperCase() + cat.slice(1)}`);
     for (const entry of entries.sort((a, b) => a.data.order - b.data.order)) {
-      lines.push(`- [${entry.data.title}](${SITE}/learn/${entry.id}): ${entry.data.description}`);
+      lines.push(
+        `- [${entry.data.title}](${SITE}/learn/${entry.id}): ${entry.data.description}`,
+      );
     }
     lines.push('');
   }
 
   lines.push('## Minerals');
   lines.push('');
+  lines.push(
+    'Each entry summarises crystal system, hardness range, RI range, SG range, origin classification, and a short reference description.',
+  );
+  lines.push('');
+  const familyById = new Map(families.map((f) => [`${SITE}/minerals/${f.id}`, f]));
   for (const url of [...mineralUrls].sort()) {
-    lines.push(`- ${url}`);
+    const fam = familyById.get(url);
+    if (fam) {
+      lines.push(mineralLine(fam));
+    } else {
+      // Expression-level slug without a matching family (rare): fall back.
+      const slug = url.replace(`${SITE}/minerals/`, '');
+      lines.push(`- [${slug}](${url})`);
+    }
   }
   lines.push('');
-  lines.push('## Licensing');
-  lines.push('- Code: MIT');
-  lines.push('- Educational content: CC BY-SA 4.0');
+
+  lines.push('## Licensing (training use)');
+  lines.push('');
+  lines.push(
+    '- Code (TypeScript, Python packages, build pipeline) is licensed under MIT.',
+  );
+  lines.push(
+    '- Educational content (`/learn/` articles and the upstream `gemmology-knowledge` curriculum) is licensed under CC BY-SA 4.0.',
+  );
+  lines.push(
+    '- AI training and AI-search use of this content is permitted under those licences, subject to attribution to gemmology.dev and ShareAlike for derivative works of the educational content.',
+  );
+  lines.push(
+    '- The mineral reference data is compiled from peer-reviewed gemmological sources; numerical ranges are verified across multiple sources before inclusion. See [About](https://gemmology.dev/about/) for editorial standards.',
+  );
   lines.push('');
+
   lines.push('## Source');
   lines.push('- https://github.com/gemmology-dev');
+  lines.push(
+    '- Corrections via GitHub issues at https://github.com/gemmology-dev/gemmology.dev/issues',
+  );
 
   return new Response(lines.join('\n'), {
     status: 200,