diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index da3b067c..c5dc71f9 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -76,5 +76,10 @@ jobs:
       - name: Run linter
         run: ${{ steps.pm.outputs.runner }} lint
 
+      - name: Run unit tests
+        run: ${{ steps.pm.outputs.runner }} test
+
       - name: Build Next.js
         run: ${{ steps.pm.outputs.runner }} build
+        env:
+          FOOMATIC_SKIP_SIMILARITY: "1"
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 52019076..0af45c8f 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -4,6 +4,10 @@ on:
   push:
     branches: [master]
 
+  # Weekly rebuild so recommendations pick up upstream foomatic-db changes.
+  schedule:
+    - cron: "0 2 * * 1"
+
   workflow_dispatch:
 
 permissions:
diff --git a/app/foomatic/printers/page.tsx b/app/foomatic/printers/page.tsx
index 180ea524..83db8b8a 100644
--- a/app/foomatic/printers/page.tsx
+++ b/app/foomatic/printers/page.tsx
@@ -261,18 +261,17 @@ export default function HomePage() {
 
     if (selectedColorCapability !== "all") {
       result = result.filter((printer) => {
-        const type = printer.type?.toLowerCase() || ""
-        const model = typeof printer.model === "string" ? printer.model.toLowerCase() : ""
+        const color = printer.color
 
         if (selectedColorCapability === "color") {
-          return type.includes("color") || model.includes("color")
+          return color === true
         }
 
         if (selectedColorCapability === "monochrome") {
-          return type.includes("mono") || type.includes("dot-matrix") || model.includes("mono")
+          return color === false
         }
 
-        return true
+        return color === "unknown" || color === undefined
       })
     }
 
diff --git a/app/layout.tsx b/app/layout.tsx
index 1162ec9a..cb00f2b1 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -4,6 +4,7 @@ import "./globals.css";
 import Navbar from "@/components/navbar";
 import Footer from "@/components/footer";
 import TopLoader from "@/components/top-loader";
+import AssistantLauncher from "@/components/assistant/AssistantLauncher";
 import { ThemeProvider } from "@/components/theme-provider";
 import { siteConfig } from "@/config/site.config";
 import { getSiteUrl } from "@/lib/site";
@@ -45,6 +46,7 @@ export default function RootLayout({
           <Navbar />
           {children}
           <Footer />
+          <AssistantLauncher />
         </ThemeProvider>
       </body>
     </html>
diff --git a/components/assistant/AssistantBlocks.tsx b/components/assistant/AssistantBlocks.tsx
new file mode 100644
index 00000000..3979f830
--- /dev/null
+++ b/components/assistant/AssistantBlocks.tsx
@@ -0,0 +1,191 @@
+"use client"
+
+// Renders the assistant's typed ResponsePlan blocks. Everything here is plain
+// React over typed data - user text and data fields are rendered as text
+// nodes (React escapes them), links are built exclusively by the canonical
+// printerHref/driverHref helpers, and no HTML string is ever injected.
+//
+// Link/accent colour inside the assistant is the site's blue family
+// (text-gradient-blue et al.) rather than --primary, which is near-white in
+// dark mode and would not read as a link there.
+
+import Link from "next/link"
+import { ArrowRight } from "lucide-react"
+import { FoomaticBadge, FoomaticCard, FoomaticStatusBadge } from "@/components/foomatic/shared"
+import { driverHref, printerHref } from "@/lib/foomatic/routes"
+import type { ResponseBlock } from "@/lib/assistant/types"
+
+// Same tone mapping as RecommendedPrintersSection.tsx: tier wording and
+// thresholds live in lib/foomatic/scoring.ts next to the model they describe.
+const TONE_CLASSES: Record<string, string> = {
+  high: "text-emerald-700 dark:text-emerald-400",
+  good: "text-sky-700 dark:text-sky-400",
+  moderate: "text-amber-700 dark:text-amber-400",
+  limited: "text-muted-foreground",
+}
+
+const LINK_CLASSES =
+  "inline-flex items-center gap-1 text-xs font-medium text-blue-600 hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring dark:text-blue-400"
+
+interface BlockProps {
+  block: ResponseBlock
+  onAsk: (query: string) => void
+  busy: boolean
+}
+
+export function AssistantBlock({ block, onAsk, busy }: BlockProps) {
+  switch (block.kind) {
+    case "text":
+      return <p className="text-sm leading-relaxed text-foreground">{block.text}</p>
+
+    case "list":
+      return (
+        <div className="space-y-1">
+          <p className="text-sm font-medium text-foreground">{block.title}</p>
+          <ul className="list-disc space-y-0.5 pl-5 text-sm leading-relaxed text-foreground">
+            {block.items.map(item => (
+              <li key={item}>{item}</li>
+            ))}
+          </ul>
+        </div>
+      )
+
+    case "chips":
+      return (
+        <div className="flex flex-wrap gap-1.5">
+          {block.chips.map(chip => (
+            <button
+              key={chip.label + chip.query}
+              type="button"
+              disabled={busy}
+              onClick={() => onAsk(chip.query)}
+              className="min-h-[2.25rem] max-w-full rounded-full border border-border bg-background px-3.5 py-1.5 text-left text-xs font-medium leading-snug text-foreground transition-colors hover:border-blue-500/50 hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+            >
+              {chip.label}
+            </button>
+          ))}
+        </div>
+      )
+
+    case "printer-cards":
+      return (
+        <ul className="space-y-2" aria-label="Printer results">
+          {block.printers.map(card => {
+            const name = `${card.manufacturer} ${card.model}`.trim() || card.id
+            return (
+              <li key={card.id}>
+                <FoomaticCard className="p-3 transition-colors hover:border-blue-500/40">
+                  <div className="flex items-start justify-between gap-3">
+                    <div className="min-w-0">
+                      {card.manufacturer && (
+                        <p className="text-xs text-muted-foreground">{card.manufacturer}</p>
+                      )}
+                      <p className="truncate text-sm font-semibold tracking-tight text-foreground">
+                        {card.model || card.id}
+                      </p>
+                    </div>
+                    {card.score !== undefined && card.tierLabel && (
+                      <div className="shrink-0 text-right">
+                        <p className={`text-xs font-medium ${TONE_CLASSES[card.tierTone ?? "limited"]}`}>
+                          {card.tierLabel}
+                        </p>
+                        <p className="text-xs text-muted-foreground">{Math.round(card.score * 100)}% similarity</p>
+                      </div>
+                    )}
+                  </div>
+                  <div className="mt-2 flex flex-wrap items-center gap-1.5">
+                    <FoomaticStatusBadge status={card.status} />
+                    {card.type && (
+                      <FoomaticBadge className="border-border text-muted-foreground">{card.type}</FoomaticBadge>
+                    )}
+                    {typeof card.driverCount === "number" && (
+                      <FoomaticBadge className="border-border text-muted-foreground">
+                        {card.driverCount} {card.driverCount === 1 ? "driver" : "drivers"}
+                      </FoomaticBadge>
+                    )}
+                    {card.features?.map(feature => (
+                      <FoomaticBadge
+                        key={feature}
+                        className="border-blue-500/20 bg-blue-500/5 text-blue-700 dark:text-blue-300"
+                      >
+                        {feature}
+                      </FoomaticBadge>
+                    ))}
+                  </div>
+                  <div className="mt-2.5">
+                    <Link
+                      href={printerHref(card.id, card.manufacturer)}
+                      aria-label={`View ${name} printer page`}
+                      className={LINK_CLASSES}
+                    >
+                      View printer
+                      <ArrowRight className="h-3 w-3" aria-hidden="true" />
+                    </Link>
+                  </div>
+                </FoomaticCard>
+              </li>
+            )
+          })}
+        </ul>
+      )
+
+    case "driver-card": {
+      const driver = block.driver
+      return (
+        <FoomaticCard className="p-3 transition-colors hover:border-blue-500/40">
+          <p className="text-sm font-semibold tracking-tight text-foreground">{driver.name}</p>
+          <div className="mt-1.5 flex flex-wrap items-center gap-1.5">
+            {driver.supplier && (
+              <FoomaticBadge className="border-border text-muted-foreground">{driver.supplier}</FoomaticBadge>
+            )}
+            {driver.type && (
+              <FoomaticBadge className="border-border text-muted-foreground">{driver.type}</FoomaticBadge>
+            )}
+            <FoomaticBadge className="border-border text-muted-foreground">
+              {driver.printerCount} {driver.printerCount === 1 ? "printer" : "printers"}
+            </FoomaticBadge>
+          </div>
+          <div className="mt-2.5">
+            <Link
+              href={driverHref(driver.id)}
+              aria-label={`View ${driver.name} driver page`}
+              className={LINK_CLASSES}
+            >
+              View driver
+              <ArrowRight className="h-3 w-3" aria-hidden="true" />
+            </Link>
+          </div>
+        </FoomaticCard>
+      )
+    }
+
+    case "comparison":
+      return (
+        <div className="overflow-x-auto rounded-lg border border-border">
+          <table className="w-full border-collapse text-xs">
+            <caption className="sr-only">
+              Comparison of {block.aName} and {block.bName}
+            </caption>
+            <thead>
+              <tr className="border-b border-border bg-muted/50 text-left">
+                <th scope="col" className="px-2.5 py-2 font-medium text-muted-foreground" />
+                <th scope="col" className="px-2.5 py-2 font-semibold text-foreground">{block.aName}</th>
+                <th scope="col" className="px-2.5 py-2 font-semibold text-foreground">{block.bName}</th>
+              </tr>
+            </thead>
+            <tbody>
+              {block.rows.map((row, index) => (
+                <tr key={row.label} className={index < block.rows.length - 1 ? "border-b border-border/60" : ""}>
+                  <th scope="row" className="px-2.5 py-2 text-left font-medium text-muted-foreground">
+                    {row.label}
+                  </th>
+                  <td className="px-2.5 py-2 text-foreground">{row.a}</td>
+                  <td className="px-2.5 py-2 text-foreground">{row.b}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )
+  }
+}
diff --git a/components/assistant/AssistantLauncher.tsx b/components/assistant/AssistantLauncher.tsx
new file mode 100644
index 00000000..658f3b49
--- /dev/null
+++ b/components/assistant/AssistantLauncher.tsx
@@ -0,0 +1,56 @@
+"use client"
+
+// Site-wide assistant entry point, mounted once in app/layout.tsx. The
+// launcher is the only assistant code in the shared bundle; the panel (and
+// the engine it imports) lives in a lazy chunk loaded on first open, and no
+// assistant data is fetched until then.
+//
+// Visual identity: the site's blue accent family (hero gradients,
+// text-gradient-blue) rather than --primary, which flips to near-white in
+// dark mode and would make the launcher vanish against light content. White
+// iconography on blue-500..700 keeps ≥3:1 contrast in both themes.
+
+import { useState } from "react"
+import dynamic from "next/dynamic"
+import { MessageCircleMore, X } from "lucide-react"
+
+const AssistantPanel = dynamic(() => import("./AssistantPanel"), { ssr: false })
+
+const LAUNCHER_ID = "assistant-launcher"
+
+export default function AssistantLauncher() {
+  const [open, setOpen] = useState(false)
+  const [loaded, setLoaded] = useState(false)
+
+  return (
+    <>
+      <button
+        id={LAUNCHER_ID}
+        type="button"
+        aria-label={open ? "Close printer assistant" : "Open printer assistant"}
+        aria-expanded={open}
+        aria-haspopup="dialog"
+        aria-controls="assistant-panel"
+        onClick={() => {
+          setLoaded(true)
+          setOpen(current => !current)
+        }}
+        className="group fixed bottom-[max(1.25rem,env(safe-area-inset-bottom))] right-[max(1.25rem,env(safe-area-inset-right))] z-40 flex h-14 w-14 items-center justify-center rounded-full bg-gradient-to-br from-blue-500 to-blue-700 text-white shadow-lg shadow-blue-600/25 ring-1 ring-white/20 transition-[box-shadow,transform] duration-200 hover:shadow-xl hover:shadow-blue-600/35 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background motion-safe:hover:scale-105 motion-safe:active:scale-95 print:hidden sm:bottom-6 sm:right-6"
+      >
+        <span className="relative flex h-6 w-6 items-center justify-center" aria-hidden="true">
+          <MessageCircleMore
+            className={`absolute h-6 w-6 transition-all duration-200 motion-reduce:transition-none ${
+              open ? "scale-50 opacity-0" : "scale-100 opacity-100"
+            }`}
+          />
+          <X
+            className={`absolute h-5 w-5 transition-all duration-200 motion-reduce:transition-none ${
+              open ? "scale-100 opacity-100" : "scale-50 opacity-0"
+            }`}
+          />
+        </span>
+      </button>
+      {loaded && <AssistantPanel open={open} onClose={() => setOpen(false)} launcherId={LAUNCHER_ID} />}
+    </>
+  )
+}
diff --git a/components/assistant/AssistantPanel.tsx b/components/assistant/AssistantPanel.tsx
new file mode 100644
index 00000000..46c8be37
--- /dev/null
+++ b/components/assistant/AssistantPanel.tsx
@@ -0,0 +1,385 @@
+"use client"
+
+// The assistant chat panel.
+//
+// Responsive tiers (JS-driven - the panel never server-renders, so the tier
+// has a single source of truth instead of parallel CSS breakpoints):
+// - compact (width < 640px OR height < 480px, i.e. phones in either
+//   orientation): full-height modal sheet over a backdrop - aria-modal,
+//   focus-trapped, body scroll locked, safe-area padded, keyboard-aware
+//   (dvh sizing plus a visualViewport listener that keeps the newest message
+//   and the input visible while the on-screen keyboard is up);
+// - anchored (everything else): a compact surface (400px, 420px from md up)
+//   whose height is capped against the fixed 4rem navbar
+//   (min(600px, 100dvh - 10.5rem)), non-modal so the page stays readable.
+//
+// Stacking: backdrop z-[65] / panel z-[70] - above the navbar (z-50) and the
+// z-40 launcher, below the search modal (z-[100]) and TopLoader (z-[9999]).
+//
+// Accessibility: role="dialog", Escape closes, focus moves to the input on
+// open and returns to the launcher on close, the conversation is a polite
+// live region, and every animation collapses under prefers-reduced-motion.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import { usePathname } from "next/navigation"
+import { motion, useReducedMotion } from "framer-motion"
+import { Loader2, Printer, Send, X } from "lucide-react"
+
+import { parsePageContext } from "@/lib/assistant/context"
+import { createBrowserData } from "@/lib/assistant/data"
+import { runAssistant } from "@/lib/assistant/engine"
+import { contextSuggestions } from "@/lib/assistant/respond"
+import type { ResponsePlan } from "@/lib/assistant/types"
+import { AssistantBlock } from "./AssistantBlocks"
+
+interface Message {
+  id: number
+  role: "user" | "assistant"
+  text?: string
+  plan?: ResponsePlan
+}
+
+interface AssistantPanelProps {
+  open: boolean
+  onClose: () => void
+  launcherId: string
+}
+
+// One data source per tab: all fetches are cached and shared across turns.
+const data = createBrowserData()
+
+let nextMessageId = 1
+
+export default function AssistantPanel({ open, onClose, launcherId }: AssistantPanelProps) {
+  const pathname = usePathname()
+  const context = useMemo(() => parsePageContext(pathname ?? "/"), [pathname])
+  // Latest context for the ask callback: usePathname already excludes any
+  // configured basePath, unlike window.location.pathname.
+  const contextRef = useRef(context)
+  useEffect(() => {
+    contextRef.current = context
+  }, [context])
+  const [messages, setMessages] = useState<Message[]>([])
+  const [input, setInput] = useState("")
+  const [busy, setBusy] = useState(false)
+  // Compact tier = the full-height sheet. Applies below the sm breakpoint OR
+  // on short viewports (phone landscape: an anchored card capped against the
+  // navbar would leave a ~200px panel there).
+  const [isCompact, setIsCompact] = useState(false)
+  const panelRef = useRef<HTMLDivElement>(null)
+  const inputRef = useRef<HTMLTextAreaElement>(null)
+  const logRef = useRef<HTMLDivElement>(null)
+  const reducedMotion = useReducedMotion()
+
+  useEffect(() => {
+    // Derived from innerWidth/innerHeight rather than MediaQueryList.matches:
+    // MQL updates ride the rendering pipeline and can lag (or never fire
+    // change events) in throttled/background documents, while the window
+    // dimensions are always current. The panel never server-renders
+    // (dynamic ssr:false), so the layout tier can safely live in JS state.
+    const update = () => setIsCompact(window.innerWidth < 640 || window.innerHeight < 480)
+    update()
+    const query = window.matchMedia("(max-width: 639px)")
+    query.addEventListener("change", update)
+    window.addEventListener("resize", update)
+    return () => {
+      query.removeEventListener("change", update)
+      window.removeEventListener("resize", update)
+    }
+  }, [])
+
+  // Warm the catalogue while the user types their first question; failures
+  // are ignored here because every query retries through the cache.
+  useEffect(() => {
+    if (open) {
+      data.getCatalog().catch(() => {})
+      data.getDriversMap().catch(() => {})
+    }
+  }, [open])
+
+  useEffect(() => {
+    if (open) {
+      inputRef.current?.focus()
+    }
+  }, [open])
+
+  // Escape closes; guard on our own open state (same window-listener idiom as
+  // the navbar and search modal).
+  useEffect(() => {
+    if (!open) return
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        onClose()
+      }
+    }
+    window.addEventListener("keydown", onKeyDown)
+    return () => window.removeEventListener("keydown", onKeyDown)
+  }, [open, onClose])
+
+  // Mobile is modal: lock body scroll and trap Tab inside the sheet.
+  useEffect(() => {
+    if (!open || !isCompact) return
+    const previousOverflow = document.body.style.overflow
+    document.body.style.overflow = "hidden"
+    const trap = (event: KeyboardEvent) => {
+      if (event.key !== "Tab" || !panelRef.current) return
+      const focusables = panelRef.current.querySelectorAll<HTMLElement>(
+        'button, [href], textarea, input, [tabindex]:not([tabindex="-1"])'
+      )
+      if (focusables.length === 0) return
+      const first = focusables[0]
+      const last = focusables[focusables.length - 1]
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault()
+        last.focus()
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault()
+        first.focus()
+      }
+    }
+    window.addEventListener("keydown", trap)
+    return () => {
+      document.body.style.overflow = previousOverflow
+      window.removeEventListener("keydown", trap)
+    }
+  }, [open, isCompact])
+
+  // When the on-screen keyboard opens/closes the visual viewport resizes;
+  // keep the newest message (and therefore the input above it) in view.
+  useEffect(() => {
+    if (!open || !isCompact) return
+    const viewport = window.visualViewport
+    if (!viewport) return
+    const onResize = () => {
+      logRef.current?.scrollTo({ top: logRef.current.scrollHeight })
+    }
+    viewport.addEventListener("resize", onResize)
+    return () => viewport.removeEventListener("resize", onResize)
+  }, [open, isCompact])
+
+  // Return focus to the launcher when the panel closes.
+  const wasOpen = useRef(false)
+  useEffect(() => {
+    if (wasOpen.current && !open) {
+      document.getElementById(launcherId)?.focus()
+    }
+    wasOpen.current = open
+  }, [open, launcherId])
+
+  // Scroll policy: a newly completed assistant response is revealed from its
+  // TOP, so the user reads the introduction and any caveats before the result
+  // cards - a ten-card answer must not dump them at the last card. For short
+  // responses the scroll clamps to the bottom naturally (the target sits past
+  // the maximum scroll offset), so nothing jumps. User messages and the busy
+  // indicator still track the bottom so "what you just sent" stays visible.
+  // Only message arrival triggers auto-scroll; manual scrolling is untouched.
+  useEffect(() => {
+    const log = logRef.current
+    if (!log) return
+    const behavior = reducedMotion ? ("auto" as const) : ("smooth" as const)
+    const last = messages[messages.length - 1]
+    if (last?.role === "assistant") {
+      const element = log.querySelector<HTMLElement>(`[data-message-id="${last.id}"]`)
+      if (element) {
+        const top = element.getBoundingClientRect().top - log.getBoundingClientRect().top + log.scrollTop
+        log.scrollTo({ top: Math.max(0, top - 8), behavior })
+        return
+      }
+    }
+    log.scrollTo({ top: log.scrollHeight, behavior })
+  }, [messages, busy, reducedMotion])
+
+  const ask = useCallback(
+    async (query: string) => {
+      const trimmed = query.trim()
+      if (!trimmed || busy) return
+      setInput("")
+      setMessages(current => [...current, { id: nextMessageId++, role: "user", text: trimmed }])
+      setBusy(true)
+      try {
+        const turn = await runAssistant(trimmed, contextRef.current, data)
+        setMessages(current => [...current, { id: nextMessageId++, role: "assistant", plan: turn.plan }])
+      } finally {
+        setBusy(false)
+        inputRef.current?.focus()
+      }
+    },
+    [busy]
+  )
+
+  const onInputKeyDown = (event: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (event.key === "Enter" && !event.shiftKey) {
+      event.preventDefault()
+      void ask(input)
+    }
+  }
+
+  const suggestions = useMemo(() => contextSuggestions(context), [context])
+
+  const messageMotion = reducedMotion
+    ? {}
+    : {
+        initial: { opacity: 0, y: 6 },
+        animate: { opacity: 1, y: 0 },
+        transition: { duration: 0.15, ease: "easeOut" as const },
+      }
+
+  // The open/close presentation is deliberately plain CSS driven by `open`:
+  // the closed panel is visibility-hidden and pointer-events-none IMMEDIATELY,
+  // never gated on an animation finishing. (An animation-gated unmount left
+  // the closed sheet invisibly mounted over the page - covering the launcher
+  // and swallowing every tap - whenever exit completion stalled.) Opening
+  // still eases in via a CSS transition; closing is instant, which reduced
+  // motion requires anyway. CSS transitions always settle at their final
+  // state, so no environment can strand the panel half-closed.
+  return (
+    <>
+      {isCompact && (
+        <div
+          className={`fixed inset-0 z-[65] bg-black/50 transition-opacity duration-200 motion-reduce:transition-none ${
+            open ? "opacity-100" : "pointer-events-none opacity-0"
+          }`}
+          aria-hidden="true"
+          onClick={open ? onClose : undefined}
+        />
+      )}
+      <div
+            id="assistant-panel"
+            ref={panelRef}
+            role="dialog"
+            aria-label="Printer assistant"
+            aria-modal={isCompact && open ? true : undefined}
+            className={`fixed z-[70] flex flex-col overflow-hidden bg-card shadow-2xl ring-1 ring-black/5 transition-[opacity,transform] duration-200 ease-out motion-reduce:transition-none dark:ring-white/10 ${
+              isCompact
+                ? "inset-0 h-[100dvh] w-full"
+                : "bottom-[5.75rem] right-6 h-[min(37.5rem,calc(100dvh-10.5rem))] w-[400px] rounded-2xl border border-border md:w-[420px]"
+            } ${open ? "visible translate-y-0 opacity-100" : "invisible translate-y-3 opacity-0 pointer-events-none"}`}
+          >
+            <header
+              className={`flex items-center justify-between gap-3 border-b border-border bg-card px-4 pb-3 ${
+                isCompact ? "pt-[max(0.75rem,env(safe-area-inset-top))]" : "pt-3"
+              }`}
+            >
+              <div className="flex min-w-0 items-center gap-3">
+                <span
+                  className="flex h-9 w-9 shrink-0 items-center justify-center rounded-xl bg-gradient-to-br from-blue-500 to-blue-700 text-white shadow-sm"
+                  aria-hidden="true"
+                >
+                  <Printer className="h-[18px] w-[18px]" />
+                </span>
+                <div className="min-w-0">
+                  <h2 className="truncate text-sm font-semibold tracking-tight text-foreground">
+                    Printer assistant
+                  </h2>
+                  <p className="truncate text-xs text-muted-foreground">
+                    Answers from the Foomatic printer database
+                  </p>
+                </div>
+              </div>
+              {/* Sheet-only: the sheet covers the launcher and Escape has no
+                  touch equivalent. In the anchored tier the launcher itself
+                  morphs into the close control, so a second X would be
+                  redundant - exactly one close affordance is visible at any
+                  time. */}
+              {isCompact && (
+                <button
+                  type="button"
+                  onClick={onClose}
+                  aria-label="Close assistant"
+                  className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                >
+                  <X className="h-4 w-4" aria-hidden="true" />
+                </button>
+              )}
+            </header>
+
+            <div
+              ref={logRef}
+              role="log"
+              aria-live="polite"
+              aria-busy={busy}
+              aria-label="Conversation"
+              className="flex-1 space-y-4 overflow-y-auto overscroll-contain px-4 py-4"
+            >
+              {messages.length === 0 && (
+                <div className="space-y-4 pt-2">
+                  <div className="space-y-1.5">
+                    <p className="text-sm font-medium text-foreground">
+                      Hi - I answer questions from OpenPrinting&apos;s Foomatic printer database.
+                    </p>
+                    <p className="text-sm leading-relaxed text-muted-foreground">
+                      Ask about printers, Linux support, drivers, or similar models - or start with one
+                      of these:
+                    </p>
+                  </div>
+                  <AssistantBlock block={{ kind: "chips", chips: suggestions }} onAsk={ask} busy={busy} />
+                </div>
+              )}
+              {messages.map(message =>
+                message.role === "user" ? (
+                  <motion.div key={message.id} className="flex justify-end" {...messageMotion}>
+                    <p className="max-w-[85%] whitespace-pre-wrap break-words rounded-2xl rounded-br-md bg-blue-600 px-3.5 py-2 text-sm leading-relaxed text-white">
+                      {message.text}
+                    </p>
+                  </motion.div>
+                ) : (
+                  <motion.div
+                    key={message.id}
+                    data-message-id={message.id}
+                    className="space-y-2.5"
+                    {...messageMotion}
+                  >
+                    {message.plan?.blocks.map((block, index) => (
+                      <AssistantBlock key={index} block={block} onAsk={ask} busy={busy} />
+                    ))}
+                  </motion.div>
+                )
+              )}
+              {busy && (
+                <p className="flex items-center gap-2 text-xs text-muted-foreground" role="status">
+                  <Loader2 className="h-3.5 w-3.5 animate-spin motion-reduce:animate-none" aria-hidden="true" />
+                  Looking that up…
+                </p>
+              )}
+            </div>
+
+            <form
+              className="border-t border-border bg-card px-4 py-3 pb-[max(0.75rem,env(safe-area-inset-bottom))]"
+              onSubmit={event => {
+                event.preventDefault()
+                void ask(input)
+              }}
+            >
+              <div className="flex items-end gap-2">
+                <label htmlFor="assistant-input" className="sr-only">
+                  Ask about printers
+                </label>
+                <textarea
+                  id="assistant-input"
+                  ref={inputRef}
+                  value={input}
+                  onChange={event => setInput(event.target.value)}
+                  onKeyDown={onInputKeyDown}
+                  rows={1}
+                  maxLength={300}
+                  placeholder="e.g. find a colour laser printer"
+                  className="max-h-28 min-h-[2.5rem] flex-1 resize-none rounded-xl border border-input bg-background px-3.5 py-2.5 text-sm text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                />
+                <button
+                  type="submit"
+                  disabled={busy || input.trim().length === 0}
+                  aria-label="Send question"
+                  className="flex h-10 w-10 shrink-0 items-center justify-center rounded-xl bg-blue-600 text-white transition-colors hover:bg-blue-700 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-40"
+                >
+                  {busy ? (
+                    <Loader2 className="h-4 w-4 animate-spin motion-reduce:animate-none" aria-hidden="true" />
+                  ) : (
+                    <Send className="h-4 w-4" aria-hidden="true" />
+                  )}
+                </button>
+              </div>
+            </form>
+      </div>
+    </>
+  )
+}
diff --git a/components/foomatic/DriverPageClient.tsx b/components/foomatic/DriverPageClient.tsx
index 3e365904..58204b40 100644
--- a/components/foomatic/DriverPageClient.tsx
+++ b/components/foomatic/DriverPageClient.tsx
@@ -20,6 +20,7 @@ import {
 import { Button } from "@/components/ui/button"
 import { withBasePath } from "@/lib/foomatic/base-path"
 import { driverHref, printerHref } from "@/lib/foomatic/routes"
+import { sanitizeFoomaticHtml } from "@/lib/foomatic/sanitize"
 import type { DriverRecord } from "@/lib/foomatic/types"
 
 interface DriverPageClientProps {
@@ -83,7 +84,7 @@ export default function DriverPageClient({ driverId }: DriverPageClientProps) {
         setLoading(true)
         setError(null)
 
-        const response = await fetch(withBasePath(`/foomatic-db/drivers/${driverId}.json`))
+        const response = await fetch(withBasePath(`/foomatic-db/drivers/${encodeURIComponent(driverId)}.json`))
         if (!response.ok) {
           throw new Error("This driver entry could not be loaded.")
         }
@@ -339,7 +340,7 @@ export default function DriverPageClient({ driverId }: DriverPageClientProps) {
                 <h3 className="text-sm font-semibold uppercase tracking-[0.18em] text-muted-foreground">Description</h3>
                 <div
                   className="prose prose-sm mt-4 max-w-none text-foreground dark:prose-invert"
-                  dangerouslySetInnerHTML={{ __html: driver.comments }}
+                  dangerouslySetInnerHTML={{ __html: sanitizeFoomaticHtml(driver.comments) }}
                 />
               </FoomaticCard>
             ) : driver.shortDescription ? (
diff --git a/components/foomatic/PpdViewerClient.tsx b/components/foomatic/PpdViewerClient.tsx
index caf67246..4feec5ab 100644
--- a/components/foomatic/PpdViewerClient.tsx
+++ b/components/foomatic/PpdViewerClient.tsx
@@ -14,6 +14,7 @@ import { Button } from "@/components/ui/button"
 import { withBasePath } from "@/lib/foomatic/base-path"
 import { ppdFilePath } from "@/lib/foomatic/routes"
 
+// Restrict to known PPD output dirs and reject ".." to prevent path traversal.
 function isValidPpdPath(path: string | null) {
   return Boolean(path && (path.startsWith("/ppd/") || path.startsWith("/ppds/")) && !path.includes(".."))
 }
diff --git a/components/foomatic/PrinterPageClient.tsx b/components/foomatic/PrinterPageClient.tsx
index 21d53e1f..970f40c6 100644
--- a/components/foomatic/PrinterPageClient.tsx
+++ b/components/foomatic/PrinterPageClient.tsx
@@ -21,8 +21,12 @@ import {
 import { Button } from "@/components/ui/button"
 import { withBasePath } from "@/lib/foomatic/base-path"
 import { driverHref, ppdViewHref } from "@/lib/foomatic/routes"
+import { sanitizeFoomaticHtml } from "@/lib/foomatic/sanitize"
 import type { Printer } from "@/lib/foomatic/types"
 import { calculateAccurateStatus } from "@/lib/foomatic/utils"
+import RecommendedPrintersSection, {
+  SimilarPrintersTeaser,
+} from "@/components/foomatic/RecommendedPrintersSection"
 
 interface PrinterPageClientProps {
   printerId: string
@@ -30,19 +34,40 @@ interface PrinterPageClientProps {
 
 function LoadingState() {
   return (
-    <div className="grid gap-6 lg:grid-cols-[minmax(0,0.9fr)_minmax(0,1.5fr)]" role="status" aria-label="Loading printer details">
-      <FoomaticCard className="space-y-4 p-6">
-        <div className="h-8 w-36 animate-pulse rounded bg-muted" />
-        <div className="h-5 w-28 animate-pulse rounded bg-muted" />
-        <div className="h-20 animate-pulse rounded-xl bg-muted" />
-      </FoomaticCard>
-
-      <div className="space-y-6">
-        {Array.from({ length: 2 }).map((_, index) => (
-          <FoomaticCard key={index} className="space-y-4 p-6">
-            <div className="h-7 w-40 animate-pulse rounded bg-muted" />
-            <div className="h-4 w-56 animate-pulse rounded bg-muted" />
-            <div className="h-20 animate-pulse rounded-xl bg-muted" />
+    <div className="space-y-6" role="status" aria-label="Loading printer details">
+      <div className="grid gap-6 lg:grid-cols-[minmax(0,0.9fr)_minmax(0,1.5fr)]">
+        <FoomaticCard className="space-y-4 p-6">
+          <div className="h-8 w-36 animate-pulse rounded bg-muted" />
+          <div className="h-5 w-28 animate-pulse rounded bg-muted" />
+          <div className="h-20 animate-pulse rounded-xl bg-muted" />
+        </FoomaticCard>
+
+        <div className="space-y-6">
+          {Array.from({ length: 2 }).map((_, index) => (
+            <FoomaticCard key={index} className="space-y-4 p-6">
+              <div className="h-7 w-40 animate-pulse rounded bg-muted" />
+              <div className="h-4 w-56 animate-pulse rounded bg-muted" />
+              <div className="h-20 animate-pulse rounded-xl bg-muted" />
+            </FoomaticCard>
+          ))}
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <div className="h-7 w-44 animate-pulse rounded bg-muted" />
+        {Array.from({ length: 3 }).map((_, index) => (
+          <FoomaticCard key={index} className="p-6">
+            <div className="flex flex-col gap-4 lg:flex-row lg:items-start lg:justify-between">
+              <div className="flex-1 space-y-3">
+                <div className="h-3.5 w-24 animate-pulse rounded bg-muted" />
+                <div className="h-5 w-48 animate-pulse rounded bg-muted" />
+                <div className="flex gap-2">
+                  <div className="h-6 w-20 animate-pulse rounded-full bg-muted" />
+                  <div className="h-6 w-16 animate-pulse rounded-full bg-muted" />
+                </div>
+              </div>
+              <div className="h-9 w-28 animate-pulse rounded-md bg-muted" />
+            </div>
           </FoomaticCard>
         ))}
       </div>
@@ -61,7 +86,7 @@ export default function PrinterPageClient({ printerId }: PrinterPageClientProps)
         setLoading(true)
         setError(null)
 
-        const response = await fetch(withBasePath(`/foomatic-db/printers/${printerId}.json`))
+        const response = await fetch(withBasePath(`/foomatic-db/printers/${encodeURIComponent(printerId)}.json`))
         if (!response.ok) {
           throw new Error("This printer entry could not be loaded.")
         }
@@ -120,6 +145,12 @@ export default function PrinterPageClient({ printerId }: PrinterPageClientProps)
   }
 
   const status = calculateAccurateStatus(printer)
+  const hasCapabilities =
+    (printer.color !== undefined && printer.color !== "unknown") ||
+    (printer.duplex !== undefined && printer.duplex !== "unknown") ||
+    printer.maxDpi != null ||
+    (printer.connectivity?.length ?? 0) > 0 ||
+    (printer.commandsets?.length ?? 0) > 0
   const drivers = [...(printer.drivers ?? [])].sort((left, right) => {
     if (left.id === printer.recommended_driver) return -1
     if (right.id === printer.recommended_driver) return 1
@@ -170,19 +201,23 @@ export default function PrinterPageClient({ printerId }: PrinterPageClientProps)
                 </div>
               </div>
 
-              {printer.recommended_driver ? (
-                <FoomaticCard className="max-w-sm p-4">
-                  <p className="text-xs font-semibold uppercase tracking-[0.18em] text-muted-foreground">
-                    Recommended driver
-                  </p>
-                  <Link
-                    href={driverHref(printer.recommended_driver)}
-                    className="mt-2 inline-block text-sm font-medium text-primary hover:underline"
-                  >
-                    {printer.recommended_driver.replace(/^driver\//, "")}
-                  </Link>
-                </FoomaticCard>
-              ) : null}
+              <div className="flex w-full max-w-sm flex-col gap-4 md:w-auto">
+                {printer.recommended_driver ? (
+                  <FoomaticCard className="p-4">
+                    <p className="text-xs font-semibold uppercase tracking-[0.18em] text-muted-foreground">
+                      Recommended driver
+                    </p>
+                    <Link
+                      href={driverHref(printer.recommended_driver)}
+                      className="mt-2 inline-block text-sm font-medium text-primary hover:underline"
+                    >
+                      {printer.recommended_driver.replace(/^driver\//, "")}
+                    </Link>
+                  </FoomaticCard>
+                ) : null}
+
+                <SimilarPrintersTeaser printerId={printer.id} />
+              </div>
             </div>
           </div>
         </section>
@@ -225,56 +260,66 @@ export default function PrinterPageClient({ printerId }: PrinterPageClientProps)
                     <FoomaticStatusBadge status={status} />
                   </dd>
                 </div>
-                {printer.color !== undefined && printer.color !== "unknown" ? (
-                  <div>
-                    <dt className="text-xs font-semibold uppercase tracking-[0.18em] text-muted-foreground">
-                      Color
-                    </dt>
-                    <dd className="mt-2 text-sm text-foreground">
-                      {printer.color ? "Color output" : "Monochrome only"}
-                    </dd>
-                  </div>
-                ) : null}
-                {printer.duplex !== undefined && printer.duplex !== "unknown" ? (
-                  <div>
-                    <dt className="text-xs font-semibold uppercase tracking-[0.18em] text-muted-foreground">
-                      Duplex
-                    </dt>
-                    <dd className="mt-2 text-sm text-foreground">
-                      {printer.duplex ? "Supported" : "Not supported"}
-                    </dd>
-                  </div>
-                ) : null}
-                {printer.connectivity && printer.connectivity.length > 0 ? (
-                  <div>
-                    <dt className="text-xs font-semibold uppercase tracking-[0.18em] text-muted-foreground">
-                      Connectivity
-                    </dt>
-                    <dd className="mt-2 flex flex-wrap gap-2">
-                      {printer.connectivity.map((item) => (
-                        <FoomaticBadge key={item} className="border-border bg-accent/50 text-muted-foreground">
-                          {item}
-                        </FoomaticBadge>
-                      ))}
-                    </dd>
-                  </div>
-                ) : null}
-                {printer.commandsets && printer.commandsets.length > 0 ? (
-                  <div>
-                    <dt className="text-xs font-semibold uppercase tracking-[0.18em] text-muted-foreground">
-                      Page description languages
-                    </dt>
-                    <dd className="mt-2 flex flex-wrap gap-2">
-                      {printer.commandsets.map((item) => (
-                        <FoomaticBadge key={item} className="border-border bg-accent/50 text-muted-foreground">
-                          {item}
-                        </FoomaticBadge>
-                      ))}
-                    </dd>
-                  </div>
-                ) : null}
               </dl>
 
+              {hasCapabilities ? (
+                <div className="mt-6 border-t border-border pt-5">
+                  <h3 className="text-xs font-semibold uppercase tracking-[0.18em] text-muted-foreground">
+                    Capabilities
+                  </h3>
+                  <dl className="mt-4 space-y-4">
+                    {printer.color !== undefined && printer.color !== "unknown" ? (
+                      <div>
+                        <dt className="text-xs font-medium text-muted-foreground">Color</dt>
+                        <dd className="mt-1 text-sm text-foreground">
+                          {printer.color ? "Color output" : "Monochrome only"}
+                        </dd>
+                      </div>
+                    ) : null}
+                    {printer.duplex !== undefined && printer.duplex !== "unknown" ? (
+                      <div>
+                        <dt className="text-xs font-medium text-muted-foreground">Duplex</dt>
+                        <dd className="mt-1 text-sm text-foreground">
+                          {printer.duplex ? "Supported" : "Not supported"}
+                        </dd>
+                      </div>
+                    ) : null}
+                    {printer.maxDpi != null ? (
+                      <div>
+                        <dt className="text-xs font-medium text-muted-foreground">Max resolution</dt>
+                        <dd className="mt-1 text-sm text-foreground">{printer.maxDpi} dpi</dd>
+                      </div>
+                    ) : null}
+                    {printer.connectivity && printer.connectivity.length > 0 ? (
+                      <div>
+                        <dt className="text-xs font-medium text-muted-foreground">Connectivity</dt>
+                        <dd className="mt-1 flex flex-wrap gap-2">
+                          {printer.connectivity.map((item) => (
+                            <FoomaticBadge key={item} className="border-border bg-accent/50 text-muted-foreground">
+                              {item}
+                            </FoomaticBadge>
+                          ))}
+                        </dd>
+                      </div>
+                    ) : null}
+                    {printer.commandsets && printer.commandsets.length > 0 ? (
+                      <div>
+                        <dt className="text-xs font-medium text-muted-foreground">
+                          Page description languages
+                        </dt>
+                        <dd className="mt-1 flex flex-wrap gap-2">
+                          {printer.commandsets.map((item) => (
+                            <FoomaticBadge key={item} className="border-border bg-accent/50 text-muted-foreground">
+                              {item}
+                            </FoomaticBadge>
+                          ))}
+                        </dd>
+                      </div>
+                    ) : null}
+                  </dl>
+                </div>
+              ) : null}
+
               {printer.notes ? (
                 <div className="mt-8 border-t border-border pt-6">
                   <h3 className="text-sm font-semibold uppercase tracking-[0.18em] text-muted-foreground">
@@ -282,7 +327,7 @@ export default function PrinterPageClient({ printerId }: PrinterPageClientProps)
                   </h3>
                   <div
                     className="prose prose-sm mt-4 max-w-none text-foreground dark:prose-invert"
-                    dangerouslySetInnerHTML={{ __html: printer.notes }}
+                    dangerouslySetInnerHTML={{ __html: sanitizeFoomaticHtml(printer.notes) }}
                   />
                 </div>
               ) : null}
@@ -382,7 +427,9 @@ export default function PrinterPageClient({ printerId }: PrinterPageClientProps)
                 <div
                   className="prose prose-sm mt-5 max-w-none text-foreground dark:prose-invert"
                   dangerouslySetInnerHTML={{
-                    __html: driver.comments || "No additional notes are available for this driver.",
+                    __html: sanitizeFoomaticHtml(
+                      driver.comments || "No additional notes are available for this driver."
+                    ),
                   }}
                 />
 
@@ -410,6 +457,7 @@ export default function PrinterPageClient({ printerId }: PrinterPageClientProps)
             ))}
           </section>
         </div>
+        <RecommendedPrintersSection printerId={printer.id} />
       </FoomaticPageSection>
     </main>
   )
diff --git a/components/foomatic/RecommendedPrintersSection.tsx b/components/foomatic/RecommendedPrintersSection.tsx
new file mode 100644
index 00000000..81587a7a
--- /dev/null
+++ b/components/foomatic/RecommendedPrintersSection.tsx
@@ -0,0 +1,320 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import Link from "next/link"
+import { ArrowDown } from "lucide-react"
+
+import {
+  FoomaticBadge,
+  FoomaticCard,
+  FoomaticStatusBadge,
+} from "@/components/foomatic/shared"
+import { withBasePath } from "@/lib/foomatic/base-path"
+import { printerHref } from "@/lib/foomatic/routes"
+import { confidenceTier } from "@/lib/foomatic/scoring"
+import type { ConfidenceTone } from "@/lib/foomatic/scoring"
+
+// Display fields are embedded in each per-printer recommendation shard by
+// compute-similarity.ts, so this section needs exactly one small fetch.
+interface Recommendation {
+  id: string
+  score: number
+  sharedFeatures: string[]
+  manufacturer?: string
+  model?: string
+  status: string
+  type: string
+  driverCount: number
+}
+
+interface RecommendedPrintersSectionProps {
+  printerId: string
+}
+
+// One shard fetch per printer id, shared between the hero teaser and the full
+// section below so mounting both costs a single network request. A missing
+// shard (404) resolves to an empty list; network failures clear the cache so
+// the next mount retries instead of reusing a rejected promise.
+const shardCache = new Map<string, Promise<Recommendation[]>>()
+
+function getRecommendations(printerId: string): Promise<Recommendation[]> {
+  let cached = shardCache.get(printerId)
+
+  if (!cached) {
+    cached = fetch(
+      withBasePath(`/foomatic-db/recommendations/${encodeURIComponent(printerId)}.json`)
+    )
+      .then((response) => (response.ok ? (response.json() as Promise<Recommendation[]>) : []))
+      .catch((error) => {
+        shardCache.delete(printerId)
+        throw error
+      })
+
+    shardCache.set(printerId, cached)
+  }
+
+  return cached
+}
+
+// Tier wording and thresholds live in lib/foomatic/scoring.ts next to the
+// scoring model they interpret. The percentage is labelled "similarity", not
+// "match", because the score is an engineered similarity value — it is not a
+// probability that the printer will work.
+const TONE_CLASSES: Record<ConfidenceTone, string> = {
+  high: "text-emerald-700 dark:text-emerald-400",
+  good: "text-sky-700 dark:text-sky-400",
+  moderate: "text-amber-700 dark:text-amber-400",
+  limited: "text-muted-foreground",
+}
+
+function ConfidenceBadge({ score }: { score: number }) {
+  const tier = confidenceTier(score)
+
+  return (
+    <span className="flex flex-col items-end">
+      <span className={`text-sm font-medium ${TONE_CLASSES[tier.tone]}`}>{tier.label}</span>
+      <span className="text-xs text-muted-foreground">
+        {Math.round(score * 100)}% similarity
+      </span>
+    </span>
+  )
+}
+
+function RecommendationSkeleton() {
+  return (
+    <FoomaticCard className="p-6" aria-hidden="true">
+      <div className="flex flex-col gap-4 lg:flex-row lg:items-start lg:justify-between">
+        <div className="flex-1 space-y-3">
+          <div>
+            <div className="h-3.5 w-24 animate-pulse rounded bg-muted" />
+            <div className="mt-2 h-5 w-48 animate-pulse rounded bg-muted" />
+          </div>
+          <div className="flex gap-2">
+            <div className="h-6 w-20 animate-pulse rounded-full bg-muted" />
+            <div className="h-6 w-16 animate-pulse rounded-full bg-muted" />
+          </div>
+          <div className="flex gap-2">
+            <div className="h-6 w-32 animate-pulse rounded-full bg-muted" />
+            <div className="h-6 w-24 animate-pulse rounded-full bg-muted" />
+            <div className="h-6 w-28 animate-pulse rounded-full bg-muted" />
+          </div>
+        </div>
+        <div className="flex shrink-0 flex-col items-end gap-3">
+          <div className="h-4 w-20 animate-pulse rounded bg-muted" />
+          <div className="h-9 w-28 animate-pulse rounded-md bg-muted" />
+        </div>
+      </div>
+    </FoomaticCard>
+  )
+}
+
+// Compact hero teaser so the feature is discoverable without scrolling: shows
+// the top similar printer and links down to the full section. Renders nothing
+// while loading or when the printer has no recommendations — an absent teaser
+// is better than advertising an empty section.
+export function SimilarPrintersTeaser({ printerId }: RecommendedPrintersSectionProps) {
+  const [top, setTop] = useState<Recommendation | null>(null)
+  const [count, setCount] = useState(0)
+
+  useEffect(() => {
+    let cancelled = false
+
+    getRecommendations(printerId)
+      .then((recs) => {
+        if (cancelled) return
+        setTop(recs[0] ?? null)
+        setCount(Math.min(recs.length, 3))
+      })
+      .catch(() => {
+        // Network failure: the full section reports it; the teaser stays hidden.
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [printerId])
+
+  if (!top) {
+    return null
+  }
+
+  const tier = confidenceTier(top.score)
+
+  return (
+    <FoomaticCard className="p-4">
+      <p className="text-xs font-semibold uppercase tracking-[0.18em] text-muted-foreground">
+        Similar printers
+      </p>
+
+      <p className="mt-2 text-sm font-medium text-foreground">
+        {top.manufacturer ?? ""} {top.model ?? top.id}
+      </p>
+
+      <p className="mt-0.5 text-xs text-muted-foreground">
+        {Math.round(top.score * 100)}% similarity ·{" "}
+        <span className={TONE_CLASSES[tier.tone]}>{tier.label}</span>
+      </p>
+
+      <p className="mt-2 text-xs text-muted-foreground">
+        {count === 1
+          ? "1 printer with similar Linux driver support and hardware capabilities."
+          : `${count} printers with similar Linux driver support and hardware capabilities.`}
+      </p>
+
+      <a
+        href="#similar-printers"
+        className="mt-3 inline-flex items-center gap-1.5 rounded-md border border-border px-3 py-1.5 text-xs font-medium text-foreground hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        View all similar printers
+        <ArrowDown className="h-3.5 w-3.5" aria-hidden="true" />
+      </a>
+    </FoomaticCard>
+  )
+}
+
+export default function RecommendedPrintersSection({
+  printerId,
+}: RecommendedPrintersSectionProps) {
+  const [recommendations, setRecommendations] = useState<Recommendation[]>([])
+  const [loading, setLoading] = useState(true)
+  const [hasRecommendations, setHasRecommendations] = useState(true)
+
+  useEffect(() => {
+    let cancelled = false
+
+    async function loadData() {
+      setLoading(true)
+
+      try {
+        const recs = await getRecommendations(printerId)
+
+        if (cancelled) {
+          return
+        }
+
+        setRecommendations(recs.slice(0, 3))
+        setHasRecommendations(recs.length > 0)
+      } catch (err) {
+        // A missing shard is handled by the !ok branch above, so reaching here
+        // means a network or parse failure worth surfacing to the console.
+        if (!cancelled) {
+          console.error("Failed to load recommendations:", err)
+          setHasRecommendations(false)
+        }
+      } finally {
+        if (!cancelled) {
+          setLoading(false)
+        }
+      }
+    }
+
+    loadData()
+
+    return () => {
+      cancelled = true
+    }
+  }, [printerId])
+
+  return (
+    <section
+      id="similar-printers"
+      aria-labelledby="recommendations-heading"
+      className="scroll-mt-20 space-y-4 sm:scroll-mt-24"
+    >
+      <div>
+        <h2 id="recommendations-heading" className="text-2xl font-semibold tracking-tight">
+          Similar printers
+        </h2>
+        <p className="text-sm text-muted-foreground">
+          Matched by Linux driver compatibility and shared hardware capabilities.
+        </p>
+      </div>
+
+      <div className="grid gap-4" aria-live="polite" aria-busy={loading}>
+        {loading ? (
+          <>
+            <RecommendationSkeleton />
+            <RecommendationSkeleton />
+            <RecommendationSkeleton />
+          </>
+        ) : !hasRecommendations ? (
+          <FoomaticCard className="p-6">
+            <p className="text-sm text-muted-foreground">
+              No similar printers found in the database for this entry.
+            </p>
+          </FoomaticCard>
+        ) : (
+          recommendations.map((recommendation) => {
+            const model = recommendation.model ?? recommendation.id
+            const manufacturer = recommendation.manufacturer ?? ""
+
+            return (
+              <FoomaticCard key={recommendation.id} className="p-6">
+                <div className="flex flex-col gap-4 lg:flex-row lg:items-start lg:justify-between">
+                  <div className="space-y-3">
+                    <div>
+                      <p className="text-sm text-muted-foreground">{manufacturer}</p>
+                      <h3 className="text-xl font-semibold tracking-tight">{model}</h3>
+                    </div>
+
+                    <div className="flex flex-wrap items-center gap-2">
+                      {/* The candidate printer's own Foomatic support grade — independent
+                          of the similarity result shown on the right. */}
+                      <span className="inline-flex items-center gap-1.5">
+                        <span className="text-xs text-muted-foreground">Linux support:</span>
+                        <FoomaticStatusBadge status={recommendation.status} />
+                      </span>
+
+                      <FoomaticBadge className="border-border bg-accent/50 text-muted-foreground">
+                        {recommendation.driverCount} driver
+                        {recommendation.driverCount === 1 ? "" : "s"}
+                      </FoomaticBadge>
+
+                      {recommendation.type !== "unknown" ? (
+                        <FoomaticBadge className="border-border bg-accent/50 text-muted-foreground">
+                          {recommendation.type}
+                        </FoomaticBadge>
+                      ) : null}
+                    </div>
+
+                    {recommendation.sharedFeatures.length > 0 ? (
+                      <div>
+                        <p className="mb-1.5 text-xs font-medium text-muted-foreground">
+                          Why this printer?
+                        </p>
+                        <ul
+                          className="flex flex-wrap gap-2"
+                          aria-label={`Reasons ${manufacturer} ${model} was recommended`}
+                        >
+                          {recommendation.sharedFeatures.map((feature) => (
+                            <li key={feature}>
+                              <FoomaticBadge className="border-primary/20 bg-primary/5 text-primary">
+                                {feature}
+                              </FoomaticBadge>
+                            </li>
+                          ))}
+                        </ul>
+                      </div>
+                    ) : null}
+                  </div>
+
+                  <div className="flex shrink-0 flex-col items-end gap-3">
+                    <ConfidenceBadge score={recommendation.score} />
+
+                    <Link
+                      href={printerHref(recommendation.id, manufacturer)}
+                      className="inline-flex items-center rounded-md border border-border px-4 py-2 text-sm font-medium hover:bg-accent"
+                      aria-label={`View ${manufacturer} ${model}`}
+                    >
+                      View printer
+                    </Link>
+                  </div>
+                </div>
+              </FoomaticCard>
+            )
+          })
+        )}
+      </div>
+    </section>
+  )
+}
diff --git a/docs/foomatic-assistant-queries.md b/docs/foomatic-assistant-queries.md
new file mode 100644
index 00000000..4e15f02c
--- /dev/null
+++ b/docs/foomatic-assistant-queries.md
@@ -0,0 +1,33 @@
+# Foomatic Printer Assistant — Supported Queries
+
+What the assistant can answer, with representative phrasings. Architecture and semantics: [foomatic-assistant.md](./foomatic-assistant.md).
+
+## Look up a printer
+
+> "HP 2500C" · "tell me about the HP LaserJet 4" · "Brother HL-1050" · "hl 1050"
+
+Punctuation, spacing, and casing variants unify; "Hewlett Packard" is understood as HP. Partial names ("hp deskjet 5") list candidates to choose from; models that are not in the database ("Brother HL-2270DW") get an honest not-found answer with the closest real models.
+
+## Filter by capabilities
+
+> "find a colour laser printer" · "monochrome laser with PCL 5" · "printers with good Linux support" · "600 dpi inkjet" · "postscript 3 printers" · "show me Canon printers" · "colour laser with duplex and PCL"
+
+Filterable: colour vs monochrome, mechanism type (laser / inkjet / dot-matrix), resolution ("600 dpi", "high resolution" = at least 1200 dpi, disclosed), PostScript / PCL (with optional levels), manufacturer, and Linux support grade ("good" = Perfect or Mostly; "perfect" = Perfect only). Results state their ordering and totals. Fields the database doesn't record for a printer exclude it from matches but are reported as missing data, never as a "no". Duplex is recorded for zero printers, so duplex requests are answered with that fact instead of fake results. Constraints outside the data model ("purple", "cheap", "wireless") are named as unfilterable, never silently dropped.
+
+## Similar printers and explanations
+
+> "what printers are similar to this?" (on a printer page) · "printers similar to HP 2500C" · "why was HP LaserJet 4P recommended?" · "what are better alternatives?"
+
+Similarity answers come from the site's precomputed recommendation data, in its original order, with each candidate's similarity percentage, confidence tier, and its own Linux support grade. "Better alternatives" asks which dimension to compare (Linux support, overall similarity, resolution, driver options) unless one was named.
+
+## Support, drivers, comparison
+
+> "how good is the Linux support?" (on a printer page) · "does the HP LaserJet 4 work on Linux?" · "which driver does this printer use?" · "which printers use hplip?" · "which printers use the same driver?" · "compare HP 2500C and HP DeskJet 560C"
+
+Driver questions distinguish the recommended driver from the full listed set; "same driver" uses the recommended driver and says so. Comparisons show recorded fields side by side, with "Not recorded" for gaps, and never declare an overall winner.
+
+## Meta
+
+> "what does Perfect mean?" · "what does the similarity score mean?" · "what can you do?"
+
+These three topics are answered from fixed text grounded in the site's own definitions. Definition questions the database cannot answer ("what is PostScript?") get an honest scope statement rather than a printer list — the data records which printers support such things, not what they are. Anything else outside the printer database — weather, general Linux help, documentation content — gets a clear scope statement; the assistant is not a general documentation chatbot.
diff --git a/docs/foomatic-assistant.md b/docs/foomatic-assistant.md
new file mode 100644
index 00000000..4b83eb50
--- /dev/null
+++ b/docs/foomatic-assistant.md
@@ -0,0 +1,113 @@
+# Foomatic Printer Assistant — Architecture
+
+The assistant is a site-wide, fully client-side natural-language interface to the Foomatic data this site already generates. There is no external service, no machine-learning model, and no server: every answer is computed in the browser from the same static JSON artifacts the rest of the site fetches, so every claim the assistant makes is traceable to a record in `public/foomatic-db/`.
+
+Related docs: [foomatic-assistant-queries.md](./foomatic-assistant-queries.md) (supported query shapes), [foomatic-data-formats.md](./foomatic-data-formats.md) (artifact schemas), [foomatic-recommendation-quality.md](./foomatic-recommendation-quality.md) (similarity score semantics).
+
+## Pipeline
+
+```
+free text
+  → normalize.ts     lowercase / punctuation-fold / fused forms ("HL-1050" ≡ "hl 1050")
+  → entities.ts      printer & driver references from the real catalogue
+  → lexicon.ts       capability phrases → typed filters
+  → parse.ts         ordered rule cascade → typed AssistantQuery
+  → execute.ts       the only I/O layer: catalogue filter / shard fetch
+  → respond.ts       typed ResponsePlan blocks (pure templates)
+  → components/assistant/  React rendering (no HTML strings anywhere)
+```
+
+`engine.ts` composes the stages; the UI, the unit tests, and the eval harness all call the same `runAssistant()`, so what is tested is exactly what ships. Natural language never reaches execution: the executor operates only on the typed `AssistantQuery` produced by the parser.
+
+## Intent precedence
+
+Classification is an ordered deterministic rule cascade (`parse.ts`); earlier rules are more specific so they can never be swallowed by generic vocabulary:
+
+1. COMPARISON — two printer refs + compare/vs/difference
+2. EXPLANATION — "why" + recommendation vocabulary
+3. SIMILAR_PRINTERS — similar/alternatives/"better …"
+4. DRIVER_SEARCH — printers-for-driver phrasing, "same driver", "this driver"
+5. DRIVER_LOOKUP — driver-of-printer phrasing
+6. GENERAL_INFO — closed topics: support grades, similarity, help. Sits above
+   SUPPORT_QUERY so meaning-questions ("what does perfect support mean?") are
+   answered generally — page context must never capture a meaning-question
+   and answer it with the current printer's own values. Definition-shaped
+   questions without an explicit reference ("what is PostScript?", "what is a
+   printer driver?") get the grades definition when they are about Linux
+   support and an honest scope statement otherwise — never a printer list and
+   never a context-captured answer, because the data records which printers
+   support these things, not what they are.
+7. SUPPORT_QUERY — support question about one specific printer
+8. CAPABILITY_SEARCH — recommend/best or any capability filters
+9. PRINTER_LOOKUP — a printer reference and nothing more specific
+10. UNSUPPORTED — unclear-but-domain, or out-of-domain
+
+Suggestion chips obey a strict rule: a chip's query is the exact text of its
+label, it must parse to a supported intent (tested mechanically for every
+chip the system can produce), and contextual phrasing ("this printer",
+"this driver") stays in the message and resolves through the typed page
+context — current-page values are never substituted into the question.
+
+## Semantics that must not regress
+
+- **Unknown never means false.** Filters select on recorded values only. A printer whose `color` is `"unknown"` matches neither "colour" nor "monochrome", and is counted separately (`excludedUnknown`) so responses can say "N more printers don't record this" instead of implying absence. PDL evidence is positive-only: no recorded PostScript level or token means *unknown*, never "no PostScript".
+- **Duplex.** The current dataset records duplex for zero printers. The lexicon understands duplex vocabulary, but execution reports `INSUFFICIENT_DATA` (and still answers any other constraints in the query). No result may ever imply a printer does or does not support duplex.
+- **Similarity is PR #224's, verbatim.** SIMILAR_PRINTERS/EXPLANATION read `recommendations/<id>.json` shards: shard order is preserved, scores are never recomputed or re-ranked, tiers come from the imported `confidenceTier()` in `lib/foomatic/scoring.ts`, and `sharedFeatures` strings are quoted verbatim. The score is described as "N% similarity", never as a probability or a compatibility promise, and the candidate's own Foomatic Linux support grade is always stated separately.
+- **"Best" never ranks.** A criteria-free "best printer"/"recommend a printer" produces a clarification — the database ranks nothing overall, and no hidden default score exists.
+- **"Better" never assumes a dimension.** "Better alternatives" without a named dimension asks "Better in what way?" with four defined dimensions (Linux support, overall similarity, resolution, driver options). Each dimension is a disclosed predicate over the existing recommendation shard (grade rank strictly higher with Unknown excluded; recorded `maxDpi` strictly higher; `driverCount` strictly higher; or the plain shard). Shard order is preserved in all cases.
+- **Search ordering is disclosed, not scored.** Results are ordered by explicitly requested gradable criteria first (resolution when a dpi constraint was given), then the documented default: support-status rank, then listed-driver count, then id (the same deterministic tie-break convention as `scoreThenIdComparator`). Every search response states its ordering.
+- **Unrecognized constraints are surfaced.** "purple laser printer" runs the laser filter and explicitly says that "purple" cannot be filtered — constraints are never silently dropped, and an unanswerable constraint never fabricates a NO_MATCHES claim.
+
+## Data access
+
+All artifacts are static JSON under `public/`, fetched with `withBasePath()` and cached per tab with the promise-cache pattern from `RecommendedPrintersSection.tsx` (404 ⇒ empty, network error ⇒ cache eviction so retries refetch). Measured sizes at the current snapshot (raw / gzip):
+
+| Artifact | When loaded | Size |
+|---|---|---|
+| `printersMap.json` (catalogue) | first assistant query | 1,396,087 B / 71,147 B |
+| `driversMap.json` | first assistant query | 85,064 B / 5,519 B |
+| `printers/<id>.json` | per printer asked about | e.g. HP-LaserJet_4: 21,318 B / 5,901 B |
+| `recommendations/<id>.json` | per similarity question | e.g. HP-LaserJet_4: 3,342 B / 402 B |
+| `drivers/<id>.json` | per driver question | 0.5–268 KB raw |
+
+Nothing loads until the assistant is opened; the launcher itself carries no data. The 44 MB `printers.json`, the feature matrix, and the combined recommendations file are never fetched. Query latency measured by the harness (Node, warm caches, 468 samples): median 0.08 ms, p95 4.46 ms — network transfer of the lazy artifacts dominates, not computation.
+
+JavaScript cost (measured on a clean `next build`): the shared First Load JS is unchanged by the assistant (103 kB before and after — the launcher's increment is below the build output's rounding, inside the 9.1 KB-gzip layout chunk), and the entire lazy assistant chunk (panel UI + engine) is 62,541 B raw / 17,906 B gzip, loaded only on first open.
+
+## Tunables
+
+Values live in `lib/assistant/constants.ts`; `yarn assistant:eval` fails if this table drifts from the code.
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `MAX_QUERY_LENGTH` | 300 | input truncation bound before parsing |
+| `SCORE_EXACT` | 4 | entity score: exact id / exact "make model" match |
+| `SCORE_MODEL_EXACT` | 3 | entity score: exact model match (resolves only when unique) |
+| `SCORE_MODEL_PREFIX` | 1 | entity score: prefix match (always surfaces as ambiguity) |
+| `RESOLVE_MIN_SCORE` | 3 | minimum score for silent resolution |
+| `NEAR_MISS_MAX_LENGTH` | 20 | longest fused leftover treated as a near-miss model number |
+| `MAX_CANDIDATES` | 5 | candidates carried by an ambiguity/clarification |
+| `MAX_RESULT_CARDS` | 5 | result cards per response (totals are stated) |
+| `HIGH_RES_MIN_DPI` | 1200 | disclosed interpretation of "high resolution" |
+| `UNKNOWN_REPORT_RATIO` | 0.25 | unknown-excluded share that must be reported |
+| `MIN_COMFORTABLE_RESULTS` | 3 | below this, one-filter relaxations are offered |
+
+## Testing
+
+- `lib/assistant/__tests__/` — always-run fixture suites: a 156-utterance natural-language corpus (`corpus.ts`) pinning intents and parse details, entity-resolution cases, execution-state semantics (unknown-never-false, duplex, relaxations, better-dimensions), and grounding property tests over rendered responses (every card id and similarity percentage must trace to input data; banned terminology can never appear).
+- `lib/assistant/__tests__/assistant-artifact.test.ts` — the same engine against the real generated artifacts (skipped automatically when they are absent, e.g. CI's pre-generate test run).
+- `tools/assistant-eval/run.ts` (`yarn assistant:eval`) — corpus accuracy, a full grounding sweep, the approved end-to-end flows, latency and artifact-size measurement, and the tunables/wording drift gates. Requires generated data, like `tools/eval/`.
+
+## Extending the assistant
+
+- **New capability filter:** add the field to the catalogue projection (`lib/foomatic/catalog.ts` + docs), a lexicon row (`lexicon.ts`), a filter spec (`execute.ts` `buildSpecs`), and corpus cases. Preserve known/pass separation so unknowns stay countable.
+- **New intent:** add a cascade rule in `parse.ts` (mind the precedence list above), an executor arm, a response builder, and corpus cases.
+- **New synonym:** one lexicon row plus a corpus case. Only add vocabulary grounded in the data's own terminology or clearly common phrasing.
+
+## Known limitations
+
+- Understanding is bounded by the lexicon and rule cascade; unanticipated phrasing falls back to a clarification with examples rather than a guess.
+- Clarifications resolve through suggestion chips (each chip is a complete query); free-text follow-ups like "the second one" are not interpreted against prior candidates.
+- Purely numeric model queries ("4019") need the manufacturer ("IBM 4019") — bare numbers are treated as capability values, not names.
+- English-only vocabulary.
+- Data limitations pass through honestly: duplex is unrecorded, `connectivity` is empty upstream, and 634 printers synthesized from driver back-references have thin records.
diff --git a/docs/foomatic-data-formats.md b/docs/foomatic-data-formats.md
new file mode 100644
index 00000000..11f8d79c
--- /dev/null
+++ b/docs/foomatic-data-formats.md
@@ -0,0 +1,202 @@
+# Foomatic Pipeline — Data Formats
+
+This document is the schema reference for every JSON artifact produced by the pipeline described in [foomatic-pipeline-architecture.md](./foomatic-pipeline-architecture.md). All artifacts live under `public/foomatic-db/` and are served as static files — none require a backend to read.
+
+The canonical TypeScript types are defined in [`lib/foomatic/types.ts`](../lib/foomatic/types.ts); this document explains what each field means and which pipeline stage produces it.
+
+---
+
+## `public/foomatic-db/printer/*.json`, `driver/*.json`
+
+**Produced by:** `generate-from-xml.ts`
+**Consumed by:** `combine-data.ts`
+
+A 1:1 JSON mirror of the upstream Foomatic XML, one file per `<printer>` or `<driver>` element. Shape is whatever `fast-xml-parser` produces from the source XML (attributes prefixed with `@`, text nodes under `#text`), with one normalization: the `<prototype>` tag is renamed to `driverPrototype`. These are intermediate artifacts — nothing in the frontend reads them directly.
+
+---
+
+## `public/foomatic-db/printers.json`
+
+**Produced by:** `combine-data.ts`
+**Consumed by:** `split-printers.ts`, `vectorize.ts`, `compute-similarity.ts`
+
+The unified, normalized dataset — one record per printer, each conforming to the `Printer` interface:
+
+```ts
+interface Printer {
+  id: string                          // normalized id, e.g. "HP-LaserJet-4"
+  manufacturer: string
+  model: string
+  series?: string
+  connectivity?: string[]             // ["USB", "Network", ...]
+  recommended_driver?: string         // e.g. "driver/Postscript-hp"
+  drivers?: Driver[]
+  type?: string                       // "inkjet" | "laser" | "dot-matrix" | "unknown"
+  status?: string                     // "Perfect" | "Mostly" | "Unsupported" | "Unknown"
+  notes?: string                      // HTML from upstream XML — sanitize before rendering
+  functionality?: string              // raw Foomatic grade: "A" | "B" | "C" | "?"
+  commandsets?: string[]              // normalized PDL tokens, e.g. ["PCLXL", "POSTSCRIPT"]
+  ppdOptions?: PpdOption[]
+  color?: boolean | "unknown"
+  duplex?: boolean | "unknown"
+  recommended?: boolean
+  psLevel?: number | null             // 0–3
+  pclLevel?: number | null            // 0, 3, 4, 5, or 6
+  maxDpi?: number | null
+}
+
+interface Driver {
+  id: string
+  name: string
+  url?: string
+  comments?: string                   // HTML from upstream XML — sanitize before rendering
+  hasPpd?: boolean
+  ppdPath?: string
+  execution?: { ghostscript?: string | null; filter?: string | null; prototype: string }
+}
+```
+
+`notes` and `driver.comments` are sourced from upstream contributor-editable XML and **must** be passed through `sanitizeFoomaticHtml()` (`lib/foomatic/sanitize.ts`) before being rendered with `dangerouslySetInnerHTML` — see that file's usage in `components/foomatic/PrinterPageClient.tsx`.
+
+---
+
+## `public/foomatic-db/printersMap.json`
+
+**Produced by:** `split-printers.ts`
+**Consumed by:** the directory listing page (`app/foomatic/printers/page.tsx`) and `generateStaticParams()` in `app/foomatic/printer/[make]/[id]/page.tsx`
+
+A lightweight projection of `printers.json`, one entry per printer, used so a list/filter view doesn't need to download every printer's full driver/PPD detail. Records are built by `toPrinterSummary()` in [`lib/foomatic/catalog.ts`](../lib/foomatic/catalog.ts) — the single source of truth for this schema — and the file is written **minified** (it is fetched by the browser; pretty-printing cost ~490 KB of raw payload for no consumer benefit).
+
+```ts
+interface PrinterSummary {
+  id: string
+  manufacturer: string
+  model: string
+  type?: string                // "laser" | "inkjet" | "dot-matrix" | "unknown"
+  status?: string              // "Perfect" | "Mostly" | "Unsupported" | "Unknown"
+  driverCount?: number
+  functionality?: string       // raw Foomatic grade: "A" | "B" | "C" | "?"
+  color?: boolean | "unknown"  // tri-state preserved from the full record
+
+  // Capability fields. Each is OMITTED when the source data does not
+  // establish it — an absent key means "not recorded in Foomatic",
+  // never "the printer lacks this capability".
+  maxDpi?: number              // from Printer.maxDpi (when a number)
+  psLevel?: number             // from Printer.psLevel (when a number)
+  pclLevel?: number            // from Printer.pclLevel (when a number)
+  cs?: string[]                // Printer.commandsetTokens (when non-empty)
+  rd?: string                  // recommended driver family: Printer.recommended_driver
+                               // collapsed via normalizeDriverFamily() (when present)
+}
+```
+
+`driverCount` is `drivers.length` from the full record; `type`/`status`/`functionality`/`color` default to `"unknown"`/`"Unknown"`/`"?"`/`"unknown"` respectively if absent.
+
+Two capability notes:
+
+- The tri-state fields (`color`, `type`) keep an explicit `"unknown"` value because existing consumers branch on it; the newer optional fields use key omission instead, which is cheaper across ~6.6k records. Both conventions mean the same thing: absence of evidence, not evidence of absence.
+- `duplex` is deliberately **not** part of this projection: upstream Foomatic data records duplex capability for zero printers at the current snapshot, so there is nothing to store or filter on. If upstream ever starts recording it, adding it here is a deliberate schema decision (see `lib/foomatic/__tests__/catalog.test.ts`).
+
+The generated artifact is validated record-by-record against `printers.json` by `lib/foomatic/__tests__/catalog-artifact.test.ts` (skipped automatically when the generated data is absent, e.g. in CI's pre-generate test run).
+
+---
+
+## `public/foomatic-db/printers/<id>.json`
+
+**Produced by:** `split-printers.ts`
+**Consumed by:** the printer detail page (`PrinterPageClient.tsx`)
+
+One full `Printer` record per printer (same shape as an entry in `printers.json`), written individually so a detail-page visit only fetches data for that one printer.
+
+---
+
+## `public/foomatic-db/feature-matrix.json`
+
+**Produced by:** `vectorize.ts`
+**Consumed by:** `compute-similarity.ts`
+
+```ts
+interface FeatureMatrix {
+  printerCount: number
+  featureCount: number
+  featureNames: string[]   // e.g. ["recommended_driver:postscript", ..., "res:2400plus"]
+  vocab: {
+    recommendedDrivers: string[]
+    supportedDrivers: string[]
+    types: string[]
+    commandsets: string[]  // only commandsets meeting MIN_COMMANDSET_FREQUENCY (20)
+  }
+  ids: string[]             // printer ids, parallel-indexed with matrix rows
+  matrix: number[][]        // one weighted feature vector per printer
+}
+```
+
+`matrix[i]` corresponds to `ids[i]` and is encoded in the exact order of `featureNames`. See [foomatic-recommendation-quality.md](./foomatic-recommendation-quality.md) for what each feature means and its weight.
+
+---
+
+## `public/foomatic-db/recommendations.json`
+
+**Produced by:** `compute-similarity.ts`
+**Consumed by:** dev/debug tooling and as the source for the per-printer split below (not fetched directly by the frontend — see `recommendations/<id>.json`)
+
+```ts
+interface Output {
+  version: string                    // "2.0.0"
+  printerCount: number
+  topK: number                       // 10
+  recommendations: {
+    [printerId: string]: Array<{
+      id: string                     // recommended printer's id
+      score: number                  // engineered similarity in [0, 1): IDF-weighted
+                                     // cosine x evidence damping x conflict penalties,
+                                     // rounded to 3 decimals — see the Scoring Model
+                                     // section of foomatic-recommendation-quality.md
+      sharedFeatures: string[]       // human-readable explanation strings
+    }>
+  }
+}
+```
+
+The score is deterministic and bounded. It is **not** a probability, not a
+guarantee that a printer will work, and not a human-validated accuracy figure —
+it summarizes how much recorded Foomatic evidence two printers share, minus
+penalties for conflicting capabilities. The UI maps it onto four tiers defined
+in `lib/foomatic/scoring.ts` (`confidenceTier()`).
+
+`sharedFeatures` entries are generated by `computeSharedFeatures()` and look like `"Shared command set: PostScript"`, `"Color printing"`, `"1200 dpi resolution"`, `"Excellent Linux driver support"` — these are rendered directly as the "why this printer?" list on the printer detail page.
+
+---
+
+## `public/foomatic-db/recommendations/<id>.json`
+
+**Produced by:** `compute-similarity.ts` (same run as above, written per-printer for fetch efficiency)
+**Consumed by:** `RecommendedPrintersSection.tsx`
+
+A single printer's recommendation array — `recommendations.json`'s `recommendations[id]` value, plus the display fields each card needs:
+
+```ts
+type RecommendationsForPrinter = Array<{
+  id: string
+  score: number
+  sharedFeatures: string[]
+  // Denormalized from printers.json so the printer page can render the
+  // recommendation cards from this one file alone. Defaults mirror the
+  // printersMap.json projection exactly.
+  manufacturer?: string
+  model?: string
+  status: string                     // "Perfect" | "Mostly" | ... | "Unknown"
+  type: string                       // "laser" | "inkjet" | "dot-matrix" | "unknown"
+  driverCount: number
+}>
+```
+
+The detail page only ever needs the current printer's own recommendations, so fetching this file instead of the ~23 MB combined `recommendations.json` is what keeps the printer detail page's initial load small (see commit `perf(recommendations): split recommendation data per printer`).
+
+The denormalized display fields cost roughly 0.9 KB per shard (median 3.3 KB at the current snapshot) but remove a second ~1.5 MB `printersMap.json` fetch that the section previously needed purely to resolve manufacturer/model/status for the three cards it renders — a net reduction from ~1,495 KB to ~3 KB per printer-page visit. They are intentionally *not* added to the combined `recommendations.json`, which stays a compact diagnostic artifact.
+
+---
+
+## Versioning
+
+`recommendations.json` carries an explicit `version` field (`"2.0.0"` as of the resolution-aware similarity feature addition). There is no compatibility-checking consumer of this field today — it exists as a marker for pipeline output changes across the feature-addition history documented in [foomatic-recommendation-quality.md](./foomatic-recommendation-quality.md). If the feature vector schema changes again (a new weighted dimension, a changed weight, or a different scoring formula), bump this version so it's traceable in the artifact itself.
diff --git a/docs/foomatic-pipeline-architecture.md b/docs/foomatic-pipeline-architecture.md
new file mode 100644
index 00000000..205fb23f
--- /dev/null
+++ b/docs/foomatic-pipeline-architecture.md
@@ -0,0 +1,192 @@
+# Foomatic Recommendation Pipeline — Architecture
+
+## Overview
+
+This document describes the offline, reproducible recommendation pipeline that turns the upstream [OpenPrinting/foomatic-db](https://github.com/OpenPrinting/foomatic-db) XML dataset into the static printer directory, printer detail pages, and "similar printers" recommendations served from `openprinting.github.io/foomatic`.
+
+The pipeline is designed to:
+
+- Run entirely offline, with no server-side inference at request time
+- Produce static, versioned JSON artifacts consumable by a static-exported Next.js site (no backend)
+- Be fully reproducible from upstream Foomatic XML on every run
+- Refresh automatically via GitHub Actions as the upstream database changes
+
+This is the GSoC "Track A" deliverable: *an offline pipeline for printer similarity and compatibility analysis, exported as static artifacts for static-site consumption.*
+
+---
+
+## High-Level Architecture
+
+The pipeline is divided into seven sequential stages, each implemented as an independent `tsx` script under `scripts/foomatic/`, orchestrated by `scripts/foomatic/data-generate.ts`:
+
+```
+1. generate-from-xml.ts   XML → JSON ingestion
+2. generate-ppds.sh       PPD compilation (Linux only)
+3. combine-data.ts        Normalization + enrichment
+4. split-printers.ts      Performance: per-printer artifact split
+5. split-drivers.ts       Performance: per-driver artifact split
+6. vectorize.ts           Feature engineering
+7. compute-similarity.ts  Similarity computation + recommendations
+```
+
+Each stage reads the previous stage's output from `public/foomatic-db/` and writes its own output back to the same directory, so the pipeline can be re-run incrementally or in full. Stage failure is fail-fast: if any step exits non-zero, the orchestrator stops immediately rather than continuing with stale or partial data.
+
+---
+
+## Pipeline Flow
+
+```
+                         OpenPrinting/foomatic-db (git, upstream)
+                                       │
+                                       │  git clone / pull
+                                       ▼
+                  cache/foomatic-db/db/source/{printer,driver}/*.xml
+                                       │
+                         ┌─────────────┴─────────────┐
+                         │   generate-from-xml.ts     │  fast-xml-parser
+                         └─────────────┬─────────────┘
+                                       ▼
+              public/foomatic-db/printer/*.json   driver/*.json
+                                       │
+                         ┌─────────────┴─────────────┐
+                         │     generate-ppds.sh       │  foomatic-compiledb
+                         │  (skipped on Windows /     │  (cached by git revision)
+                         │   --skip-ppd)              │
+                         └─────────────┬─────────────┘
+                                       ▼
+                              public/ppds/*.ppd
+                                       │
+                         ┌─────────────┴─────────────┐
+                         │      combine-data.ts       │  joins printer ⇄ driver
+                         │                             │  graphs, derives all
+                         │                             │  normalized attributes
+                         └─────────────┬─────────────┘
+                                       ▼
+                       public/foomatic-db/printers.json
+                       (the "unified and normalized printer
+                        metadata dataset" deliverable)
+                                       │
+                         ┌─────────────┴─────────────┐
+                         │      split-printers.ts     │  performance split
+                         └─────────────┬─────────────┘
+                                       ▼
+       public/foomatic-db/printersMap.json   printers/<id>.json
+                                       │
+                         ┌─────────────┴─────────────┐
+                         │        vectorize.ts        │  builds vocabularies,
+                         │                             │  encodes weighted
+                         │                             │  feature vectors
+                         └─────────────┬─────────────┘
+                                       ▼
+                   public/foomatic-db/feature-matrix.json
+                                       │
+                         ┌─────────────┴─────────────┐
+                         │   compute-similarity.ts    │  IDF-weighted similarity,
+                         │                             │  evidence + conflict
+                         │                             │  scoring, top-10
+                         └─────────────┬─────────────┘
+                                       ▼
+        public/foomatic-db/recommendations.json (full map)
+        public/foomatic-db/recommendations/<id>.json (per-printer)
+                                       │
+                                       ▼
+                    Next.js static export (output: "export")
+    app/foomatic/printers/page.tsx · app/foomatic/printer/[make]/[id]/page.tsx
+                  (fetched client-side, zero backend, per the
+                   Track B static-site requirement)
+```
+
+---
+
+## Stage Details
+
+### 1. XML Ingestion — `generate-from-xml.ts`
+
+- Clones `OpenPrinting/foomatic-db` into `cache/foomatic-db` on first run, or `git pull`s it on subsequent runs (a failed pull is logged but non-fatal, so a stale local cache doesn't block the rest of the pipeline).
+- Parses every `printer/*.xml` and `driver/*.xml` file with `fast-xml-parser`, configured to preserve XML attributes (`@`-prefixed) and rename the `<prototype>` tag to `driverPrototype` to avoid colliding with the reserved JavaScript identifier.
+- Normalizes driver `<printers><printer>` references (which appear as either bare strings or `{id, ...}` objects in the source XML) into a single object shape with a `.id` field, so downstream code does not need to special-case both forms.
+- Output: one JSON file per printer/driver, mirroring the XML structure, under `public/foomatic-db/printer/` and `public/foomatic-db/driver/`.
+
+### 2. PPD Compilation — `generate-ppds.sh`
+
+- Invokes `foomatic-compiledb` (from the `foomatic-db-engine` system package) to generate one `.ppd` file per supported printer/driver pair, used for the "Download PPD" / "Preview PPD" features on the printer detail page.
+- **Linux/CI only.** On Windows, or when `--skip-ppd` / `SKIP_PPD_GEN=true` is set, this stage is skipped entirely and the pipeline continues without PPDs — `combine-data.ts` simply records `hasPpd: false` for every driver in that case.
+- Caches by the foomatic-db git revision: it records the upstream HEAD SHA in `public/ppds/.foomatic-db-revision` and skips regeneration if the SHA hasn't changed and PPDs already exist (unless `--force`/`FORCE_PPD_GEN=true`), avoiding an expensive full recompilation on every CI run when the upstream database hasn't moved.
+
+### 3. Normalization + Enrichment — `combine-data.ts`
+
+This is the core data-unification stage. For every printer it:
+
+- Joins the printer and driver JSON graphs bidirectionally — a printer's `drivers` list and a driver's `printers` list are cross-referenced so each side knows about the other, even when only one side declares the relationship in the source XML. If a driver references a printer ID that has no printer JSON file of its own, a minimal stub printer record is synthesized from the ID (split on `-` into manufacturer/model) rather than silently dropping the driver.
+- Derives normalized attributes via pure helper functions (now shared with the test suite in `lib/foomatic/printer-attributes.ts`):
+  - `getFunctionalityStatus` — maps the raw Foomatic functionality grade (`A`/`B`/`C`/`?`) to a human-readable status (`Perfect`/`Mostly`/`Unknown`/`Unsupported`).
+  - `getPrinterType` — inspects `<mechanism>` to classify a printer as `inkjet`, `laser`, `dot-matrix`, or `unknown`.
+  - `getCommandsetTokens` / `normalizeCommandsetToken` — extracts page-description-language tokens from `<autodetect>` (including IEEE1284 `CMD:` device-ID strings) and folds dozens of upstream spelling variants (`PostScript`, `PS2`, `Adobe PostScript`, …) into a small set of canonical tokens (`POSTSCRIPT`, `PCLXL`, `PCL5E`, `PCL`, …).
+  - `getColorCapability` / `getBooleanCapability` — resolves color support from `<mechanism>` first, falling back to free-text capability fields.
+  - `getPSLevel` / `getPCLLevel` — parses PostScript/PCL language-level strings into normalized integer tiers.
+  - `getMaxDpi` — resolves maximum print resolution from `<mechanism><resolution><dpi>`.
+- Resolves each printer's `recommended_driver` (the printer's own declared driver if present, otherwise the first known supporting driver) and builds full driver detail records, including whether a compiled PPD exists for that driver (`hasPpd`/`ppdPath`).
+- Output: `public/foomatic-db/printers.json` — the single unified, normalized dataset that every later stage and the frontend both read from.
+
+### 4. Performance Split — `split-printers.ts`
+
+`printers.json` contains every printer's full driver/PPD/option detail and is too large to ship to every page. This stage splits it into:
+
+- `printersMap.json` — a lightweight per-printer projection (`id`, `manufacturer`, `model`, `type`, `status`, `functionality`, `driverCount`, `color`) used by the directory listing page and to drive Next.js's `generateStaticParams()` for static export.
+- `printers/<id>.json` — one full-detail file per printer, fetched only when a user visits that printer's detail page.
+
+### 5. Performance Split — `split-drivers.ts`
+
+Applies the same treatment to the driver graph, producing `drivers.json`, a lightweight `driversMap.json` index, and one `drivers/<id>.json` per driver for the driver detail pages.
+
+### 6. Feature Engineering — `vectorize.ts`
+
+Builds a weighted numeric feature vector for every printer. See [foomatic-recommendation-quality.md](./foomatic-recommendation-quality.md) for the full feature list, weights, and the rationale/timeline behind each one. Output: `public/foomatic-db/feature-matrix.json`.
+
+### 7. Similarity Computation — `compute-similarity.ts`
+
+For every printer, scores every other printer with the full model described below (IDF-weighted cosine, evidence damping, capability-conflict penalties), keeps the top 10 candidates at or above `MIN_SIMILARITY_SCORE`, orders them deterministically (score, then id — see `lib/foomatic/scoring.ts`), and generates human-readable "why this printer?" explanations. See [foomatic-data-formats.md](./foomatic-data-formats.md) for the exact output schema.
+
+---
+
+## Similarity Methodology Summary
+
+The recommendation engine is an **engineered similarity model** — weighted feature similarity with explicit, individually-motivated corrections — not a trained/learned model and not an embedding model. This was a deliberate scope choice: the feature space (driver compatibility, page-description-language support, color, resolution tier) is small, well-understood, and directly interpretable, which is what makes the "why this printer?" explanation feature possible. There is no `scikit-learn`-equivalent or embedding library dependency in this pipeline; the only data-processing dependency is `fast-xml-parser` for stage 1. Product-level descriptions may call the portal "AI-driven"; at the implementation level this is deterministic engineered similarity, and the docs use that language.
+
+The published score for a candidate pair is
+
+```
+score(a, b) = cos_idf(a, b) * (1 - exp(-k / EVIDENCE_TAU)) * conflictPenalty(a, b)
+```
+
+computed in this order:
+
+1. One-hot feature encoding with fixed per-group weights (`vectorize.ts`)
+2. IDF scaling of driver-family and command-set dimensions — `idf(t) = ln(1 + N/df(t))`, mean-normalized — so ubiquitous drivers (e.g. `postscript`, 1,746 printers) carry less weight than rare, diagnostic ones
+3. Cosine similarity over the weighted vectors
+4. Evidence damping: `k` counts dimensions active in **both** vectors; near-empty vectors can no longer score as perfect matches
+5. Capability-conflict penalties for known type, colour, and extreme-resolution contradictions (`lib/foomatic/scoring.ts`)
+6. `MIN_SIMILARITY_SCORE` floor on the final damped score
+7. Top-K selection with deterministic score-then-id ordering
+8. Explanation generation (`computeSharedFeatures()`) and per-printer shard output
+
+Every constant in that chain is documented, with measured justification, in [foomatic-recommendation-quality.md](./foomatic-recommendation-quality.md).
+
+Computation is brute-force O(n²) — every printer is compared against every other printer. At the current scale of the Foomatic database (several thousand printers), this completes in well under a minute (see `compute-similarity.ts` runtime logging). This is a known, accepted scaling limit; see the **Production Readiness** notes in the project's GSoC midterm audit for the documented ceiling and mitigation options if the dataset grows substantially.
+
+---
+
+## CI/CD Automation
+
+Two GitHub Actions workflows run the pipeline:
+
+| Workflow | Trigger | Similarity computation |
+|---|---|---|
+| `.github/workflows/build.yml` | `pull_request`, `push` to `master`, `workflow_dispatch` | **Skipped** (`FOOMATIC_SKIP_SIMILARITY=1`) — keeps PR checks fast |
+| `.github/workflows/deploy.yml` | `push` to `master`, weekly `schedule` (`0 2 * * 1`, Mondays 02:00 UTC), `workflow_dispatch` | **Runs in full** |
+
+The full pipeline runs automatically as the first half of the `build` script (`yarn generate && next build && ...`), where `yarn generate` invokes `scripts/foomatic/data-generate.ts` before Next.js compiles. Both workflows reach it by running `yarn build`. The weekly cron in `deploy.yml` is what keeps recommendations fresh as the upstream `foomatic-db` repository evolves, without requiring a manual trigger — this satisfies the proposal's "automated GitHub Actions workflows for scheduled data refresh and retraining" deliverable.
+
+Both workflows install the same system dependencies needed for XML/PPD processing: `foomatic-db-engine`, `foomatic-db-compressed-ppds`, `cups-filters`, `ghostscript`, `bsdmainutils`, `libxml2-utils`, `xsltproc`.
+
+For the exact commands to reproduce this locally, see [foomatic-retraining.md](./foomatic-retraining.md).
diff --git a/docs/foomatic-recommendation-quality.md b/docs/foomatic-recommendation-quality.md
new file mode 100644
index 00000000..fde7f247
--- /dev/null
+++ b/docs/foomatic-recommendation-quality.md
@@ -0,0 +1,275 @@
+# Foomatic Recommendation Quality — Evolution and Evidence
+
+This document quantifies how the similarity engine's recommendation quality changed across this branch's feature-addition commits. It exists to answer the question a GSoC reviewer will reasonably ask: *"you say you fixed recommendation quality — show me."*
+
+## Methodology
+
+The pipeline (`scripts/foomatic/vectorize.ts` + `compute-similarity.ts`) is deterministic: same input data + same code = same output. This makes historical comparison straightforward — for each milestone commit below, the **exact pipeline code from that commit** was extracted and re-run against the **current, full `printers.json`** (6,573–6,657 printers, depending on milestone — see table). Holding the dataset fixed and varying only the scoring code isolates the effect of each feature addition from incidental upstream data drift.
+
+This reproduces the same `logScoreDistribution()`/`logSpotCheck()` diagnostics the pipeline already prints on every run (`compute-similarity.ts`), just captured across history instead of a single point in time.
+
+| Milestone | Commit | Feature set | Features encoded |
+|---|---|---|---|
+| Baseline | `a370869` | Driver family + printer type + functionality | 429 |
+| +Color | `6a93780` | + color capability | 430 |
+| +Commandsets | `f3aab1f` | + PDL token one-hot (PostScript, PCLXL, PCL5E, …) | 455 |
+| +PS/PCL level | `73a9161` | + PostScript/PCL capability tier | 459 |
+| +Resolution | `2d6f3b7` | + DPI resolution tier | 463 |
+
+---
+
+## Scoring Model
+
+The published score is not a bare cosine. Three corrections are applied, each
+introduced because a measured failure mode demanded it:
+
+```
+score(a,b) = cos(a,b) . (1 - exp(-k / tau)) . PROD(conflict penalties)
+```
+
+**1. IDF-weighted features.** Driver-family and command-set dimensions are scaled
+by `idf(t) = ln(1 + N / df(t))`, renormalized to mean 1 across the vocabulary.
+Sharing `postscript` (1,746 of 6,657 printers) yields weight 0.62; sharing
+`necp6` (8 printers) yields 2.64. Without this, every PostScript printer looked
+equally similar to every other, and the top-3 was an arbitrary slice of a
+1,700-printer cluster.
+
+**2. Evidence damping.** Cosine on sparse one-hot vectors returns exactly 1.0
+whenever both vectors are near-empty: two printers sharing one dimension, with
+every other attribute unknown, are geometrically identical. `k` counts the
+dimensions on which both printers are non-zero, and `1 - exp(-k/tau)` with
+`tau = 4` maps k = 1 -> 0.22, 4 -> 0.63, 8 -> 0.86, 12 -> 0.95. Before this,
+recommendations resting on a single catch-all driver scored *higher* on average
+(0.992) than recommendations backed by eleven shared features (0.984).
+
+**What the score is - and is not.** The score is deterministic and bounded in
+[0, 1). It is **not** a probability, not a statistically calibrated confidence,
+not a guarantee of printer compatibility, and not a human-validated accuracy
+figure. The UI presents it as "N% similarity" under one of four tiers -
+**High confidence** (>= 0.85), **Good match** (>= 0.70), **Moderate match**
+(>= 0.50), **Limited evidence** (below). The thresholds sit at the midpoints
+between the mean scores of the observed shared-feature evidence bands
+(<=1 feature: 0.393, 2-3: 0.593, 4-6: 0.787, 7+: 0.921), so each tier reflects
+a real difference in supporting evidence rather than a cosmetic slice of the
+distribution. Measured on the full artifact set, "High confidence"
+recommendations are 90% seven-plus-feature matches with zero capability
+conflicts, and all 1,803 generic-driver-only pairs fall in "Limited evidence".
+
+**3. Capability-conflict penalties.** The vector space can express agreement but
+not contradiction, so a mono printer sharing a driver family with a colour one
+still scored well despite being unable to substitute for it. Hard substitution
+barriers are applied multiplicatively (see the table below).
+
+---
+
+## The Collapse Problem
+
+The baseline pipeline (driver family + type + functionality only) suffered from a textbook similarity-collapse failure mode: many functionally different printers share the same generic driver, so their feature vectors were nearly identical regardless of actual hardware differences. The measured signature of this is **score saturation** — recommendations clustering at a perfect cosine score of 1.000 even between printers that are not, in fact, equivalent.
+
+### Score saturation (% of recommendations scoring >= 0.9995, i.e. "exact match")
+
+Feature engineering alone reduced saturation from 92.0% to 79.8%, but did not
+solve it: four in five recommendations were still presented as perfect matches.
+The scoring-model corrections above removed it entirely.
+
+| Stage | Saturated | Mean score | p10 |
+|---|---|---|---|
+| Baseline (driver + type + functionality) | **92.0%** | 0.996 | 1.000 |
+| + colour | 88.1% | 0.972 | 0.967 |
+| + commandsets | 84.4% | 0.974 | 0.955 |
+| + PS/PCL level | 82.8% | 0.973 | 0.953 |
+| + resolution (feature engineering complete) | 79.8% | 0.969 | 0.935 |
+| **+ IDF, evidence damping, conflict penalties** | **0.0%** | **0.814** | **0.393** |
+
+Rows through "feature engineering complete" are measured over all retained top-10 recommendations, the pipeline's historical diagnostic basis. The final row, and every current-state figure in this document, is measured over the 19,606 recommendations actually displayed (top-3 per printer); on that displayed basis, pre-correction saturation was 86.8% (17,212 of 19,827).
+The score histogram changed from a single spike (17,212 of 19,827 at 1.0) to a
+spread distribution peaking at 0.9 and reaching down to 0.3.
+
+The decisive metric is the correlation between how much evidence supports a
+recommendation and the confidence shown for it:
+
+| | Before | After |
+|---|---|---|
+| Corr(shared features, score) | 0.078 | **0.849** |
+| Mean score, weak evidence (<= 1 shared feature) | 0.992 | 0.393 |
+| Mean score, strong evidence (>= 2) | 0.984 | 0.859 |
+
+Before, the confidence signal was *inverted*: thin recommendations scored higher
+than well-supported ones. It is now strongly aligned.
+
+### Recommendation churn
+
+Comparing the **#1 recommendation** for every printer between the baseline and final feature sets:
+
+> **4,546 of 6,573 printers (69.2%) received a different top recommendation** once color, commandset, PS/PCL level, and resolution features were added.
+
+This is the direct, measured effect of the four feature-addition commits — not an estimate. A concrete example from that diff:
+
+- **Alps-MD-2010** (baseline): top recommendation was **Citizen-printiva700** — a different manufacturer entirely, sharing only a generic driver family.
+- **Alps-MD-2010** (final): top recommendation became **Alps-MD-2300** — a same-manufacturer, same-series printer, a substantially more sensible suggestion surfaced once commandset and capability features were available to discriminate within the driver-family cluster.
+
+---
+
+## Feature Weights and Tunables
+
+All weights live as named constants at the top of `scripts/foomatic/vectorize.ts`; thresholds live in `compute-similarity.ts` and `RecommendedPrintersSection.tsx`. They are the knobs to turn when tuning recommendation behaviour.
+
+| Constant | Value | Where | Effect |
+|---|---|---|---|
+| `RECOMMENDED_DRIVER_WEIGHT` | 3.0 | `vectorize.ts` | Dominant signal — two printers sharing a preferred Linux driver are strongly similar |
+| `COMMANDSET_WEIGHT` | 1.5 | `vectorize.ts` | One-hot per normalized PDL token; highest-weighted post-baseline feature |
+| `SUPPORTED_DRIVER_WEIGHT` | 1.0 | `vectorize.ts` | One-hot per additional supported driver family |
+| `COLOR_WEIGHT` | 1.0 | `vectorize.ts` | Binary colour capability |
+| `LANG_WEIGHT` | 1.0 | `vectorize.ts` | PostScript / PCL support present |
+| `RESOLUTION_WEIGHT` | 0.75 | `vectorize.ts` | One-hot across four DPI tiers (≤300, ≤600, ≤1200, >1200) |
+| `TYPE_WEIGHT` | 0.5 | `vectorize.ts` | Mechanism class (laser / inkjet / dot-matrix) |
+| `LANG_LEVEL_WEIGHT` | 0.5 | `vectorize.ts` | Bonus for matching PostScript 3 / PCL 6 specifically |
+| `FUNCTIONALITY_WEIGHT` | 0.25 | `vectorize.ts` | Linux support grade (A/B/C), weakest signal |
+| `MIN_COMMANDSET_FREQUENCY` | 20 | `vectorize.ts` | Commandset tokens rarer than this are dropped from the vocabulary as noise |
+| `TOP_K` | 10 | `compute-similarity.ts` | Candidates retained per printer |
+| `MIN_SIMILARITY_SCORE` | 0.35 | `lib/foomatic/scoring.ts` | Floor on the damped score; removes single-dimension matches automatically |
+| `EVIDENCE_TAU` | 4 | `lib/foomatic/scoring.ts` | Damping constant in `1 - exp(-k/tau)`; larger = harsher on thin evidence |
+| `TYPE_CONFLICT_PENALTY` | 0.5 | `lib/foomatic/scoring.ts` | Applied when both mechanism types are known and differ |
+| `COLOR_CONFLICT_PENALTY` | 0.6 | `lib/foomatic/scoring.ts` | Applied when one prints colour and the other does not |
+| `RESOLUTION_CONFLICT_PENALTY` | 0.7 | `lib/foomatic/scoring.ts` | Applied when max resolutions differ by >= 4x |
+| `RESOLUTION_CONFLICT_RATIO` | 4 | `lib/foomatic/scoring.ts` | Max-DPI ratio at/above which the resolution penalty applies |
+| `CONFIDENCE_HIGH_THRESHOLD` | 0.85 | `lib/foomatic/scoring.ts` | "High confidence" tier floor - midpoint between the 4-6 and 7+ shared-feature evidence-band mean scores |
+| `CONFIDENCE_GOOD_THRESHOLD` | 0.7 | `lib/foomatic/scoring.ts` | "Good match" floor - midpoint between the 2-3 and 4-6 evidence bands |
+| `CONFIDENCE_MODERATE_THRESHOLD` | 0.5 | `lib/foomatic/scoring.ts` | "Moderate match" floor; below it sits "Limited evidence", where every generic-driver-only pair lands |
+
+Raising a weight increases how much that attribute pulls two printers together; the vectors are L2-normalized by the cosine denominator, so only the *relative* magnitudes matter.
+
+---
+
+## Feature-by-Feature Timeline
+
+### Color features (`6a93780`, 2026-06-10)
+
+**Problem:** Driver-family-only similarity could recommend a monochrome printer in place of a color one, since many mono and color printers in the same product family share a driver.
+**Change:** Added a 1.0-weighted binary color feature (`vectorize.ts`).
+**Measured effect:** Saturation dropped from 92.0% → 88.1%; mean score dropped from 0.996 → 0.972, the largest single-commit drop in mean score of any feature addition — consistent with color being the single most common source of false-positive matches in the baseline.
+
+### Commandset features (`f3aab1f`, 2026-06-10)
+
+**Problem:** Driver family is a coarse compatibility proxy — two printers can share a driver family without supporting the same page-description language (PostScript vs. PCL vs. ESC/P).
+**Change:** Added a 1.5-weighted one-hot feature per normalized commandset token (the highest weight of any feature added after the baseline), with `normalizeCommandsetToken()` folding ~20 upstream spelling variants into canonical tokens (`POSTSCRIPT`, `PCLXL`, `PCL5E`, `PCL`, …), filtered to commandsets appearing in at least 20 printers (`MIN_COMMANDSET_FREQUENCY`) to avoid vocabulary noise from rare tokens.
+**Measured effect:** Saturation dropped from 88.1% → 84.4%; feature count grew from 430 → 455 (25 new commandset dimensions passed the frequency filter).
+
+### PostScript/PCL level features (`73a9161`, 2026-06-10)
+
+**Problem:** Commandset matching alone treats "supports some PostScript" as equivalent regardless of capability tier — a PS1 printer and a full PS3 printer would score identically on the commandset feature.
+**Change:** Added separate language-support and level-bonus features (1.0 + 0.5 weight) for PostScript level 3 and PCL level 6, refining within-language-family matching.
+**Measured effect:** Saturation dropped from 84.4% → 82.8%.
+
+### Resolution features (`2d6f3b7`, 2026-06-12)
+
+**Problem:** Two printers with identical driver, commandset, and language support could still differ enormously in print quality (300 dpi vs. 2400 dpi) and still be scored as near-identical.
+**Change:** Added a 0.75-weighted one-hot feature across four DPI tiers (≤300, 300–600, 600–1200, >1200).
+**Measured effect:** Saturation dropped from 82.8% → 79.8% — the largest p10 drop of any single addition (0.953 → 0.935), reflecting that resolution tier is a meaningfully independent axis of variation across the dataset.
+
+---
+
+## Performance: Per-Printer Data Split (`983f915`, 2026-06-12)
+
+Not a scoring-quality change, but a necessary scale fix once `recommendations.json` grew large: the full recommendation map for ~6,600 printers serializes to **23.8 MB** at the current snapshot (see `compute-similarity.ts` runtime logging). Shipping that to every printer detail page visit would be a significant and unnecessary page-weight cost, since a single page only ever needs one printer's own top-10 list.
+
+The fix splits the combined file into one small file per printer (median 3.3 KB, max 6.0 KB at the current snapshot, including denormalized card fields) under `recommendations/<id>.json` (see [foomatic-data-formats.md](./foomatic-data-formats.md#publicfoomatic-dbrecommendationsidjson)), so `RecommendedPrintersSection.tsx` fetches only the relevant slice instead of the full ~24 MB map.
+
+---
+
+## What the Evaluation Proves - and What It Does Not
+
+The evaluation harness (below) measures internal, mechanically checkable
+properties of the generated artifacts. Re-run against the current artifacts it
+establishes that:
+
+- **The engine is discriminative.** 0% of displayed scores saturate at 1.0
+  (baseline before the scoring-model corrections: 86.8%).
+- **Confidence tracks evidence.** Correlation between shared-feature count and
+  score is 0.849 (baseline: 0.078, with weak pairs *outscoring* strong ones).
+  A single-signal pair mathematically cannot leave the bottom tier.
+- **Capability conflicts are penalized.** Across displayed recommendations:
+  type contradictions 0%, colour contradictions 0.2%, >=4x resolution gaps 0.04%.
+- **Explanations are truthful.** Every user-visible claim (drivers, command
+  sets, PS/PCL levels, colour, type, resolution tiers) is re-validated against
+  `printers.json`: 0 false or misleading claims (baseline: 1,470 false
+  resolution claims).
+- **Output is reproducible.** Deterministic tie-breaking; identical inputs
+  produce byte-identical artifacts.
+- **Under the documented deterministic rubric** (see `tools/eval/grade.mjs`),
+  89.7% of the 195-recommendation stratified sample grades Excellent or Good
+  ("qualitatively usable") and 4.1% grades Weak or Incorrect.
+
+It does **not** establish human-validated relevance. There is no labelled
+ground-truth dataset in this repository asserting "printer A is a good
+alternative to printer B", so figures like the 89.7% above are rubric outcomes
+on a deterministic sample - they must not be read as "89.7% accurate" or as
+compatibility accuracy. Building a small hand-curated pair set is the single
+highest-value follow-up if recommendation quality needs stronger defence.
+
+---
+
+## Known Limitations
+
+- **Identical feature vectors.** Only 1,096 distinct engineered feature vectors
+  exist across 6,657 printers; 90.7% of printers share their vector with at
+  least one other, and in 85.3% of top-3 lists the candidates are byte-identical
+  clones of each other. Given the recorded Foomatic data these printers
+  *genuinely cannot be distinguished*; deterministic id ordering is used so tied
+  results are reproducible, not to pretend to a ranking the data cannot support.
+- **Zero-recommendation printers.** 71 printers (1.07%) currently receive no
+  recommendations: every candidate falls below `MIN_SIMILARITY_SCORE`, almost
+  always because the printer record carries too little data to accumulate
+  evidence. The UI shows an explicit empty state for these.
+- **Catalogue coverage.** Roughly 27% of printers ever appear in someone's
+  top-3; the rest are never surfaced. Driver-family clustering concentrates
+  exposure on a minority of the catalogue.
+- **Same-manufacturer and rebadge concentration.** 47.5% of displayed
+  recommendations are same-manufacturer, and 58.7% of cross-manufacturer ones
+  pair printers within the Ricoh badge family (Ricoh/Lanier/NRG/Gestetner/
+  Savin/Infotec) - technically correct for compatibility, since these are
+  frequently the same hardware, but of limited value as *alternatives*. Roughly
+  22% of recommendations cross to a genuinely different vendor.
+- **No human-labelled ground truth** - the most important limitation; see the
+  section above.
+- **O(n^2) computation.** Every printer is compared against every other
+  (~44M pairs at 6,657 printers), measured at roughly 60-70s single-threaded
+  on a typical development machine. Acceptable at the current database size and
+  re-run only at build/regeneration time, but not unbounded.
+
+---
+
+## Reproducing the Evaluation
+
+Prerequisites: `yarn install`, then generated artifacts in
+`public/foomatic-db/` (`yarn generate`, or `yarn foomatic:pipeline` for the
+foomatic stages alone - see [foomatic-retraining.md](./foomatic-retraining.md)).
+
+```
+yarn foomatic:eval
+```
+
+runs three deterministic checks against the artifacts on disk:
+
+1. **`tools/eval/metrics.mjs`** - full-dataset ranking metrics: score
+   distribution and saturation, tie rates, evidence/score correlation,
+   explanation-truthfulness validation of every displayed claim,
+   manufacturer/rebadge/coverage diversity, and capability contradictions.
+2. **`tools/eval/check-docs.mjs`** - verifies every tunable documented in this
+   file against the values in the source, and greps the docs for retired
+   terminology. Fails non-zero on drift.
+3. **`tools/eval/grade.mjs`** - applies the fixed rubric documented in its
+   header to a deterministic stratified sample (~68 printers across technology,
+   colour, resolution, rarity, and manufacturer strata built by
+   `tools/eval/sample.mjs`; sorted pools, evenly-spaced picks, no randomness -
+   the same artifacts always yield the same sample, so results are not
+   cherry-picked). Pass `--rows` for the per-pair detail.
+
+`node tools/eval/pairs.mjs` prints a maintainer-facing deep-dive of the sampled
+pairs - full source/target capabilities beside the user-visible explanation,
+bucketed into good / low-value / weak / problematic.
+
+The harness proves internal consistency, truthfulness, and discriminative
+behaviour. It does not prove human-validated relevance (no labelled pair set
+exists), and the rubric in `grade.mjs` is itself an engineered heuristic - a
+lens for review, not ground truth.
diff --git a/docs/foomatic-retraining.md b/docs/foomatic-retraining.md
new file mode 100644
index 00000000..5feaa387
--- /dev/null
+++ b/docs/foomatic-retraining.md
@@ -0,0 +1,111 @@
+# Foomatic Pipeline — Regeneration Guide
+
+This is the operational reference for re-running the printer recommendation pipeline described in [foomatic-pipeline-architecture.md](./foomatic-pipeline-architecture.md). There is no "training" in the machine-learning-model sense — the pipeline deterministically regenerates static artifacts from upstream `foomatic-db` XML and engineered feature weights. "Retraining" here means re-running the pipeline end-to-end after either the upstream database or the feature/weight logic has changed.
+
+---
+
+## Prerequisites
+
+The full pipeline (including PPD compilation) requires the same system packages installed in CI (`.github/workflows/build.yml` / `deploy.yml`):
+
+```
+foomatic-db-engine foomatic-db-compressed-ppds cups-filters ghostscript bsdmainutils libxml2-utils xsltproc
+```
+
+On Windows (or any environment without `foomatic-compiledb`), PPD compilation is automatically skipped — `data-generate.ts` skips it whenever `process.platform === "win32"`, and `generate-ppds.sh` itself exits early if the `foomatic-compiledb` binary isn't found. The rest of the pipeline runs identically either way; printers simply get `hasPpd: false`.
+
+Node dependencies are managed with `yarn` (`yarn.lock` is the lockfile of record).
+
+---
+
+## Running the full pipeline
+
+```bash
+yarn foomatic:pipeline
+```
+
+This runs `scripts/foomatic/data-generate.ts`, which executes every stage in order and stops immediately if any stage fails:
+
+1. `generate-from-xml.ts` — clones/pulls `OpenPrinting/foomatic-db` into `cache/foomatic-db`, converts XML to JSON
+2. `generate-ppds.sh` — compiles PPDs (skipped on Windows or with `--skip-ppd`)
+3. `combine-data.ts` — produces `printers.json`
+4. `split-printers.ts` — produces `printersMap.json` and `printers/<id>.json`
+5. `vectorize.ts` — produces `feature-matrix.json` (skipped with `--skip-similarity`)
+6. `compute-similarity.ts` — produces `recommendations.json` and `recommendations/<id>.json` (skipped with `--skip-similarity`)
+
+This also runs automatically before every `next build`: the `build` script is `yarn generate && next build && ...`, and `yarn generate` invokes this pipeline first.
+
+### Flags / environment variables
+
+| Flag | Env var equivalent | Effect |
+|---|---|---|
+| `--skip-ppd` | n/a (Windows always skips) | Skip PPD compilation (stage 2) |
+| `--skip-similarity` | `FOOMATIC_SKIP_SIMILARITY=1` | Skip stages 6–7 (vectorize + compute-similarity) |
+| `--force` (forwarded to `generate-ppds.sh` only) | `FORCE_PPD_GEN=true` | Force PPD recompilation even if the cached `foomatic-db` git revision hasn't changed |
+
+Example — fast local iteration on UI changes without recomputing recommendations:
+
+```bash
+yarn foomatic:pipeline --skip-similarity
+```
+
+---
+
+## Running individual stages
+
+Each stage can be run independently via its own `package.json` script — useful when iterating on one stage without re-running the whole pipeline:
+
+```bash
+yarn foomatic:generate:xml      # stage 1: XML → JSON
+yarn foomatic:generate:ppds     # stage 2: PPD compilation (Linux/macOS only)
+yarn foomatic:data:combine      # stage 3: normalization → printers.json
+yarn foomatic:data:split        # stages 4-5: printersMap.json + printers/<id>.json,
+                                #             driversMap.json + drivers/<id>.json
+yarn foomatic:data:vectorize    # stage 6: feature-matrix.json
+yarn foomatic:data:similarity   # stage 7: recommendations.json + recommendations/<id>.json
+```
+
+Stages 3–7 each read their input from a fixed path under `public/foomatic-db/` (see [foomatic-data-formats.md](./foomatic-data-formats.md)) rather than from in-memory state, so they can be re-run independently as long as the upstream artifact they depend on already exists. Running `yarn foomatic:data:vectorize` without first running `yarn foomatic:data:combine` will fail fast with a message telling you which earlier command to run.
+
+---
+
+## When to re-run which stage
+
+| Change | Stages to re-run |
+|---|---|
+| Upstream `foomatic-db` content changed (new printers/drivers) | All stages (`yarn foomatic:pipeline`) |
+| Editing normalization logic in `lib/foomatic/printer-attributes.ts` (e.g. a new commandset token mapping) | `combine-data` onward (3–6) |
+| Editing feature weights or adding a new feature in `vectorize.ts` | `vectorize` onward (5–6) — `combine-data`/`split-printers` output is unaffected |
+| Editing similarity scoring/explanation logic in `compute-similarity.ts` | `compute-similarity` only (6) |
+| UI-only changes (components, pages) | No pipeline re-run needed — just `next dev` / `next build` against existing `public/foomatic-db/` artifacts |
+
+---
+
+## CI automation
+
+You do not need to run the pipeline manually for production — it runs automatically:
+
+- **Every PR / push to `master`:** `build.yml` runs the full pipeline with `FOOMATIC_SKIP_SIMILARITY=1`, so PR checks validate ingestion/normalization/UI without paying the cost of the O(n²) similarity computation.
+- **Every push to `master`, plus a weekly cron (`0 2 * * 1`, Mondays 02:00 UTC):** `deploy.yml` runs the full pipeline including similarity computation, then deploys the static export to GitHub Pages. This is what keeps recommendations fresh as `foomatic-db` evolves upstream, without anyone needing to remember to trigger it.
+
+To manually trigger a full regeneration in CI without waiting for the weekly cron, use the `workflow_dispatch` trigger on `deploy.yml` from the Actions tab.
+
+---
+
+## Verifying a regeneration was a no-op (regression check)
+
+If you've changed code but expect output to be unchanged (e.g. a refactor with no behavior change), diff the artifacts before and after:
+
+```bash
+cp public/foomatic-db/printers.json /tmp/printers.before.json
+yarn foomatic:data:combine
+diff -q /tmp/printers.before.json public/foomatic-db/printers.json
+```
+
+Repeat the same pattern for `feature-matrix.json` (after `yarn foomatic:data:vectorize`) and `recommendations.json` (after `yarn foomatic:data:similarity`). This is how the `lib/foomatic/*` extraction refactor (see the test suite under `lib/foomatic/__tests__/`) was verified to be behavior-preserving before being merged.
+
+---
+
+## Adding a new similarity feature
+
+See [foomatic-ui-extending.md](./foomatic-ui-extending.md#adding-a-new-recommendation-signal) for the step-by-step process — it touches `combine-data.ts` (derive the attribute), `vectorize.ts` (encode it with a weight), and `compute-similarity.ts` (optionally add it to `computeSharedFeatures()` for the "why this printer?" explanation).
diff --git a/docs/foomatic-ui-extending.md b/docs/foomatic-ui-extending.md
new file mode 100644
index 00000000..656053fb
--- /dev/null
+++ b/docs/foomatic-ui-extending.md
@@ -0,0 +1,124 @@
+# Foomatic Web Interface — Extending Guide
+
+This document is for contributors working on the printer discovery and recommendation interface at `/foomatic`. It assumes you've read [foomatic-pipeline-architecture.md](./foomatic-pipeline-architecture.md) and [foomatic-data-formats.md](./foomatic-data-formats.md) for how the data this UI consumes is produced.
+
+This is the GSoC "Track B" deliverable: *a client-side-only interface, with no backend, consuming the static ML artifacts generated by Track A.*
+
+---
+
+## Component Structure
+
+```
+app/foomatic/
+  printers/page.tsx                 Directory/listing page (client component)
+  printer/[make]/[id]/page.tsx      Printer detail route — server component,
+                                    generateStaticParams() pre-renders one
+                                    page per printer from printersMap.json
+  drivers/page.tsx                  Driver directory listing
+  driver/[id]/page.tsx              Driver detail route
+  ppd-o-matic/page.tsx              PPD preview route
+
+components/foomatic/
+  Printers.tsx                      Grid wrapper, renders PrinterCard per item
+  PrinterCard.tsx                   Single printer summary card (directory page)
+  PrinterSearch.tsx                 Search input + filter controls
+  PrinterPageClient.tsx             Printer detail page body (client component)
+  RecommendedPrintersSection.tsx    "Similar printers" section on the detail page
+  DriverListClient.tsx              Driver directory body
+  DriverPageClient.tsx              Driver detail page body
+  PpdViewerClient.tsx               PPD text viewer (ppd-o-matic route)
+  shared.tsx                        Shared primitives: FoomaticCard, FoomaticBadge,
+                                    FoomaticStatusBadge, FoomaticSelect, etc.
+
+lib/foomatic/
+  types.ts                          Printer / Driver / PrinterSummary types
+  utils.ts                          calculateAccurateStatus()
+  sanitize.ts                       sanitizeFoomaticHtml() — DOMPurify wrapper
+  base-path.ts                      withBasePath() — GitHub Pages basePath helper
+  driver-family.ts                  normalizeDriverFamily() and friends (also used
+                                     by the pipeline scripts — see below)
+  printer-attributes.ts             Pipeline-side attribute derivation (also used
+                                     by the pipeline scripts)
+  similarity-math.ts                cosineSimilarity() and friends (pipeline-side)
+  hooks/use-debounce.ts             useDebounce() — used by PrinterSearch
+```
+
+Everything under `app/foomatic` and `components/foomatic` is a Next.js **client component** (`"use client"`) except `app/foomatic/printer/[make]/[id]/page.tsx`, which is a server component whose only job is to call `generateStaticParams()` (reading `printersMap.json` from disk at build time) and hand off to `PrinterPageClient`. This split exists because static export needs `generateStaticParams()` to run at build time in Node, while the actual data-fetching and interactivity happens in the browser against the static JSON artifacts.
+
+`lib/foomatic/driver-family.ts`, `printer-attributes.ts`, and `similarity-math.ts` are shared between the **build-time pipeline** (`scripts/foomatic/*.ts`) and its **test suite** (`lib/foomatic/__tests__/`) — they are not UI code, but they live in `lib/foomatic` because that's the one place both the pipeline scripts and (potentially) the frontend can import from without a circular path back into `scripts/`.
+
+---
+
+## Printer Page Architecture
+
+`app/foomatic/printer/[make]/[id]/page.tsx` → `PrinterPageClient.tsx`:
+
+1. On mount, fetches `public/foomatic-db/printers/${printerId}.json` (the per-printer split file — see data formats doc).
+2. Renders a loading skeleton while the fetch is in flight, and a "Printer not found" card if the fetch fails or 404s — never a hard error.
+3. Recomputes `status` via `calculateAccurateStatus()` rather than trusting the printer's raw `status` field directly, because `status` in the data can be stale relative to `functionality`/`driverCount` depending on how the record was synthesized upstream (see `lib/foomatic/utils.ts`).
+4. Renders a grouped **Capabilities** block (color, duplex, max resolution, connectivity, page description languages) and the driver list, sorted so `recommended_driver` appears first. PostScript/PCL levels are surfaced through the page-description-language labels rather than as separate rows, since the `commandsets` labels already carry the level (`PCL 5e`, `PostScript 3`).
+5. Renders `driver.comments` and `printer.notes` through `sanitizeFoomaticHtml()` before `dangerouslySetInnerHTML` — **never bypass this**; that content originates from upstream contributor-editable XML (see [foomatic-data-formats.md](./foomatic-data-formats.md#publicfoomatic-dbprintersjson)).
+6. Renders `<RecommendedPrintersSection printerId={printer.id} />` at the bottom.
+
+---
+
+## Recommendation UI
+
+`RecommendedPrintersSection.tsx`:
+
+1. Fetches exactly one file: `public/foomatic-db/recommendations/${printerId}.json`. Each entry already carries the `manufacturer`/`model`/`status`/`type`/`driverCount` fields the card renders, denormalized by `compute-similarity.ts`, so no second lookup against `printersMap.json` is needed.
+2. If you add a field to the card, add it to the denormalization block in `compute-similarity.ts` (and to the schema in [foomatic-data-formats.md](./foomatic-data-formats.md#publicfoomatic-dbrecommendationsidjson)) rather than reintroducing a `printersMap.json` fetch here — that file is ~1.5 MB and would dominate the page's transfer cost.
+3. Renders only the **top 3** recommendations (`recs.slice(0, 3)`) — the underlying data has up to 10, the UI deliberately shows fewer to keep the section compact.
+4. `ConfidenceBadge` maps the score to one of four evidence-aligned tiers via `confidenceTier()` in `lib/foomatic/scoring.ts`: **High confidence** (≥ 0.85, emerald), **Good match** (≥ 0.70, sky), **Moderate match** (≥ 0.50, amber), **Limited evidence** (below, muted), with a secondary `N% similarity` line. The wording is deliberate: the score is an engineered similarity value, not a probability that the printer will work, so nothing is ever labelled "exact".
+5. `sharedFeatures` (the explanation strings produced by `computeSharedFeatures()` in the pipeline) are rendered as a labeled chip list under "Why this printer?".
+6. Uses a `cancelled` flag in the `useEffect` cleanup to avoid calling `setState` after unmount (relevant if a user navigates away mid-fetch).
+7. `SimilarPrintersTeaser` (exported from the same file) renders a compact card in the printer-page header beside the Recommended driver box: the top similar printer, its `N% similarity` and confidence tier, and an anchor link to `#similar-printers` on the full section. It shares one shard request with the full section through a module-level per-printer cache, and renders nothing while loading or when the printer has no recommendations.
+8. Inside recommendation cards the candidate's own Foomatic grade badge is prefixed with "Linux support:" specifically to distinguish the candidate's Linux support grade from the similarity result; the bare badge used elsewhere on the site is unchanged.
+
+---
+
+## Filter System
+
+`app/foomatic/printers/page.tsx` owns all filter/search/pagination state for the directory listing:
+
+- State is persisted to `localStorage` under the `STORAGE_KEYS` constants (search query, manufacturer, driver type, mechanism type, support level, color capability, current page, items-per-page) — so filters survive a reload or back-navigation.
+- `PrinterSearch.tsx` is a presentational component: it owns the debounced text input (`useDebounce`, 300ms) and renders the filter `<select>` controls, but the actual filtering logic and state lives in the parent page.
+- Filtering itself is a `useMemo`-derived `filteredPrinters` array in `page.tsx`, applying each active filter in sequence (manufacturer → search text → driver availability → mechanism type → support level → color).
+- Changing any filter resets pagination to page 1; resizing the result set (e.g. via "items per page") clamps the current page if it now exceeds the new total.
+
+### Adding a new filter
+
+1. Add a new `STORAGE_KEYS` entry and a corresponding `useState` in `app/foomatic/printers/page.tsx`, following the existing pattern (e.g. `selectedDriverType`).
+2. Add the filter's predicate to the `filteredPrinters` `useMemo` chain.
+3. Add a `<FilterField>` entry in `PrinterSearch.tsx` (label, options, current value, change handler) — it already wires up a paired `<label>`/`aria-label` for you, so a new filter is accessible by default.
+4. If the filter needs a field that isn't in `PrinterSummary` (`lib/foomatic/types.ts`) yet, add it there **and** to `split-printers.ts`'s `printersMap` projection in the pipeline (see [foomatic-data-formats.md](./foomatic-data-formats.md#publicfoomatic-dbprintersmapjson)) — the directory page only ever sees the lightweight summary, not the full printer record.
+
+---
+
+## Adding a New Recommendation Signal
+
+To add a new feature dimension to the similarity engine (the kind of change made repeatedly in this branch's history — color, commandsets, PS/PCL level, resolution), touch these three files in order:
+
+1. **`scripts/foomatic/combine-data.ts`** (or `lib/foomatic/printer-attributes.ts` if the derivation is a pure function) — derive the new attribute from the raw XML and add it to the `Printer` shape written to `printers.json`. Add the corresponding field to `lib/foomatic/types.ts`'s `Printer` interface.
+2. **`scripts/foomatic/vectorize.ts`** — pick a weight constant (look at the existing table in [foomatic-recommendation-quality.md](./foomatic-recommendation-quality.md) to calibrate relative importance), add the feature to both `buildFeatureNames()` and `encodePrinter()` in the same position so the names array and the vector stay aligned.
+3. **`scripts/foomatic/compute-similarity.ts`** — optionally extend `computeSharedFeatures()` to add a human-readable explanation string when the new attribute matches between two printers, so it surfaces in the "Why this printer?" UI.
+
+Then regenerate and verify per [foomatic-retraining.md](./foomatic-retraining.md#adding-a-new-similarity-feature):
+
+```bash
+yarn foomatic:data:vectorize
+yarn foomatic:data:similarity
+```
+
+Add unit tests for any new pure derivation function in `lib/foomatic/__tests__/`, following the existing pattern in `printer-attributes.test.ts`.
+
+If the new signal should also be visible as a standalone capability badge (not just a recommendation explanation), add it to the **Capabilities** `<dl>` block in `PrinterPageClient.tsx` (and extend the `hasCapabilities` guard so the block still hides when nothing is known), following the existing color/duplex/max-resolution examples.
+
+---
+
+## Adding a New UI Feature (general)
+
+- Keep new components under `components/foomatic/`, reusing the shared primitives in `shared.tsx` (`FoomaticCard`, `FoomaticBadge`, `FoomaticStatusBadge`, `FoomaticSelect`, `FoomaticHeroPill`, `FoomaticPageSection`) rather than introducing new ad-hoc styling — this keeps the directory and detail pages visually consistent.
+- All data fetching is `fetch()` against static JSON under `public/foomatic-db/`, wrapped with `withBasePath()` from `lib/foomatic/base-path.ts` so paths resolve correctly under the GitHub Pages base path in production. Never hardcode a `/foomatic-db/...` path without `withBasePath()`.
+- Preserve the existing accessibility patterns: `aria-live`/`aria-busy` on async-loading containers, `aria-label` on icon-only or ambiguous links/buttons, a real `<label htmlFor>` paired with any `aria-label` on form controls (see `PrinterSearch.tsx`'s `FilterField` for the canonical pattern).
+- If you render any field sourced from `printers.json` that could contain upstream-authored HTML (anything that traces back to a Foomatic XML `<comments>`-like field), sanitize it with `sanitizeFoomaticHtml()` before `dangerouslySetInnerHTML` — do not introduce a new unsanitized `dangerouslySetInnerHTML` call.
diff --git a/lib/assistant/__tests__/assistant-artifact.test.ts b/lib/assistant/__tests__/assistant-artifact.test.ts
new file mode 100644
index 00000000..6688b3fc
--- /dev/null
+++ b/lib/assistant/__tests__/assistant-artifact.test.ts
@@ -0,0 +1,223 @@
+import { beforeAll, describe, expect, it } from "vitest"
+import { normalizeDriverId, printerHref } from "@/lib/foomatic/routes"
+import type { PrinterSummary } from "@/lib/foomatic/types"
+import { artifactsPresent, nodeData } from "../../../tools/assistant-eval/node-data"
+import { parsePageContext } from "../context"
+import { buildDriverIndex, buildPrinterIndex, type PrinterIndex } from "../entities"
+import { runAssistant } from "../engine"
+import { MANUFACTURER_ALIASES } from "../entities"
+import { fuseText } from "../normalize"
+import { parseQuery } from "../parse"
+import type { AssistantData, AssistantPageContext, ResponsePlan } from "../types"
+
+// End-to-end validation against the REAL generated artifacts (the exact data
+// the site ships). Skipped when the artifacts are absent - CI runs `yarn test`
+// before `yarn generate`; run `yarn generate` (or the split/similarity stages)
+// locally first. The always-run fixture suites pin the engine's behavior.
+
+const present = artifactsPresent()
+
+describe.skipIf(!present)("assistant against real foomatic artifacts", () => {
+  let data: AssistantData
+  let catalog: PrinterSummary[]
+  let byId: Map<string, PrinterSummary>
+  let printerIndex: PrinterIndex
+  let indexes: Parameters<typeof parseQuery>[2]
+  let lj4Context: AssistantPageContext
+
+  const cardIds = (plan: ResponsePlan): string[] =>
+    plan.blocks.flatMap(block => (block.kind === "printer-cards" ? block.printers.map(card => card.id) : []))
+
+  const planText = (plan: ResponsePlan): string =>
+    plan.blocks
+      .map(block => {
+        if (block.kind === "text") return block.text
+        if (block.kind === "list") return `${block.title} ${block.items.join(" ")}`
+        return ""
+      })
+      .join(" ")
+
+  beforeAll(async () => {
+    data = nodeData()
+    catalog = await data.getCatalog()
+    byId = new Map(catalog.map(printer => [printer.id, printer]))
+    printerIndex = buildPrinterIndex(catalog)
+    indexes = { printers: printerIndex, drivers: buildDriverIndex(await data.getDriversMap()) }
+    lj4Context = parsePageContext(printerHref("HP-LaserJet_4", "HP"))
+  })
+
+  it("resolves real printer names, aliases, and punctuation variants", () => {
+    const home = parsePageContext("/")
+    for (const [input, id] of [
+      ["HP 2500C", "HP-2500C"],
+      ["hp 2500cm", "HP-2500CM"],
+      ["Hewlett Packard 2500C", "HP-2500C"],
+      ["HP DeskJet 560C", "HP-DeskJet_560C"],
+      ["hp laserjet 4", "HP-LaserJet_4"],
+    ] as const) {
+      const query = parseQuery(input, home, indexes)
+      expect(query.intent, input).toBe("PRINTER_LOOKUP")
+      if (query.intent === "PRINTER_LOOKUP") {
+        expect(query.printer, input).toEqual({ kind: "resolved", id })
+      }
+    }
+  })
+
+  it("resolves 'HP LaserJet' to the literal HP-LaserJet record (it really exists upstream)", () => {
+    // The upstream database contains plain family-name printers (HP-LaserJet,
+    // HP-DeskJet, Epson-Stylus), so an exact name match is the honest answer
+    // here - ambiguity handling applies only when no exact record exists.
+    const query = parseQuery("HP LaserJet", parsePageContext("/"), indexes)
+    expect(query.intent).toBe("PRINTER_LOOKUP")
+    if (query.intent === "PRINTER_LOOKUP") {
+      expect(query.printer).toEqual({ kind: "resolved", id: "HP-LaserJet" })
+    }
+  })
+
+  it("treats a partial model prefix as ambiguous across the real family", () => {
+    // No printer is literally named "HP DeskJet 5", but 21 DeskJet 5xx models
+    // exist: this must surface as an ambiguity with real candidates.
+    const query = parseQuery("hp deskjet 5", parsePageContext("/"), indexes)
+    expect(query.intent).toBe("PRINTER_LOOKUP")
+    if (query.intent === "PRINTER_LOOKUP") {
+      expect(query.printer.kind).toBe("ambiguous")
+      if (query.printer.kind === "ambiguous") {
+        expect(query.printer.total).toBeGreaterThan(5)
+        for (const candidate of query.printer.candidates) {
+          expect(byId.has(candidate.id)).toBe(true)
+        }
+      }
+    }
+  })
+
+  it("does not resolve Brother HL-2270DW (absent from the dataset) and only suggests real models", () => {
+    const query = parseQuery("Brother HL-2270DW", parsePageContext("/"), indexes)
+    expect(query.intent).toBe("PRINTER_LOOKUP")
+    if (query.intent === "PRINTER_LOOKUP") {
+      expect(query.printer.kind).toBe("unresolved")
+      if (query.printer.kind === "unresolved") {
+        for (const suggestion of query.printer.suggestions) {
+          expect(byId.has(suggestion.id)).toBe(true)
+        }
+      }
+    }
+  })
+
+  it("keeps every manufacturer alias pointing at a real catalogue make", () => {
+    const makes = new Set(catalog.map(printer => fuseText(printer.manufacturer)))
+    for (const make of Object.values(MANUFACTURER_ALIASES)) {
+      expect(makes.has(fuseText(make)), make).toBe(true)
+    }
+  })
+
+  it("capability search returns only printers whose recorded fields match", async () => {
+    const turn = await runAssistant("find a colour laser printer with good linux support", parsePageContext("/"), data)
+    expect(turn.execution.kind).toBe("search-results")
+    if (turn.execution.kind === "search-results") {
+      expect(turn.execution.total).toBeGreaterThan(0)
+      for (const match of turn.execution.matches) {
+        expect(match.color).toBe(true)
+        expect(match.type).toBe("laser")
+        expect(["Perfect", "Mostly"]).toContain(match.status)
+      }
+    }
+  })
+
+  it("similar-printers answers come from the real recommendation shard, order and scores intact", async () => {
+    const shard = await data.getRecommendations("HP-LaserJet_4")
+    expect(shard.length).toBeGreaterThan(0)
+    const turn = await runAssistant("what printers are similar to this?", lj4Context, data)
+    expect(turn.execution.kind).toBe("similar")
+    if (turn.execution.kind === "similar") {
+      expect(turn.execution.entries).toEqual(shard)
+    }
+    const ids = cardIds(turn.plan)
+    expect(ids.length).toBeGreaterThan(0)
+    for (const [position, id] of ids.entries()) {
+      expect(id).toBe(shard[position].id)
+    }
+  })
+
+  it("explanations quote the real shard's sharedFeatures verbatim", async () => {
+    const shard = await data.getRecommendations("HP-LaserJet_4")
+    const top = shard[0]
+    const name = `${top.manufacturer ?? ""} ${top.model ?? top.id}`.trim()
+    const turn = await runAssistant(`why was ${name} recommended`, lj4Context, data)
+    expect(turn.execution.kind).toBe("explanation")
+    const text = planText(turn.plan)
+    for (const feature of top.sharedFeatures) {
+      expect(text).toContain(feature)
+    }
+    expect(text).toContain(`${Math.round(top.score * 100)}% similarity`)
+    expect(text).toContain(top.status)
+  })
+
+  it("comparison rows reflect the real printer records", async () => {
+    const turn = await runAssistant("compare HP 2500C and HP DeskJet 560C", parsePageContext("/"), data)
+    expect(turn.execution.kind).toBe("comparison")
+    if (turn.execution.kind !== "comparison") return
+    const [a, b] = await Promise.all([data.getPrinter("HP-2500C"), data.getPrinter("HP-DeskJet_560C")])
+    const comparison = turn.plan.blocks.find(block => block.kind === "comparison")
+    expect(comparison).toBeDefined()
+    if (comparison && comparison.kind === "comparison" && a && b) {
+      const resolution = comparison.rows.find(row => row.label === "Max resolution")
+      expect(resolution?.a).toBe(typeof a.maxDpi === "number" ? `${a.maxDpi} dpi` : "Not recorded")
+      expect(resolution?.b).toBe(typeof b.maxDpi === "number" ? `${b.maxDpi} dpi` : "Not recorded")
+    }
+  })
+
+  it("'same driver' uses the real recommended driver and its real reverse index", async () => {
+    const printer = await data.getPrinter("HP-LaserJet_4")
+    const recommended = normalizeDriverId(printer?.recommended_driver ?? "")
+    expect(recommended.length).toBeGreaterThan(0)
+    const turn = await runAssistant("which printers use the same driver?", lj4Context, data)
+    expect(turn.execution.kind).toBe("driver-search")
+    if (turn.execution.kind === "driver-search") {
+      expect(turn.execution.anchorDriverName).toBe(recommended)
+      const record = await data.getDriver(recommended)
+      const listed = new Set(record?.printers.map(p => p.id))
+      for (const id of cardIds(turn.plan)) {
+        expect(listed.has(id)).toBe(true)
+      }
+    }
+  })
+
+  it("duplex is answered as missing data across the whole real catalogue", async () => {
+    const turn = await runAssistant("duplex printer", parsePageContext("/"), data)
+    expect(turn.execution.kind).toBe("insufficient")
+    const text = planText(turn.plan)
+    expect(text).toContain(String(catalog.length))
+    expect(cardIds(turn.plan)).toEqual([])
+  })
+
+  it("'purple laser printer' surfaces the unapplied constraint and filters the rest", async () => {
+    const turn = await runAssistant("purple laser printer", parsePageContext("/"), data)
+    const text = planText(turn.plan)
+    expect(text).toContain('"purple"')
+    for (const id of cardIds(turn.plan)) {
+      expect(byId.get(id)?.type).toBe("laser")
+    }
+  })
+
+  it("criteria-free best and dimension-free better both clarify on real data", async () => {
+    const best = await runAssistant("what is the best printer?", parsePageContext("/"), data)
+    expect(best.execution.kind).toBe("clarify")
+    const better = await runAssistant("what are better alternatives?", lj4Context, data)
+    expect(better.execution.kind).toBe("clarify")
+  })
+
+  it("every similarity percentage rendered anywhere matches a real shard score", async () => {
+    const shard = await data.getRecommendations("HP-LaserJet_4")
+    const scores = new Set(shard.map(entry => Math.round(entry.score * 100)))
+    const turn = await runAssistant("what printers are similar to this?", lj4Context, data)
+    for (const block of turn.plan.blocks) {
+      if (block.kind === "printer-cards") {
+        for (const card of block.printers) {
+          if (card.score !== undefined) {
+            expect(scores.has(Math.round(card.score * 100))).toBe(true)
+          }
+        }
+      }
+    }
+  })
+})
diff --git a/lib/assistant/__tests__/context.test.ts b/lib/assistant/__tests__/context.test.ts
new file mode 100644
index 00000000..5f468186
--- /dev/null
+++ b/lib/assistant/__tests__/context.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest"
+import { driverHref, printerHref } from "@/lib/foomatic/routes"
+import { parsePageContext } from "../context"
+
+describe("parsePageContext", () => {
+  it("round-trips the canonical printer URL builder", () => {
+    const href = printerHref("HP-LaserJet_4", "HP")
+    const context = parsePageContext(href)
+    expect(context).toEqual({ pageType: "printer", route: href, printerId: "HP-LaserJet_4" })
+  })
+
+  it("round-trips a multi-word manufacturer", () => {
+    const href = printerHref("Kyocera_Mita-FS-600", "Kyocera Mita")
+    const context = parsePageContext(`${href}/`)
+    expect(context.pageType).toBe("printer")
+    if (context.pageType === "printer") {
+      expect(context.printerId).toBe("Kyocera_Mita-FS-600")
+    }
+  })
+
+  it("round-trips the canonical driver URL builder", () => {
+    const href = driverHref("driver/hplip")
+    expect(parsePageContext(href)).toEqual({ pageType: "driver", route: href, driverId: "hplip" })
+  })
+
+  it("decodes encoded id segments", () => {
+    const context = parsePageContext("/foomatic/printer/HP/HP-2500C%20Plus/")
+    expect(context.pageType).toBe("printer")
+    if (context.pageType === "printer") {
+      expect(context.printerId).toBe("HP-2500C Plus")
+    }
+  })
+
+  it("classifies directories, home, and other routes", () => {
+    expect(parsePageContext("/foomatic/printers/").pageType).toBe("printer-directory")
+    expect(parsePageContext("/foomatic/drivers").pageType).toBe("driver-directory")
+    expect(parsePageContext("/").pageType).toBe("home")
+    expect(parsePageContext("").pageType).toBe("home")
+    expect(parsePageContext("/documentation/abc").pageType).toBe("other")
+    expect(parsePageContext("/foomatic/printer/HP").pageType).toBe("other")
+  })
+})
diff --git a/lib/assistant/__tests__/corpus.ts b/lib/assistant/__tests__/corpus.ts
new file mode 100644
index 00000000..0caebc0e
--- /dev/null
+++ b/lib/assistant/__tests__/corpus.ts
@@ -0,0 +1,413 @@
+// Natural-language test corpus for the assistant parser. Shared between the
+// unit tests (lib/assistant/__tests__/parse.test.ts, run against the fixture
+// catalogue) and the eval harness (tools/assistant-eval/run.ts, run against
+// the real generated artifacts).
+//
+// Each case pins the expected intent; `check` adds deeper assertions and
+// returns an error string (or null). Checks marked fixtureOnly depend on the
+// fixture catalogue's exact contents and are skipped by the harness.
+
+import type { AssistantQuery } from "../types"
+
+export interface CorpusCase {
+  q: string
+  // Page context: "home" (default), "printer" (an HP LaserJet 4 page), or
+  // "driver" (the hplip driver page).
+  ctx?: "home" | "printer" | "driver"
+  intent: AssistantQuery["intent"]
+  check?: (query: AssistantQuery) => string | null
+  fixtureOnly?: boolean
+}
+
+function err(condition: boolean, message: string): string | null {
+  return condition ? null : message
+}
+
+const resolvedPrinter = (id: string) => (query: AssistantQuery): string | null => {
+  if (!("printer" in query)) return "no printer ref"
+  const ref = query.printer
+  return err(ref.kind === "resolved" && ref.id === id, `expected resolved ${id}, got ${JSON.stringify(ref)}`)
+}
+
+const contextPrinter = (query: AssistantQuery): string | null => {
+  if (!("printer" in query)) return "no printer ref"
+  return err(query.printer.kind === "context", `expected context ref, got ${query.printer.kind}`)
+}
+
+const hasFilter = (key: string, value?: unknown) => (query: AssistantQuery): string | null => {
+  if (!("filters" in query) || !query.filters) return "no filters"
+  const filters = query.filters as Record<string, unknown>
+  if (!(key in filters)) return `missing filter ${key} in ${JSON.stringify(filters)}`
+  if (value !== undefined && JSON.stringify(filters[key]) !== JSON.stringify(value)) {
+    return `filter ${key}=${JSON.stringify(filters[key])}, expected ${JSON.stringify(value)}`
+  }
+  return null
+}
+
+const all = (...checks: ((query: AssistantQuery) => string | null)[]) => (query: AssistantQuery) => {
+  for (const check of checks) {
+    const failure = check(query)
+    if (failure) return failure
+  }
+  return null
+}
+
+const better = (value: string | undefined) => (query: AssistantQuery): string | null => {
+  if (query.intent !== "SIMILAR_PRINTERS") return "not SIMILAR_PRINTERS"
+  return err(query.better === value, `better=${String(query.better)}, expected ${String(value)}`)
+}
+
+const unappliedIncludes = (word: string) => (query: AssistantQuery): string | null => {
+  if (!("unapplied" in query)) return "no unapplied list"
+  return err(query.unapplied.includes(word), `unapplied=${JSON.stringify(query.unapplied)} missing ${word}`)
+}
+
+export const CORPUS: CorpusCase[] = [
+  // --- exact printer lookup -------------------------------------------------
+  { q: "HP 2500C", intent: "PRINTER_LOOKUP", check: resolvedPrinter("HP-2500C") },
+  { q: "hp 2500c", intent: "PRINTER_LOOKUP", check: resolvedPrinter("HP-2500C") },
+  { q: "HP-2500C", intent: "PRINTER_LOOKUP", check: resolvedPrinter("HP-2500C") },
+  { q: "tell me about HP 2500C", intent: "PRINTER_LOOKUP", check: resolvedPrinter("HP-2500C") },
+  { q: "tell me about the HP LaserJet 4", intent: "PRINTER_LOOKUP", check: resolvedPrinter("HP-LaserJet_4") },
+  { q: "HP DeskJet 560C", intent: "PRINTER_LOOKUP", check: resolvedPrinter("HP-DeskJet_560C") },
+  { q: "deskjet 560c", intent: "PRINTER_LOOKUP", check: resolvedPrinter("HP-DeskJet_560C"), fixtureOnly: true },
+  { q: "info on hp laserjet 4p", intent: "PRINTER_LOOKUP", check: resolvedPrinter("HP-LaserJet_4P") },
+  { q: "hp 2500cm", intent: "PRINTER_LOOKUP", check: resolvedPrinter("HP-2500CM") },
+  { q: "what is the hp 2500c", intent: "PRINTER_LOOKUP", check: resolvedPrinter("HP-2500C") },
+
+  // --- fuzzy / punctuation / casing / alias lookup --------------------------
+  { q: "Brother HL-1050", intent: "PRINTER_LOOKUP", check: resolvedPrinter("Brother-HL-1050") },
+  { q: "brother hl 1050", intent: "PRINTER_LOOKUP", check: resolvedPrinter("Brother-HL-1050") },
+  { q: "BROTHER HL1050", intent: "PRINTER_LOOKUP", check: resolvedPrinter("Brother-HL-1050") },
+  { q: "hl-1050", intent: "PRINTER_LOOKUP", check: resolvedPrinter("Brother-HL-1050"), fixtureOnly: true },
+  { q: "Hewlett Packard 2500C", intent: "PRINTER_LOOKUP", check: resolvedPrinter("HP-2500C") },
+  { q: "hewlett-packard 2500c", intent: "PRINTER_LOOKUP", check: resolvedPrinter("HP-2500C") },
+  { q: "epson stylus color", intent: "PRINTER_LOOKUP", check: resolvedPrinter("Epson-Stylus_Color") },
+  { q: "apple laserwriter", intent: "PRINTER_LOOKUP", check: resolvedPrinter("Apple-LaserWriter"), fixtureOnly: true },
+
+  // --- ambiguous printer names ----------------------------------------------
+  {
+    q: "HP LaserJet",
+    intent: "PRINTER_LOOKUP",
+    // fixtureOnly: the real database has a printer literally named
+    // "HP LaserJet", so this resolves exactly there.
+    check: query => {
+      if (query.intent !== "PRINTER_LOOKUP") return "wrong intent"
+      return err(query.printer.kind === "ambiguous", `expected ambiguous, got ${query.printer.kind}`)
+    },
+    fixtureOnly: true,
+  },
+  {
+    q: "tell me about the laserjet",
+    intent: "PRINTER_LOOKUP",
+    // fixtureOnly: the real database contains a printer literally named
+    // "HP LaserJet", which is then a legitimate exact match.
+    check: query => {
+      if (query.intent !== "PRINTER_LOOKUP") return "wrong intent"
+      return err(query.printer.kind !== "resolved", "a family name must not silently resolve")
+    },
+    fixtureOnly: true,
+  },
+
+  // --- no-match entities ------------------------------------------------------
+  {
+    q: "Brother HL-2270DW",
+    intent: "PRINTER_LOOKUP",
+    check: query => {
+      if (query.intent !== "PRINTER_LOOKUP") return "wrong intent"
+      return err(query.printer.kind === "unresolved", `expected unresolved, got ${query.printer.kind}`)
+    },
+  },
+  {
+    q: "hp color laserjet 9999",
+    intent: "PRINTER_LOOKUP",
+    check: query => {
+      if (query.intent !== "PRINTER_LOOKUP") return "wrong intent"
+      return err(query.printer.kind !== "resolved", "an unknown model must not resolve")
+    },
+    fixtureOnly: true,
+  },
+
+  // --- capability search: colour/type ---------------------------------------
+  { q: "find a colour laser printer", intent: "CAPABILITY_SEARCH", check: all(hasFilter("color", true), hasFilter("type", "laser")) },
+  { q: "find a color laser printer", intent: "CAPABILITY_SEARCH", check: all(hasFilter("color", true), hasFilter("type", "laser")) },
+  { q: "colour laser", intent: "CAPABILITY_SEARCH", check: all(hasFilter("color", true), hasFilter("type", "laser")) },
+  { q: "laser printer in colour", intent: "CAPABILITY_SEARCH", check: all(hasFilter("color", true), hasFilter("type", "laser")) },
+  { q: "printer that prints in colour", intent: "CAPABILITY_SEARCH", check: hasFilter("color", true) },
+  { q: "colored printers", intent: "CAPABILITY_SEARCH", check: hasFilter("color", true) },
+  { q: "black and white laser printer", intent: "CAPABILITY_SEARCH", check: all(hasFilter("color", false), hasFilter("type", "laser")) },
+  { q: "monochrome laser", intent: "CAPABILITY_SEARCH", check: hasFilter("color", false) },
+  { q: "mono printers", intent: "CAPABILITY_SEARCH", check: hasFilter("color", false) },
+  { q: "show me inkjet printers", intent: "CAPABILITY_SEARCH", check: hasFilter("type", "inkjet") },
+  { q: "ink jet printer", intent: "CAPABILITY_SEARCH", check: hasFilter("type", "inkjet") },
+  { q: "dot matrix printers", intent: "CAPABILITY_SEARCH", check: hasFilter("type", "dot-matrix") },
+  { q: "impact printer", intent: "CAPABILITY_SEARCH", check: hasFilter("type", "dot-matrix") },
+
+  // --- capability search: manufacturer --------------------------------------
+  { q: "show me Canon printers", intent: "CAPABILITY_SEARCH", check: hasFilter("manufacturer", "Canon") },
+  { q: "show me HP printers", intent: "CAPABILITY_SEARCH", check: hasFilter("manufacturer", "HP") },
+  { q: "epson printers", intent: "CAPABILITY_SEARCH", check: hasFilter("manufacturer", "Epson") },
+  { q: "list brother printers", intent: "CAPABILITY_SEARCH", check: hasFilter("manufacturer", "Brother") },
+  { q: "canon inkjet printers", intent: "CAPABILITY_SEARCH", check: all(hasFilter("manufacturer", "Canon"), hasFilter("type", "inkjet")) },
+
+  // --- capability search: PDLs -----------------------------------------------
+  { q: "printers supporting PCL", intent: "CAPABILITY_SEARCH", check: hasFilter("pcl") },
+  { q: "which printers support postscript", intent: "CAPABILITY_SEARCH", check: hasFilter("postscript") },
+  { q: "postscript printers", intent: "CAPABILITY_SEARCH", check: hasFilter("postscript") },
+  { q: "postscript 3 printers", intent: "CAPABILITY_SEARCH", check: hasFilter("postscript", { minLevel: 3 }) },
+  { q: "postscript level 2 printer", intent: "CAPABILITY_SEARCH", check: hasFilter("postscript", { minLevel: 2 }) },
+  { q: "pcl 6 printers", intent: "CAPABILITY_SEARCH", check: hasFilter("pcl", { minLevel: 6 }) },
+  { q: "pclxl printer", intent: "CAPABILITY_SEARCH", check: hasFilter("pcl", { minLevel: 6 }) },
+  { q: "pcl5e laser", intent: "CAPABILITY_SEARCH", check: all(hasFilter("pcl", { minLevel: 5 }), hasFilter("type", "laser")) },
+  { q: "colour laser with PostScript", intent: "CAPABILITY_SEARCH", check: all(hasFilter("color", true), hasFilter("type", "laser"), hasFilter("postscript")) },
+
+  // --- capability search: resolution ----------------------------------------
+  { q: "600 dpi laser printers", intent: "CAPABILITY_SEARCH", check: all(hasFilter("minDpi", 600), hasFilter("type", "laser")) },
+  { q: "printers with at least 1200 dpi", intent: "CAPABILITY_SEARCH", check: hasFilter("minDpi", 1200) },
+  { q: "high resolution printer", intent: "CAPABILITY_SEARCH", check: hasFilter("minDpi", 1200) },
+  { q: "high res inkjet", intent: "CAPABILITY_SEARCH", check: all(hasFilter("minDpi", 1200), hasFilter("type", "inkjet")) },
+
+  // --- capability search: Linux support --------------------------------------
+  { q: "find printers with good linux support", intent: "CAPABILITY_SEARCH", check: hasFilter("support", "good") },
+  { q: "printer with good Linux support", intent: "CAPABILITY_SEARCH", check: hasFilter("support", "good") },
+  { q: "printers that work well on linux", intent: "CAPABILITY_SEARCH", check: hasFilter("support", "good") },
+  { q: "well supported printers", intent: "CAPABILITY_SEARCH", check: hasFilter("support", "good") },
+  { q: "printers with perfect linux support", intent: "CAPABILITY_SEARCH", check: hasFilter("support", "perfect") },
+  { q: "fully supported printers", intent: "CAPABILITY_SEARCH", check: hasFilter("support", "perfect") },
+  { q: "show me printers with excellent support", intent: "CAPABILITY_SEARCH", check: hasFilter("support", "perfect") },
+
+  // --- multi-constraint search ------------------------------------------------
+  {
+    q: "find a colour laser printer with good linux support",
+    intent: "CAPABILITY_SEARCH",
+    check: all(hasFilter("color", true), hasFilter("type", "laser"), hasFilter("support", "good")),
+  },
+  {
+    q: "colour laser printer with duplex and PCL",
+    intent: "CAPABILITY_SEARCH",
+    check: all(hasFilter("color", true), hasFilter("type", "laser"), hasFilter("duplex", true), hasFilter("pcl")),
+  },
+  {
+    q: "monochrome laser with pcl 5 and 600 dpi",
+    intent: "CAPABILITY_SEARCH",
+    check: all(hasFilter("color", false), hasFilter("pcl", { minLevel: 5 }), hasFilter("minDpi", 600)),
+  },
+  {
+    q: "canon colour inkjet with good linux support",
+    intent: "CAPABILITY_SEARCH",
+    check: all(hasFilter("manufacturer", "Canon"), hasFilter("color", true), hasFilter("support", "good")),
+  },
+  {
+    q: "i need a colour printer with postscript 3 and at least 600 dpi",
+    intent: "CAPABILITY_SEARCH",
+    check: all(hasFilter("color", true), hasFilter("postscript", { minLevel: 3 }), hasFilter("minDpi", 600)),
+  },
+
+  // --- duplex (insufficient data downstream) ---------------------------------
+  // Even with a specific printer in scope, a duplex question gets the duplex
+  // data-gap answer - never a redirect to the printer's support grade.
+  { q: "does this printer support duplex", ctx: "printer", intent: "CAPABILITY_SEARCH", check: hasFilter("duplex", true) },
+  { q: "does the hp laserjet 4 support duplex", intent: "CAPABILITY_SEARCH", check: hasFilter("duplex", true) },
+  { q: "duplex printer", intent: "CAPABILITY_SEARCH", check: hasFilter("duplex", true) },
+  { q: "find a duplex printer", intent: "CAPABILITY_SEARCH", check: hasFilter("duplex", true) },
+  { q: "printer with two sided printing", intent: "CAPABILITY_SEARCH", check: hasFilter("duplex", true) },
+  { q: "double sided printing", intent: "CAPABILITY_SEARCH", check: hasFilter("duplex", true) },
+  { q: "double-sided laser printer", intent: "CAPABILITY_SEARCH", check: all(hasFilter("duplex", true), hasFilter("type", "laser")) },
+  { q: "i want a colour laser printer with duplex", intent: "CAPABILITY_SEARCH", check: all(hasFilter("duplex", true), hasFilter("color", true)) },
+
+  // --- unsupported constraints -------------------------------------------------
+  { q: "purple laser printer", intent: "CAPABILITY_SEARCH", check: all(hasFilter("type", "laser"), unappliedIncludes("purple")) },
+  { q: "purple printer", intent: "CAPABILITY_SEARCH", check: unappliedIncludes("purple") },
+  { q: "cheap colour laser printer", intent: "CAPABILITY_SEARCH", check: all(hasFilter("color", true), unappliedIncludes("cheap")) },
+  { q: "wireless printer", intent: "CAPABILITY_SEARCH", check: unappliedIncludes("wireless") },
+  { q: "fast laser printer", intent: "CAPABILITY_SEARCH", check: all(hasFilter("type", "laser"), unappliedIncludes("fast")) },
+
+  // --- similar printers --------------------------------------------------------
+  { q: "printers similar to HP 2500C", intent: "SIMILAR_PRINTERS", check: all(resolvedPrinter("HP-2500C"), better(undefined)) },
+  { q: "what printers are similar to hp laserjet 4", intent: "SIMILAR_PRINTERS", check: resolvedPrinter("HP-LaserJet_4") },
+  { q: "similar printers to brother hl-1050", intent: "SIMILAR_PRINTERS", check: resolvedPrinter("Brother-HL-1050") },
+  { q: "alternatives to hp 2500c", intent: "SIMILAR_PRINTERS", check: resolvedPrinter("HP-2500C") },
+  { q: "what printers are similar to this?", ctx: "printer", intent: "SIMILAR_PRINTERS", check: contextPrinter },
+  { q: "what printers are similar to this one", ctx: "printer", intent: "SIMILAR_PRINTERS", check: contextPrinter },
+  { q: "similar printers", ctx: "printer", intent: "SIMILAR_PRINTERS", check: contextPrinter },
+  { q: "show me something like this", ctx: "printer", intent: "SIMILAR_PRINTERS", check: contextPrinter },
+  { q: "replacement for hp laserjet 4", intent: "SIMILAR_PRINTERS", check: resolvedPrinter("HP-LaserJet_4") },
+  { q: "similar printers", ctx: "home", intent: "SIMILAR_PRINTERS", check: contextPrinter },
+  {
+    q: "show me printers similar to this one with colour support",
+    ctx: "printer",
+    intent: "SIMILAR_PRINTERS",
+    check: all(contextPrinter, hasFilter("color", true)),
+  },
+
+  // --- best / recommend --------------------------------------------------------
+  { q: "what is the best printer?", intent: "CAPABILITY_SEARCH", check: query => err(query.intent === "CAPABILITY_SEARCH" && query.recommend && Object.keys(query.filters).length === 0, "expected criteria-free recommend") },
+  { q: "recommend a printer", intent: "CAPABILITY_SEARCH", check: query => err(query.intent === "CAPABILITY_SEARCH" && query.recommend, "expected recommend flag") },
+  { q: "which printer should i buy", intent: "CAPABILITY_SEARCH", check: query => err(query.intent === "CAPABILITY_SEARCH" && query.recommend, "expected recommend flag") },
+  { q: "find me a good printer", intent: "CAPABILITY_SEARCH", check: query => err(query.intent === "CAPABILITY_SEARCH" && query.recommend && Object.keys(query.filters).length === 0, "expected criteria clarification path") },
+  { q: "recommend a colour laser with good linux support", intent: "CAPABILITY_SEARCH", check: all(hasFilter("color", true), hasFilter("type", "laser"), hasFilter("support", "good")) },
+  { q: "what printer would you recommend if i need colour and duplex", intent: "CAPABILITY_SEARCH", check: all(hasFilter("color", true), hasFilter("duplex", true)) },
+  { q: "best colour laser printer", intent: "CAPABILITY_SEARCH", check: all(hasFilter("color", true), hasFilter("type", "laser")) },
+
+  // --- better alternatives -------------------------------------------------------
+  { q: "what are better alternatives?", ctx: "printer", intent: "SIMILAR_PRINTERS", check: all(contextPrinter, better("unspecified")) },
+  { q: "better alternatives to hp laserjet 4", intent: "SIMILAR_PRINTERS", check: all(resolvedPrinter("HP-LaserJet_4"), better("unspecified")) },
+  { q: "what are the best alternatives to this printer", ctx: "printer", intent: "SIMILAR_PRINTERS", check: all(contextPrinter, better("unspecified")) },
+  { q: "alternatives to hp laserjet 4 with better linux support", intent: "SIMILAR_PRINTERS", check: all(resolvedPrinter("HP-LaserJet_4"), better("support")) },
+  { q: "find a printer with better linux support", ctx: "printer", intent: "SIMILAR_PRINTERS", check: all(contextPrinter, better("support")) },
+  { q: "alternatives to hp laserjet 4 with higher resolution", intent: "SIMILAR_PRINTERS", check: all(resolvedPrinter("HP-LaserJet_4"), better("resolution")) },
+  { q: "alternatives to hp laserjet 4 with more driver options", intent: "SIMILAR_PRINTERS", check: all(resolvedPrinter("HP-LaserJet_4"), better("drivers")) },
+  { q: "better alternatives with more drivers", ctx: "printer", intent: "SIMILAR_PRINTERS", check: all(contextPrinter, better("drivers")) },
+
+  // --- explanation -----------------------------------------------------------------
+  { q: "why was this recommended?", ctx: "printer", intent: "EXPLANATION", check: query => err(query.intent === "EXPLANATION" && query.candidate === null, "expected null candidate") },
+  { q: "why was hp laserjet 4p recommended", ctx: "printer", intent: "EXPLANATION", check: query => {
+      if (query.intent !== "EXPLANATION") return "wrong intent"
+      return err(query.candidate?.kind === "resolved" && query.candidate.id === "HP-LaserJet_4P", "expected resolved candidate")
+    } },
+  { q: "why is hp laserjet 5 recommended here", ctx: "printer", intent: "EXPLANATION" },
+  { q: "why do you suggest the okidata ol400", ctx: "printer", intent: "EXPLANATION" },
+  { q: "why was this printer suggested", ctx: "printer", intent: "EXPLANATION" },
+
+  // --- support queries ----------------------------------------------------------
+  { q: "what linux support does hp 2500c have", intent: "SUPPORT_QUERY", check: resolvedPrinter("HP-2500C") },
+  { q: "how good is the linux support", ctx: "printer", intent: "SUPPORT_QUERY", check: contextPrinter },
+  { q: "how good is the linux support for this printer", ctx: "printer", intent: "SUPPORT_QUERY", check: contextPrinter },
+  { q: "does hp laserjet 4 work on linux", intent: "SUPPORT_QUERY", check: resolvedPrinter("HP-LaserJet_4") },
+  { q: "is the brother hl-1050 supported", intent: "SUPPORT_QUERY", check: resolvedPrinter("Brother-HL-1050") },
+  { q: "is this printer supported on linux", ctx: "printer", intent: "SUPPORT_QUERY", check: contextPrinter },
+  { q: "linux support for epson stylus color", intent: "SUPPORT_QUERY", check: resolvedPrinter("Epson-Stylus_Color") },
+
+  // --- driver lookup ---------------------------------------------------------------
+  { q: "which driver does HP 2500C use?", intent: "DRIVER_LOOKUP", check: resolvedPrinter("HP-2500C") },
+  { q: "what driver does the hp laserjet 4 use", intent: "DRIVER_LOOKUP", check: resolvedPrinter("HP-LaserJet_4") },
+  { q: "which driver does this printer use", ctx: "printer", intent: "DRIVER_LOOKUP", check: contextPrinter },
+  { q: "recommended driver for this printer", ctx: "printer", intent: "DRIVER_LOOKUP", check: contextPrinter },
+  { q: "driver for brother hl-1050", intent: "DRIVER_LOOKUP", check: resolvedPrinter("Brother-HL-1050") },
+  { q: "drivers for hp deskjet 560c", intent: "DRIVER_LOOKUP", check: resolvedPrinter("HP-DeskJet_560C") },
+  { q: "what driver should i use", ctx: "printer", intent: "DRIVER_LOOKUP", check: contextPrinter },
+
+  // --- driver search -----------------------------------------------------------------
+  { q: "which printers use hplip", intent: "DRIVER_SEARCH", check: query => {
+      if (query.intent !== "DRIVER_SEARCH") return "wrong intent"
+      return err(query.driver.kind === "resolved" && query.driver.id === "hplip", `expected hplip, got ${JSON.stringify(query.driver)}`)
+    } },
+  { q: "which printers use hpijs?", intent: "DRIVER_SEARCH" },
+  { q: "what printers work with gutenprint", intent: "DRIVER_SEARCH" },
+  { q: "printers using ljet4", intent: "DRIVER_SEARCH" },
+  { q: "which printers use the same driver?", ctx: "printer", intent: "DRIVER_SEARCH", check: query => {
+      if (query.intent !== "DRIVER_SEARCH") return "wrong intent"
+      if (query.driver.kind !== "same-as") return `expected same-as, got ${query.driver.kind}`
+      return err(query.driver.printer.kind === "context", "expected context anchor")
+    } },
+  { q: "which printers use the same driver as hp laserjet 4", intent: "DRIVER_SEARCH", check: query => {
+      if (query.intent !== "DRIVER_SEARCH") return "wrong intent"
+      return err(query.driver.kind === "same-as", `expected same-as, got ${query.driver.kind}`)
+    } },
+  { q: "which printers use the laserjet driver", intent: "DRIVER_SEARCH", check: query => {
+      if (query.intent !== "DRIVER_SEARCH") return "wrong intent"
+      return err(query.driver.kind === "family", `family must clarify, got ${query.driver.kind}`)
+    }, fixtureOnly: true },
+  { q: "which printers use hpcups", intent: "DRIVER_SEARCH", check: query => {
+      if (query.intent !== "DRIVER_SEARCH") return "wrong intent"
+      return err(query.driver.kind !== "resolved" || query.driver.id !== "hpcups", "hpcups must not silently resolve")
+    }, fixtureOnly: true },
+
+  // --- comparison -----------------------------------------------------------------------
+  { q: "compare HP 2500C and HP DeskJet 560C", intent: "COMPARISON" },
+  { q: "compare hp 2500c and deskjet 560c", intent: "COMPARISON" },
+  { q: "hp laserjet 4 vs hp laserjet 4p", intent: "COMPARISON" },
+  { q: "hp 2500c versus hp 2500cm", intent: "COMPARISON" },
+  { q: "compare this and hp laserjet 4p", ctx: "printer", intent: "COMPARISON" },
+  { q: "compare hp laserjet 4 with hp laserjet 5", intent: "COMPARISON" },
+  { q: "what is the difference between hp 2500c and hp 2500cm", intent: "COMPARISON", check: query => err(query.intent === "COMPARISON", "expected comparison") },
+
+  // --- general info -----------------------------------------------------------------------
+  // Meaning-questions must answer generally even on a printer page: the page
+  // context must never capture them and answer with the printer's own values.
+  { q: "what do the grades mean", ctx: "printer", intent: "GENERAL_INFO" },
+  { q: "what do the support grades mean", ctx: "printer", intent: "GENERAL_INFO" },
+  { q: "what does perfect support mean", ctx: "printer", intent: "GENERAL_INFO" },
+  { q: "what does this printer's support grade mean", ctx: "printer", intent: "GENERAL_INFO" },
+  { q: "what are the grades", intent: "GENERAL_INFO" },
+  { q: "what does perfect mean", intent: "GENERAL_INFO" },
+  { q: "what do the support grades mean", intent: "GENERAL_INFO" },
+  { q: "what does mostly mean", intent: "GENERAL_INFO" },
+  { q: "what does the similarity score mean", intent: "GENERAL_INFO" },
+  { q: "what does 81 similarity mean", intent: "GENERAL_INFO" },
+  { q: "what does high confidence mean", intent: "GENERAL_INFO" },
+  { q: "what can you do", intent: "GENERAL_INFO" },
+  { q: "help", intent: "GENERAL_INFO" },
+
+  // --- contextual bare queries ---------------------------------------------------------------
+  // These DO carry a contextual reference, so page context is the right
+  // resolution - unlike the general grade questions above.
+  { q: "what is the support status of this printer", ctx: "printer", intent: "SUPPORT_QUERY", check: contextPrinter },
+  { q: "what are the grades for this printer", ctx: "printer", intent: "PRINTER_LOOKUP", check: contextPrinter },
+  {
+    q: "which printers use this driver",
+    ctx: "driver",
+    intent: "DRIVER_SEARCH",
+    check: query => {
+      if (query.intent !== "DRIVER_SEARCH") return "wrong intent"
+      return err(query.driver.kind === "context", `expected context driver ref, got ${query.driver.kind}`)
+    },
+  },
+  { q: "what about this printer?", ctx: "printer", intent: "PRINTER_LOOKUP", check: contextPrinter },
+  { q: "tell me about this one", ctx: "printer", intent: "PRINTER_LOOKUP", check: contextPrinter },
+  { q: "is this printer colour", ctx: "printer", intent: "PRINTER_LOOKUP", check: contextPrinter },
+
+  // --- definition questions stay general (and are never answered with a
+  // printer list or captured by page context) --------------------------------
+  { q: "what is postscript", ctx: "printer", intent: "UNSUPPORTED" },
+  { q: "what is pcl", ctx: "printer", intent: "UNSUPPORTED" },
+  { q: "what is a printer driver", ctx: "printer", intent: "UNSUPPORTED" },
+  { q: "what is linux support", ctx: "printer", intent: "GENERAL_INFO" },
+  { q: "what does linux support mean", ctx: "printer", intent: "GENERAL_INFO" },
+  // ...while explicit references still resolve through context:
+  { q: "what drivers does this printer use", ctx: "printer", intent: "DRIVER_LOOKUP", check: contextPrinter },
+  { q: "what does this printer support", ctx: "printer", intent: "SUPPORT_QUERY", check: contextPrinter },
+  {
+    q: "what does this driver do",
+    ctx: "driver",
+    intent: "DRIVER_SEARCH",
+    check: query => {
+      if (query.intent !== "DRIVER_SEARCH") return "wrong intent"
+      return err(query.driver.kind === "context", `expected context driver ref, got ${query.driver.kind}`)
+    },
+  },
+  {
+    q: "what about this?",
+    ctx: "driver",
+    intent: "DRIVER_SEARCH",
+    check: query => {
+      if (query.intent !== "DRIVER_SEARCH") return "wrong intent"
+      return err(query.driver.kind === "context", `expected context driver ref, got ${query.driver.kind}`)
+    },
+  },
+
+  // --- adversarial wording ----------------------------------------------------
+  { q: "printer that definitely works", intent: "CAPABILITY_SEARCH", check: unappliedIncludes("definitely") },
+  { q: "printer guaranteed to work", intent: "CAPABILITY_SEARCH", check: unappliedIncludes("guaranteed") },
+  { q: "printer with 100 percent compatibility", intent: "CAPABILITY_SEARCH", check: unappliedIncludes("compatibility") },
+  { q: "which printer has the highest quality", intent: "CAPABILITY_SEARCH", check: unappliedIncludes("quality") },
+  { q: "which printer is perfect", intent: "CAPABILITY_SEARCH", check: unappliedIncludes("perfect") },
+  { q: "4019", intent: "UNSUPPORTED" },
+  { q: "123456789", intent: "UNSUPPORTED" },
+  { q: "hello", intent: "UNSUPPORTED" },
+  { q: "thanks", intent: "UNSUPPORTED" },
+  { q: "tell me a joke", intent: "UNSUPPORTED" },
+  { q: "write python code", intent: "UNSUPPORTED" },
+  { q: "what is the stock price", intent: "UNSUPPORTED" },
+
+  // --- unsupported / out-of-domain -------------------------------------------------------------
+  { q: "what's the weather?", intent: "UNSUPPORTED" },
+  { q: "who won the football game", intent: "UNSUPPORTED" },
+  { q: "write me a poem", intent: "UNSUPPORTED" },
+  { q: "how do i install ubuntu", intent: "UNSUPPORTED" },
+  { q: "asdfghjkl", intent: "UNSUPPORTED" },
+  { q: "printer", intent: "UNSUPPORTED", check: query => err(query.intent === "UNSUPPORTED" && query.reason === "unclear", "expected unclear") },
+  { q: "", intent: "UNSUPPORTED", check: query => err(query.intent === "UNSUPPORTED" && query.reason === "empty", "expected empty") },
+  { q: "   ", intent: "UNSUPPORTED" },
+  { q: "?!", intent: "UNSUPPORTED" },
+]
diff --git a/lib/assistant/__tests__/entities.test.ts b/lib/assistant/__tests__/entities.test.ts
new file mode 100644
index 00000000..7ccc1806
--- /dev/null
+++ b/lib/assistant/__tests__/entities.test.ts
@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest"
+import { tokenize } from "../normalize"
+import { findNearMissPrinter, resolveDriverInText, resolvePrintersInText } from "../entities"
+import { INDEXES } from "./fixtures"
+
+const resolve = (text: string) => resolvePrintersInText(tokenize(text), INDEXES.printers)
+
+describe("printer entity resolution", () => {
+  it("resolves an exact catalogue id", () => {
+    expect(resolve("hp-2500c").refs).toEqual([{ kind: "resolved", id: "HP-2500C" }])
+  })
+
+  it("resolves an exact manufacturer + model name", () => {
+    expect(resolve("HP LaserJet 4").refs).toEqual([{ kind: "resolved", id: "HP-LaserJet_4" }])
+  })
+
+  it("resolves punctuation, spacing, and casing variants to the same printer", () => {
+    for (const variant of ["HL-1050", "HL 1050", "hl1050", "Brother HL-1050", "brother hl 1050"]) {
+      expect(resolve(variant).refs, variant).toEqual([{ kind: "resolved", id: "Brother-HL-1050" }])
+    }
+  })
+
+  it("resolves a unique model without the manufacturer", () => {
+    expect(resolve("deskjet 560c").refs).toEqual([{ kind: "resolved", id: "HP-DeskJet_560C" }])
+  })
+
+  it("resolves manufacturer aliases", () => {
+    expect(resolve("hewlett packard 2500c").refs).toEqual([{ kind: "resolved", id: "HP-2500C" }])
+    expect(resolve("hewlett-packard 2500c").refs).toEqual([{ kind: "resolved", id: "HP-2500C" }])
+  })
+
+  it("does not confuse 2500C with 2500CM", () => {
+    expect(resolve("hp 2500c").refs).toEqual([{ kind: "resolved", id: "HP-2500C" }])
+    expect(resolve("hp 2500cm").refs).toEqual([{ kind: "resolved", id: "HP-2500CM" }])
+  })
+
+  it("returns an ambiguity with candidates for a partial family name", () => {
+    const refs = resolve("hp laserjet").refs
+    expect(refs).toHaveLength(1)
+    expect(refs[0].kind).toBe("ambiguous")
+    if (refs[0].kind === "ambiguous") {
+      expect(refs[0].total).toBeGreaterThan(1)
+      const ids = refs[0].candidates.map(candidate => candidate.id)
+      expect(ids).toContain("HP-LaserJet_4")
+      // Deterministic candidate order: sorted by id.
+      expect(ids).toEqual([...ids].sort((a, b) => a.localeCompare(b)))
+    }
+  })
+
+  it("never resolves a bare capability word as an entity", () => {
+    // "laser" must not prefix-match the LaserJet family.
+    expect(resolve("colour laser printer").refs).toEqual([])
+    expect(resolve("laser").refs).toEqual([])
+  })
+
+  it("finds two printers for comparison phrasing", () => {
+    const refs = resolve("compare hp 2500c and deskjet 560c").refs
+    expect(refs).toEqual([
+      { kind: "resolved", id: "HP-2500C" },
+      { kind: "resolved", id: "HP-DeskJet_560C" },
+    ])
+  })
+
+  it("reports a standalone manufacturer mention without inventing an entity", () => {
+    const result = resolve("show me canon printers")
+    expect(result.refs).toEqual([])
+    expect(result.makeOnly).toBe("Canon")
+  })
+
+  it("does not fabricate a match for a model that is not in the data", () => {
+    // "Brother HL-2270DW" is deliberately absent from the catalogue: the scan
+    // must yield no resolved ref (the near-miss handling in parse.ts turns
+    // this into an unresolved ref with suggestions).
+    const result = resolve("brother hl 2270dw")
+    expect(result.refs).toEqual([])
+    expect(result.makeOnly).toBe("Brother")
+  })
+
+  it("builds an unresolved near-miss ref with real-catalogue suggestions", () => {
+    const tokens = tokenize("brother hl 2270dw")
+    const scan = resolvePrintersInText(tokens, INDEXES.printers)
+    const nearMiss = findNearMissPrinter(tokens, scan.consumed, INDEXES.printers, scan.makeOnly, () => false)
+    expect(nearMiss).not.toBeNull()
+    if (nearMiss) {
+      expect(nearMiss.ref.kind).toBe("unresolved")
+      if (nearMiss.ref.kind === "unresolved") {
+        expect(nearMiss.ref.text).toContain("hl 2270dw")
+        expect(nearMiss.ref.suggestions.length).toBeGreaterThan(0)
+        // Suggestions are real catalogue entries, never invented.
+        for (const suggestion of nearMiss.ref.suggestions) {
+          expect(INDEXES.printers.byId.has(suggestion.id)).toBe(true)
+        }
+      }
+    }
+  })
+
+  it("is deterministic for repeated calls", () => {
+    const a = JSON.stringify(resolve("hp laserjet"))
+    const b = JSON.stringify(resolve("hp laserjet"))
+    expect(a).toBe(b)
+  })
+})
+
+describe("driver entity resolution", () => {
+  const resolveDriver = (text: string, required = true) => {
+    const tokens = tokenize(text)
+    return resolveDriverInText(tokens, new Set(), INDEXES.drivers, required)
+  }
+
+  it("resolves an exact driver id", () => {
+    expect(resolveDriver("which printers use hpijs")).toEqual({ kind: "resolved", id: "hpijs" })
+  })
+
+  it("treats a driver family as a clarification, never a silent expansion", () => {
+    const ref = resolveDriver("which printers use the laserjet driver")
+    expect(ref).toEqual({ kind: "family", family: "laserjet", members: ["lj4dith", "ljet4"] })
+  })
+
+  it("suggests near names for an unknown driver when one is required", () => {
+    const ref = resolveDriver("which printers use hpcups")
+    expect(ref?.kind).toBe("unresolved")
+    if (ref?.kind === "unresolved") {
+      expect(ref.suggestions).toContain("hpijs")
+      expect(ref.suggestions).toContain("hplip")
+    }
+  })
+
+  it("returns null when no driver is mentioned and none is required", () => {
+    expect(resolveDriver("which printers are fast", false)).toBeNull()
+  })
+})
diff --git a/lib/assistant/__tests__/execute.test.ts b/lib/assistant/__tests__/execute.test.ts
new file mode 100644
index 00000000..19c038f4
--- /dev/null
+++ b/lib/assistant/__tests__/execute.test.ts
@@ -0,0 +1,351 @@
+import { describe, expect, it } from "vitest"
+import { executeQuery } from "../execute"
+import type { AssistantQuery, CapabilityFilters } from "../types"
+import { BJC_CONTEXT, fixtureData, HOME_CONTEXT, LJ4_CONTEXT } from "./fixtures"
+
+const data = fixtureData()
+
+function search(filters: CapabilityFilters, unapplied: string[] = [], recommend = false): AssistantQuery {
+  return { intent: "CAPABILITY_SEARCH", filters, unapplied, recommend }
+}
+
+describe("capability search execution", () => {
+  it("filters on known values and orders by the documented default", async () => {
+    const execution = await executeQuery(search({ type: "laser", support: "good" }), HOME_CONTEXT, data)
+    expect(execution.kind).toBe("search-results")
+    if (execution.kind !== "search-results") return
+    expect(execution.state).toBe("SUCCESS")
+    // Perfect before Mostly, more drivers first, id ascending on full ties.
+    expect(execution.matches[0].id).toBe("HP-LaserJet_5")
+    expect(execution.matches[1].id).toBe("HP-LaserJet_4")
+    expect(execution.matches[2].id).toBe("HP-LaserJet_4P")
+    expect(execution.matches[execution.matches.length - 1].id).toBe("Okidata-OL400")
+    // IBM-4019 has status Unknown: excluded but counted as unknown, not "no".
+    const supportDiag = execution.diagnostics.filters.find(f => f.label.includes("Linux support"))
+    expect(supportDiag?.excludedUnknown).toBe(1)
+    expect(execution.diagnostics.orderingLabel).toBe("Linux support status, then number of listed drivers")
+  })
+
+  it("never turns unknown colour into a negative: unknowns are excluded from both polarities", async () => {
+    const colour = await executeQuery(search({ color: true }), HOME_CONTEXT, data)
+    const mono = await executeQuery(search({ color: false }), HOME_CONTEXT, data)
+    if (colour.kind !== "search-results" || mono.kind !== "search-results") throw new Error("wrong kind")
+    const colourIds = colour.matches.map(m => m.id)
+    const monoIds = mono.matches.map(m => m.id)
+    // IBM-4019's colour is unrecorded: it must appear in neither result...
+    expect(colourIds).not.toContain("IBM-4019")
+    expect(monoIds).not.toContain("IBM-4019")
+    // ...and must be counted as unknown-excluded in both.
+    expect(colour.diagnostics.filters[0].excludedUnknown).toBe(1)
+    expect(mono.diagnostics.filters[0].excludedUnknown).toBe(1)
+  })
+
+  it("requested resolution becomes the leading ordering key", async () => {
+    const execution = await executeQuery(search({ minDpi: 600 }), HOME_CONTEXT, data)
+    if (execution.kind !== "search-results") throw new Error("wrong kind")
+    expect(execution.matches[0].id).toBe("Xerox-Phaser_6100") // 1200 dpi
+    expect(execution.matches[1].id).toBe("Epson-Stylus_Color") // 720 dpi
+    expect(execution.diagnostics.orderingLabel).toContain("recorded maximum resolution")
+  })
+
+  it("evidences PostScript positively and never claims absence", async () => {
+    const execution = await executeQuery(search({ postscript: {} }), HOME_CONTEXT, data)
+    if (execution.kind !== "search-results") throw new Error("wrong kind")
+    const ids = execution.matches.map(m => m.id)
+    expect(ids).toContain("Apple-LaserWriter")
+    expect(ids).toContain("Xerox-Phaser_6100")
+    // Everything else is unknown-excluded: there is no known-negative for PDLs
+    // without a level constraint.
+    expect(execution.diagnostics.filters[0].excludedKnown).toBe(0)
+  })
+
+  it("applies PostScript level constraints on recorded levels", async () => {
+    const execution = await executeQuery(search({ postscript: { minLevel: 3 } }), HOME_CONTEXT, data)
+    if (execution.kind !== "search-results") throw new Error("wrong kind")
+    expect(execution.matches.map(m => m.id)).toEqual(["Xerox-Phaser_6100"])
+  })
+
+  it("reports duplex as insufficient data instead of filtering", async () => {
+    const duplexOnly = await executeQuery(search({ duplex: true }), HOME_CONTEXT, data)
+    expect(duplexOnly.kind).toBe("insufficient")
+    if (duplexOnly.kind === "insufficient" && duplexOnly.message.topic === "duplex") {
+      expect(duplexOnly.message.catalogSize).toBe(13)
+    }
+
+    const mixed = await executeQuery(search({ duplex: true, color: true, type: "laser" }), HOME_CONTEXT, data)
+    expect(mixed.kind).toBe("search-results")
+    if (mixed.kind === "search-results") {
+      expect(mixed.diagnostics.insufficient).toEqual(["duplex"])
+      expect(mixed.matches.map(m => m.id)).toEqual(["Xerox-Phaser_6100"])
+    }
+  })
+
+  it("clarifies criteria-free recommendation requests instead of ranking", async () => {
+    const execution = await executeQuery(search({}, [], true), HOME_CONTEXT, data)
+    expect(execution.kind).toBe("clarify")
+    if (execution.kind === "clarify") {
+      expect(execution.question.topic).toBe("criteria-needed")
+    }
+  })
+
+  it("surfaces unrecognized-only constraints as unsupported, not as no-matches", async () => {
+    const execution = await executeQuery(search({}, ["purple"]), HOME_CONTEXT, data)
+    expect(execution.kind).toBe("search-results")
+    if (execution.kind === "search-results") {
+      expect(execution.state).toBe("UNSUPPORTED")
+      expect(execution.diagnostics.unapplied).toEqual(["purple"])
+    }
+  })
+
+  it("offers one-filter relaxations when nothing matches, each labelled with its own filter", async () => {
+    const execution = await executeQuery(
+      search({ color: true, type: "laser", minDpi: 2400 }),
+      HOME_CONTEXT,
+      data
+    )
+    if (execution.kind !== "search-results") throw new Error("wrong kind")
+    expect(execution.state).toBe("NO_MATCHES")
+    const dropped = execution.diagnostics.relaxations.map(r => r.droppedLabel)
+    expect(dropped).toContain("at least 2400 dpi")
+    // Labels must correspond to the dropped filter, not another one: dropping
+    // "colour" from {colour, laser, 2400dpi} leaves laser+2400dpi (0 matches),
+    // so no "colour" relaxation exists; dropping the dpi leaves colour lasers.
+    expect(dropped).not.toContain("colour")
+    for (const relaxation of execution.diagnostics.relaxations) {
+      expect(relaxation.resultCount).toBeGreaterThan(0)
+    }
+  })
+
+  it("surfaces both the duplex gap and unrecognized constraints together", async () => {
+    const execution = await executeQuery(search({ duplex: true }, ["purple"]), HOME_CONTEXT, data)
+    expect(execution.kind).toBe("search-results")
+    if (execution.kind === "search-results") {
+      expect(execution.diagnostics.insufficient).toEqual(["duplex"])
+      expect(execution.diagnostics.unapplied).toEqual(["purple"])
+    }
+  })
+})
+
+describe("similarity execution (PR #224 shards, consumed verbatim)", () => {
+  const similar = (overrides: Partial<Extract<AssistantQuery, { intent: "SIMILAR_PRINTERS" }>> = {}): AssistantQuery => ({
+    intent: "SIMILAR_PRINTERS",
+    printer: { kind: "context" },
+    filters: {},
+    unapplied: [],
+    ...overrides,
+  })
+
+  it("preserves shard order and scores exactly", async () => {
+    const execution = await executeQuery(similar(), LJ4_CONTEXT, data)
+    if (execution.kind !== "similar") throw new Error(`wrong kind ${execution.kind}`)
+    expect(execution.entries.map(e => e.id)).toEqual([
+      "HP-LaserJet_4P", "HP-LaserJet_5", "Okidata-OL400", "Xerox-Phaser_6100",
+    ])
+    expect(execution.entries.map(e => e.score)).toEqual([0.895, 0.885, 0.61, 0.52])
+  })
+
+  it("post-filters the shard without re-ranking", async () => {
+    const execution = await executeQuery(similar({ filters: { color: true } }), LJ4_CONTEXT, data)
+    if (execution.kind !== "similar") throw new Error("wrong kind")
+    expect(execution.entries.map(e => e.id)).toEqual(["Xerox-Phaser_6100"])
+    expect(execution.totalBeforeFilters).toBe(4)
+  })
+
+  it("reports the whole catalogue's size in the duplex caveat, not the shard's", async () => {
+    const execution = await executeQuery(
+      similar({ filters: { duplex: true, color: true } }),
+      LJ4_CONTEXT,
+      data
+    )
+    if (execution.kind !== "similar") throw new Error("wrong kind")
+    expect(execution.diagnostics?.insufficient).toEqual(["duplex"])
+    expect(execution.diagnostics?.catalogSize).toBe(13)
+  })
+
+  it("clarifies the dimension for unspecified 'better'", async () => {
+    const execution = await executeQuery(similar({ better: "unspecified" }), LJ4_CONTEXT, data)
+    expect(execution.kind).toBe("clarify")
+    if (execution.kind === "clarify" && execution.question.topic === "better-dimension") {
+      expect(execution.question.anchorName).toBe("HP LaserJet 4")
+    }
+  })
+
+  it("better:support keeps shard order, excludes Unknown grades, and compares grades only", async () => {
+    const execution = await executeQuery(
+      { intent: "SIMILAR_PRINTERS", printer: { kind: "context" }, filters: {}, unapplied: [], better: "support" },
+      BJC_CONTEXT,
+      data
+    )
+    if (execution.kind !== "similar") throw new Error("wrong kind")
+    // Canon BJC-210 is Mostly; Epson and DeskJet are Perfect; IBM-4019 is
+    // Unknown and must be excluded, never treated as lower.
+    expect(execution.entries.map(e => e.id)).toEqual(["Epson-Stylus_Color", "HP-DeskJet_560C"])
+  })
+
+  it("better:support from a Perfect anchor returns an empty comparison, not a downgrade", async () => {
+    const execution = await executeQuery(similar({ better: "support" }), LJ4_CONTEXT, data)
+    if (execution.kind !== "similar") throw new Error("wrong kind")
+    expect(execution.entries).toEqual([])
+    expect(execution.state).toBe("SUCCESS")
+  })
+
+  it("better:resolution compares recorded values only", async () => {
+    const execution = await executeQuery(similar({ better: "resolution" }), LJ4_CONTEXT, data)
+    if (execution.kind !== "similar") throw new Error("wrong kind")
+    expect(execution.entries.map(e => e.id)).toEqual(["Xerox-Phaser_6100"])
+    expect(execution.sourceMaxDpi).toBe(600)
+  })
+
+  it("better:drivers compares listed driver counts", async () => {
+    const execution = await executeQuery(similar({ better: "drivers" }), LJ4_CONTEXT, data)
+    if (execution.kind !== "similar") throw new Error("wrong kind")
+    expect(execution.entries.map(e => e.id)).toEqual(["HP-LaserJet_5"])
+  })
+
+  it("reports missing similarity data honestly", async () => {
+    const execution = await executeQuery(
+      similar({ printer: { kind: "resolved", id: "HP-2500C" } }),
+      HOME_CONTEXT,
+      data
+    )
+    expect(execution.kind).toBe("insufficient")
+    if (execution.kind === "insufficient" && execution.message.topic === "no-recommendation-data") {
+      expect(execution.message.printerName).toBe("HP 2500C")
+    }
+  })
+
+  it("asks for context when 'this printer' has none", async () => {
+    const execution = await executeQuery(similar(), HOME_CONTEXT, data)
+    expect(execution.kind).toBe("clarify")
+    if (execution.kind === "clarify") {
+      expect(execution.question.topic).toBe("context-needed")
+    }
+  })
+})
+
+describe("explanation execution", () => {
+  it("returns the shard entry for a named candidate", async () => {
+    const execution = await executeQuery(
+      { intent: "EXPLANATION", source: { kind: "context" }, candidate: { kind: "resolved", id: "HP-LaserJet_4P" } },
+      LJ4_CONTEXT,
+      data
+    )
+    if (execution.kind !== "explanation") throw new Error(`wrong kind ${execution.kind}`)
+    expect(execution.entry.score).toBe(0.895)
+    expect(execution.entry.sharedFeatures).toContain("Preferred Linux driver: hplip")
+  })
+
+  it("is honest when the candidate is not in the recommendation list", async () => {
+    const execution = await executeQuery(
+      { intent: "EXPLANATION", source: { kind: "context" }, candidate: { kind: "resolved", id: "Brother-HL-1050" } },
+      LJ4_CONTEXT,
+      data
+    )
+    expect(execution.kind).toBe("explanation-none")
+  })
+
+  it("asks which recommendation to explain when none was named", async () => {
+    const execution = await executeQuery(
+      { intent: "EXPLANATION", source: { kind: "context" }, candidate: null },
+      LJ4_CONTEXT,
+      data
+    )
+    expect(execution.kind).toBe("clarify")
+    if (execution.kind === "clarify" && execution.question.topic === "explanation-candidate") {
+      expect(execution.question.topRecommendations).toHaveLength(3)
+    }
+  })
+})
+
+describe("driver execution", () => {
+  it("looks up a printer's drivers", async () => {
+    const execution = await executeQuery(
+      { intent: "DRIVER_LOOKUP", printer: { kind: "resolved", id: "HP-2500C" } },
+      HOME_CONTEXT,
+      data
+    )
+    if (execution.kind !== "driver-lookup") throw new Error("wrong kind")
+    expect(execution.printer.recommended_driver).toBe("driver/hplip")
+  })
+
+  it("resolves 'same driver as this' through the recommended driver, disclosed", async () => {
+    const execution = await executeQuery(
+      { intent: "DRIVER_SEARCH", driver: { kind: "same-as", printer: { kind: "context" } } },
+      LJ4_CONTEXT,
+      data
+    )
+    if (execution.kind !== "driver-search") throw new Error(`wrong kind ${execution.kind}`)
+    expect(execution.anchorDriverName).toBe("hplip")
+    expect(execution.driver.printers.map(p => p.id)).toContain("HP-LaserJet_4P")
+  })
+
+  it("returns the reverse index for a resolved driver", async () => {
+    const execution = await executeQuery(
+      { intent: "DRIVER_SEARCH", driver: { kind: "resolved", id: "hplip" } },
+      HOME_CONTEXT,
+      data
+    )
+    if (execution.kind !== "driver-search") throw new Error("wrong kind")
+    expect(execution.driver.printerCount).toBe(4)
+  })
+
+  it("clarifies driver families instead of expanding them silently", async () => {
+    const execution = await executeQuery(
+      { intent: "DRIVER_SEARCH", driver: { kind: "family", family: "laserjet", members: ["lj4dith", "ljet4"] } },
+      HOME_CONTEXT,
+      data
+    )
+    expect(execution.kind).toBe("clarify")
+  })
+})
+
+describe("comparison and reference handling", () => {
+  it("compares two resolved printers from their full records", async () => {
+    const execution = await executeQuery(
+      {
+        intent: "COMPARISON",
+        printers: [
+          { kind: "resolved", id: "HP-2500C" },
+          { kind: "resolved", id: "HP-DeskJet_560C" },
+        ],
+      },
+      HOME_CONTEXT,
+      data
+    )
+    if (execution.kind !== "comparison") throw new Error("wrong kind")
+    expect(execution.a.id).toBe("HP-2500C")
+    expect(execution.b.id).toBe("HP-DeskJet_560C")
+  })
+
+  it("clarifies ambiguous references with their candidates", async () => {
+    const execution = await executeQuery(
+      {
+        intent: "PRINTER_LOOKUP",
+        printer: {
+          kind: "ambiguous",
+          text: "hp laserjet",
+          candidates: [
+            { id: "HP-LaserJet_4", manufacturer: "HP", model: "LaserJet 4", score: 1 },
+            { id: "HP-LaserJet_4P", manufacturer: "HP", model: "LaserJet 4P", score: 1 },
+          ],
+          total: 3,
+        },
+      },
+      HOME_CONTEXT,
+      data
+    )
+    expect(execution.kind).toBe("clarify")
+  })
+
+  it("reports unresolved references as entity misses with suggestions", async () => {
+    const execution = await executeQuery(
+      {
+        intent: "PRINTER_LOOKUP",
+        printer: { kind: "unresolved", text: "Brother hl 2270dw", suggestions: [] },
+      },
+      HOME_CONTEXT,
+      data
+    )
+    expect(execution.kind).toBe("entity-miss")
+  })
+})
diff --git a/lib/assistant/__tests__/fixtures.ts b/lib/assistant/__tests__/fixtures.ts
new file mode 100644
index 00000000..120c044d
--- /dev/null
+++ b/lib/assistant/__tests__/fixtures.ts
@@ -0,0 +1,153 @@
+// Shared in-memory fixtures for the assistant tests. The catalogue slice is
+// modelled on real records (ids, statuses, capability fields all follow the
+// shapes produced by lib/foomatic/catalog.ts) so tests exercise realistic
+// data without depending on the generated artifacts.
+
+import type { DriverRecord, DriverSummary, Printer, PrinterSummary } from "@/lib/foomatic/types"
+import { buildDriverIndex, buildPrinterIndex } from "../entities"
+import type { AssistantData, RecommendationEntry } from "../types"
+
+export const CATALOG: PrinterSummary[] = [
+  { id: "HP-2500C", manufacturer: "HP", model: "2500C", type: "inkjet", status: "Perfect", functionality: "A", driverCount: 5, color: true, maxDpi: 600, cs: ["PCL"], rd: "hplip" },
+  { id: "HP-2500CM", manufacturer: "HP", model: "2500CM", type: "inkjet", status: "Mostly", functionality: "B", driverCount: 4, color: true, maxDpi: 600 },
+  { id: "HP-DeskJet_560C", manufacturer: "HP", model: "DeskJet 560C", type: "inkjet", status: "Perfect", functionality: "A", driverCount: 6, color: true, maxDpi: 300, rd: "hpijs" },
+  { id: "HP-LaserJet_4", manufacturer: "HP", model: "LaserJet 4", type: "laser", status: "Perfect", functionality: "A", driverCount: 6, color: false, maxDpi: 600, pclLevel: 5, cs: ["PCL5E", "PJL"], rd: "hplip" },
+  { id: "HP-LaserJet_4P", manufacturer: "HP", model: "LaserJet 4P", type: "laser", status: "Perfect", functionality: "A", driverCount: 6, color: false, maxDpi: 600, pclLevel: 5, rd: "hplip" },
+  { id: "HP-LaserJet_5", manufacturer: "HP", model: "LaserJet 5", type: "laser", status: "Perfect", functionality: "A", driverCount: 8, color: false, maxDpi: 600, pclLevel: 5, rd: "hplip" },
+  { id: "Brother-HL-1050", manufacturer: "Brother", model: "HL-1050", type: "laser", status: "Perfect", functionality: "A", driverCount: 4, color: false, maxDpi: 600, rd: "laserjet" },
+  { id: "Canon-BJC-210", manufacturer: "Canon", model: "BJC-210", type: "inkjet", status: "Mostly", functionality: "B", driverCount: 3, color: true, maxDpi: 360 },
+  { id: "Epson-Stylus_Color", manufacturer: "Epson", model: "Stylus Color", type: "inkjet", status: "Perfect", functionality: "A", driverCount: 5, color: true, maxDpi: 720 },
+  { id: "Apple-LaserWriter", manufacturer: "Apple", model: "LaserWriter", type: "laser", status: "Perfect", functionality: "A", driverCount: 3, color: false, maxDpi: 300, psLevel: 2, cs: ["POSTSCRIPT"] },
+  { id: "IBM-4019", manufacturer: "IBM", model: "4019", type: "laser", status: "Unknown", functionality: "?", driverCount: 2, color: "unknown" },
+  { id: "Xerox-Phaser_6100", manufacturer: "Xerox", model: "Phaser 6100", type: "laser", status: "Perfect", functionality: "A", driverCount: 4, color: true, maxDpi: 1200, psLevel: 3, cs: ["POSTSCRIPT"], rd: "postscript" },
+  { id: "Okidata-OL400", manufacturer: "Okidata", model: "OL400", type: "laser", status: "Mostly", functionality: "B", driverCount: 2, color: false, maxDpi: 300, pclLevel: 4 },
+]
+
+export const DRIVERS: DriverSummary[] = [
+  { id: "hplip", name: "hplip", supplier: "HP", type: "Filter", obsolete: false, shortDescription: "HPLIP", printerCount: 4 },
+  { id: "hpijs", name: "hpijs", supplier: "HP", type: "IJS", obsolete: false, shortDescription: "HPIJS", printerCount: 3 },
+  { id: "ljet4", name: "ljet4", supplier: "GPL Ghostscript", type: "Ghostscript built-in", obsolete: false, shortDescription: "PCL5e laser", printerCount: 2 },
+  { id: "lj4dith", name: "lj4dith", supplier: "GPL Ghostscript", type: "Ghostscript built-in", obsolete: false, shortDescription: "Dithered", printerCount: 1 },
+  { id: "gutenprint", name: "gutenprint", supplier: "Gutenprint", type: "CUPS raster", obsolete: false, shortDescription: "Gutenprint", printerCount: 5 },
+  { id: "epson", name: "epson", supplier: "GPL Ghostscript", type: "Ghostscript built-in", obsolete: false, shortDescription: "Epson", printerCount: 2 },
+]
+
+const summaryById = new Map(CATALOG.map(printer => [printer.id, printer]))
+
+function fullPrinter(id: string, overrides: Partial<Printer> = {}): Printer {
+  const summary = summaryById.get(id)
+  if (!summary) throw new Error(`fixture printer missing: ${id}`)
+  return {
+    id: summary.id,
+    manufacturer: summary.manufacturer,
+    model: summary.model,
+    type: summary.type,
+    status: summary.status,
+    functionality: summary.functionality,
+    color: summary.color,
+    duplex: "unknown",
+    maxDpi: summary.maxDpi ?? null,
+    psLevel: summary.psLevel ?? null,
+    pclLevel: summary.pclLevel ?? null,
+    commandsets: [],
+    commandsetTokens: summary.cs ?? [],
+    recommended_driver: summary.rd ? `driver/${summary.rd === "laserjet" ? "ljet4" : summary.rd}` : undefined,
+    drivers: Array.from({ length: summary.driverCount ?? 0 }, (_, i) => ({
+      id: `driver/fixture-${i}`,
+      name: i === 0 && summary.rd ? (summary.rd === "laserjet" ? "ljet4" : summary.rd) : `fixture-${i}`,
+    })),
+    ...overrides,
+  }
+}
+
+export const RECOMMENDATIONS: Record<string, RecommendationEntry[]> = {
+  "HP-LaserJet_4": [
+    {
+      id: "HP-LaserJet_4P", score: 0.895, manufacturer: "HP", model: "LaserJet 4P",
+      status: "Perfect", type: "laser", driverCount: 6,
+      sharedFeatures: ["Preferred Linux driver: hplip", "Laser printer", "PCL 5e", "Similar resolution (300-600 dpi)", "Excellent Linux driver support"],
+    },
+    {
+      id: "HP-LaserJet_5", score: 0.885, manufacturer: "HP", model: "LaserJet 5",
+      status: "Perfect", type: "laser", driverCount: 8,
+      sharedFeatures: ["Preferred Linux driver: hplip", "Laser printer", "PCL 5e"],
+    },
+    {
+      id: "Okidata-OL400", score: 0.61, manufacturer: "Okidata", model: "OL400",
+      status: "Mostly", type: "laser", driverCount: 2,
+      sharedFeatures: ["Laser printer"],
+    },
+    {
+      id: "Xerox-Phaser_6100", score: 0.52, manufacturer: "Xerox", model: "Phaser 6100",
+      status: "Perfect", type: "laser", driverCount: 4,
+      sharedFeatures: ["Laser printer"],
+    },
+  ],
+  "Canon-BJC-210": [
+    {
+      id: "Epson-Stylus_Color", score: 0.71, manufacturer: "Epson", model: "Stylus Color",
+      status: "Perfect", type: "inkjet", driverCount: 5,
+      sharedFeatures: ["Inkjet printer", "Color printing"],
+    },
+    {
+      id: "HP-DeskJet_560C", score: 0.55, manufacturer: "HP", model: "DeskJet 560C",
+      status: "Perfect", type: "inkjet", driverCount: 6,
+      sharedFeatures: ["Inkjet printer", "Color printing"],
+    },
+    {
+      id: "IBM-4019", score: 0.4, manufacturer: "IBM", model: "4019",
+      status: "Unknown", type: "laser", driverCount: 2,
+      sharedFeatures: [],
+    },
+  ],
+}
+
+export const DRIVER_RECORDS: Record<string, DriverRecord> = {
+  hplip: {
+    id: "hplip", name: "hplip", supplier: "HP", printerCount: 4,
+    printers: [
+      { id: "HP-2500C", manufacturer: "HP", model: "2500C", status: "Perfect", recommended: true },
+      { id: "HP-LaserJet_4", manufacturer: "HP", model: "LaserJet 4", status: "Perfect", recommended: true },
+      { id: "HP-LaserJet_4P", manufacturer: "HP", model: "LaserJet 4P", status: "Perfect", recommended: true },
+      { id: "HP-LaserJet_5", manufacturer: "HP", model: "LaserJet 5", status: "Perfect", recommended: true },
+    ],
+  },
+  hpijs: {
+    id: "hpijs", name: "hpijs", supplier: "HP", printerCount: 1,
+    printers: [{ id: "HP-DeskJet_560C", manufacturer: "HP", model: "DeskJet 560C", status: "Perfect", recommended: true }],
+  },
+  ljet4: {
+    id: "ljet4", name: "ljet4", supplier: "GPL Ghostscript", printerCount: 2,
+    printers: [
+      { id: "Brother-HL-1050", manufacturer: "Brother", model: "HL-1050", status: "Perfect", recommended: true },
+      { id: "HP-LaserJet_4", manufacturer: "HP", model: "LaserJet 4", status: "Perfect", recommended: false },
+    ],
+  },
+}
+
+export function fixtureData(): AssistantData {
+  return {
+    getCatalog: async () => CATALOG,
+    getPrinter: async id => (summaryById.has(id) ? fullPrinter(id) : null),
+    getRecommendations: async id => RECOMMENDATIONS[id] ?? [],
+    getDriversMap: async () => DRIVERS,
+    getDriver: async id => DRIVER_RECORDS[id] ?? null,
+  }
+}
+
+export const INDEXES = {
+  printers: buildPrinterIndex(CATALOG),
+  drivers: buildDriverIndex(DRIVERS),
+}
+
+export const HOME_CONTEXT = { pageType: "home", route: "/" } as const
+export const LJ4_CONTEXT = {
+  pageType: "printer",
+  route: "/foomatic/printer/HP/HP-LaserJet_4",
+  printerId: "HP-LaserJet_4",
+} as const
+export const BJC_CONTEXT = {
+  pageType: "printer",
+  route: "/foomatic/printer/Canon/Canon-BJC-210",
+  printerId: "Canon-BJC-210",
+} as const
diff --git a/lib/assistant/__tests__/normalize.test.ts b/lib/assistant/__tests__/normalize.test.ts
new file mode 100644
index 00000000..b03d29ec
--- /dev/null
+++ b/lib/assistant/__tests__/normalize.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest"
+import { MAX_QUERY_LENGTH } from "../constants"
+import { fuseText, normalizeText, tokenize } from "../normalize"
+
+describe("normalizeText", () => {
+  it("lowercases and collapses punctuation to single spaces", () => {
+    expect(normalizeText("Brother HL-1050!")).toBe("brother hl 1050")
+    expect(normalizeText("  Colour,  laser??  ")).toBe("colour laser")
+  })
+
+  it("caps input length", () => {
+    const long = "a".repeat(MAX_QUERY_LENGTH * 2)
+    expect(normalizeText(long).length).toBe(MAX_QUERY_LENGTH)
+  })
+})
+
+describe("fuseText", () => {
+  it("unifies punctuation and spacing variants of model numbers", () => {
+    expect(fuseText("HL-1050")).toBe("hl1050")
+    expect(fuseText("HL 1050")).toBe("hl1050")
+    expect(fuseText("hl1050")).toBe("hl1050")
+    expect(fuseText("LaserJet 4")).toBe("laserjet4")
+  })
+})
+
+describe("tokenize", () => {
+  it("splits on the normalized form", () => {
+    expect(tokenize("find a colour laser printer")).toEqual(["find", "a", "colour", "laser", "printer"])
+  })
+
+  it("returns an empty array for empty or punctuation-only input", () => {
+    expect(tokenize("")).toEqual([])
+    expect(tokenize("?!.")).toEqual([])
+  })
+})
diff --git a/lib/assistant/__tests__/parse.test.ts b/lib/assistant/__tests__/parse.test.ts
new file mode 100644
index 00000000..4adc5448
--- /dev/null
+++ b/lib/assistant/__tests__/parse.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest"
+import type { AssistantPageContext } from "../types"
+import { parseQuery } from "../parse"
+import { CORPUS } from "./corpus"
+import { HOME_CONTEXT, INDEXES, LJ4_CONTEXT } from "./fixtures"
+
+const DRIVER_CONTEXT: AssistantPageContext = {
+  pageType: "driver",
+  route: "/foomatic/driver/hplip",
+  driverId: "hplip",
+}
+
+function contextFor(ctx?: "home" | "printer" | "driver"): AssistantPageContext {
+  if (ctx === "printer") return LJ4_CONTEXT
+  if (ctx === "driver") return DRIVER_CONTEXT
+  return HOME_CONTEXT
+}
+
+describe("natural-language corpus", () => {
+  for (const testCase of CORPUS) {
+    it(`[${testCase.intent}] "${testCase.q}"${testCase.ctx ? ` (on ${testCase.ctx} page)` : ""}`, () => {
+      const query = parseQuery(testCase.q, contextFor(testCase.ctx), INDEXES)
+      expect(query.intent).toBe(testCase.intent)
+      if (testCase.check) {
+        expect(testCase.check(query)).toBeNull()
+      }
+    })
+  }
+})
+
+describe("parser determinism", () => {
+  it("returns identical output for identical input", () => {
+    for (const input of ["find a colour laser printer", "printers similar to hp 2500c", "hp laserjet"]) {
+      const a = parseQuery(input, HOME_CONTEXT, INDEXES)
+      const b = parseQuery(input, HOME_CONTEXT, INDEXES)
+      expect(JSON.stringify(a)).toBe(JSON.stringify(b))
+    }
+  })
+
+  it("caps hostile input without throwing", () => {
+    const noisy = "colour ".repeat(500) + "<script>alert(1)</script>"
+    expect(() => parseQuery(noisy, HOME_CONTEXT, INDEXES)).not.toThrow()
+  })
+})
diff --git a/lib/assistant/__tests__/respond.test.ts b/lib/assistant/__tests__/respond.test.ts
new file mode 100644
index 00000000..05766c32
--- /dev/null
+++ b/lib/assistant/__tests__/respond.test.ts
@@ -0,0 +1,344 @@
+import { describe, expect, it } from "vitest"
+import { runAssistant } from "../engine"
+import { buildResponse, contextSuggestions } from "../respond"
+import type { AssistantPageContext, Execution, ResponsePlan } from "../types"
+import { CORPUS } from "./corpus"
+import { CATALOG, fixtureData, HOME_CONTEXT, LJ4_CONTEXT, RECOMMENDATIONS } from "./fixtures"
+
+const data = fixtureData()
+
+// Terminology that PR #224 banned for recommendation language
+// (tools/eval/check-docs.mjs) plus assistant-specific equivalents. No
+// response, for any corpus utterance, may ever produce these.
+const BANNED_PATTERNS = [
+  /exact match/i,
+  /% match\b/i,
+  /% compatible/i,
+  /compatibility (probability|percentage|score)/i,
+  /guaranteed to work/i,
+  /\bbest printer overall\b/i,
+]
+
+function allText(plan: ResponsePlan): string {
+  return plan.blocks
+    .map(block => {
+      switch (block.kind) {
+        case "text":
+          return block.text
+        case "list":
+          return `${block.title} ${block.items.join(" ")}`
+        case "chips":
+          return block.chips.map(chip => chip.label).join(" ")
+        case "comparison":
+          return block.rows.map(row => `${row.label} ${row.a} ${row.b}`).join(" ")
+        default:
+          return ""
+      }
+    })
+    .join(" ")
+}
+
+function contextFor(ctx?: "home" | "printer" | "driver"): AssistantPageContext {
+  if (ctx === "printer") return LJ4_CONTEXT
+  if (ctx === "driver") return { pageType: "driver", route: "/foomatic/driver/hplip", driverId: "hplip" }
+  return HOME_CONTEXT
+}
+
+describe("grounding: every rendered claim traces to fixture data", () => {
+  const knownIds = new Set(CATALOG.map(printer => printer.id))
+  const knownScores = new Set(
+    Object.values(RECOMMENDATIONS).flat().map(entry => Math.round(entry.score * 100))
+  )
+
+  it("full corpus sweep: cards reference real printers, similarity percentages match shard scores, no banned wording", async () => {
+    for (const testCase of CORPUS) {
+      const turn = await runAssistant(testCase.q, contextFor(testCase.ctx), data)
+      const text = allText(turn.plan)
+
+      for (const pattern of BANNED_PATTERNS) {
+        expect(pattern.test(text), `"${testCase.q}" produced banned wording (${pattern})`).toBe(false)
+      }
+
+      for (const block of turn.plan.blocks) {
+        if (block.kind === "printer-cards") {
+          for (const card of block.printers) {
+            expect(knownIds.has(card.id), `"${testCase.q}" rendered unknown printer ${card.id}`).toBe(true)
+            if (card.score !== undefined) {
+              expect(
+                knownScores.has(Math.round(card.score * 100)),
+                `"${testCase.q}" rendered a similarity score not present in any shard`
+              ).toBe(true)
+            }
+          }
+        }
+      }
+
+      const percentages = [...text.matchAll(/(\d+)% similarity/g)].map(match => Number(match[1]))
+      for (const percent of percentages) {
+        expect(knownScores.has(percent), `"${testCase.q}" stated ${percent}% similarity, not in any shard`).toBe(true)
+      }
+    }
+  })
+
+  it("every suggestion chip re-parses through the normal pipeline without throwing", async () => {
+    for (const testCase of CORPUS.slice(0, 60)) {
+      const turn = await runAssistant(testCase.q, contextFor(testCase.ctx), data)
+      for (const block of turn.plan.blocks) {
+        if (block.kind === "chips") {
+          for (const chip of block.chips) {
+            await expect(runAssistant(chip.query, contextFor(testCase.ctx), data)).resolves.toBeTruthy()
+          }
+        }
+      }
+    }
+  })
+})
+
+describe("honest language for key flows", () => {
+  it("explanations quote the shard verbatim and keep similarity separate from the support grade", async () => {
+    const turn = await runAssistant("why was hp laserjet 4p recommended", LJ4_CONTEXT, data)
+    const text = allText(turn.plan)
+    expect(text).toContain("90% similarity")
+    expect(text).toContain("High confidence")
+    expect(text).toContain("Preferred Linux driver: hplip")
+    expect(text).toContain("Linux support grade is Perfect")
+    expect(text).toContain("not a promise")
+  })
+
+  it("similar-printers responses state that similarity is not a compatibility promise", async () => {
+    const turn = await runAssistant("what printers are similar to this?", LJ4_CONTEXT, data)
+    const text = allText(turn.plan)
+    expect(text).toContain("similarity is not a compatibility promise")
+  })
+
+  it("criteria-free 'best' clarifies and never ranks", async () => {
+    const turn = await runAssistant("what is the best printer?", HOME_CONTEXT, data)
+    expect(turn.execution.kind).toBe("clarify")
+    expect(allText(turn.plan)).toContain("doesn't rank printers overall")
+    expect(turn.plan.blocks.some(block => block.kind === "printer-cards")).toBe(false)
+  })
+
+  it("'better alternatives' asks for the dimension", async () => {
+    const turn = await runAssistant("what are better alternatives?", LJ4_CONTEXT, data)
+    expect(allText(turn.plan)).toContain("Better in what way?")
+  })
+
+  it("duplex answers state the data gap and never fabricate results", async () => {
+    const turn = await runAssistant("find a duplex printer", HOME_CONTEXT, data)
+    const text = allText(turn.plan)
+    expect(text).toContain("doesn't record duplex")
+    expect(text).toContain("13 printers")
+    expect(turn.plan.blocks.some(block => block.kind === "printer-cards")).toBe(false)
+  })
+
+  it("duplex combined with real filters still answers the real part", async () => {
+    const turn = await runAssistant("colour laser printer with duplex", HOME_CONTEXT, data)
+    const text = allText(turn.plan)
+    expect(text).toContain("doesn't record duplex")
+    const cards = turn.plan.blocks.find(block => block.kind === "printer-cards")
+    expect(cards).toBeDefined()
+    if (cards && cards.kind === "printer-cards") {
+      expect(cards.printers.map(card => card.id)).toEqual(["Xerox-Phaser_6100"])
+    }
+  })
+
+  it("unsupported constraints are surfaced, not silently dropped", async () => {
+    const turn = await runAssistant("purple laser printer", HOME_CONTEXT, data)
+    const text = allText(turn.plan)
+    expect(text).toContain('"purple"')
+    expect(text).toContain("doesn't record that")
+  })
+
+  it("out-of-domain questions get a scope statement", async () => {
+    const turn = await runAssistant("what's the weather?", HOME_CONTEXT, data)
+    expect(allText(turn.plan)).toContain("outside my data")
+  })
+
+  it("unknown fields render as 'Not recorded' in comparisons, never as absence", async () => {
+    const turn = await runAssistant("compare hp 2500c and ibm 4019", HOME_CONTEXT, data)
+    expect(turn.execution.kind).toBe("comparison")
+    const comparison = turn.plan.blocks.find(block => block.kind === "comparison")
+    expect(comparison).toBeDefined()
+    if (comparison && comparison.kind === "comparison") {
+      const colourRow = comparison.rows.find(row => row.label === "Colour")
+      expect(colourRow?.b).toBe("Not recorded")
+    }
+    const text = allText(turn.plan)
+    expect(text).not.toMatch(/does not support/i)
+  })
+
+  it("no-match entities are reported with catalogue-backed suggestions", async () => {
+    const turn = await runAssistant("Brother HL-2270DW", HOME_CONTEXT, data)
+    const text = allText(turn.plan)
+    expect(text).toContain("couldn't find a printer matching")
+    const cards = turn.plan.blocks.find(block => block.kind === "printer-cards")
+    if (cards && cards.kind === "printer-cards") {
+      for (const card of cards.printers) {
+        expect(CATALOG.some(printer => printer.id === card.id)).toBe(true)
+      }
+    }
+  })
+})
+
+describe("synthetic diagnostics rendering", () => {
+  it("reports materially unknown-excluded populations", () => {
+    const execution: Execution = {
+      kind: "search-results",
+      state: "SUCCESS",
+      recommend: false,
+      matches: CATALOG.slice(0, 2),
+      total: 2,
+      diagnostics: {
+        filters: [{ label: "colour", matched: 2, excludedKnown: 2, excludedUnknown: 4 }],
+        unapplied: [],
+        insufficient: [],
+        relaxations: [],
+        orderingLabel: "Linux support status, then number of listed drivers",
+        catalogSize: 8,
+      },
+    }
+    const text = allText(buildResponse(execution))
+    expect(text).toContain("4 more printers don't record")
+    expect(text).toContain("missing data")
+  })
+
+  it("renders relaxation chips with counts", () => {
+    const execution: Execution = {
+      kind: "search-results",
+      state: "NO_MATCHES",
+      recommend: false,
+      matches: [],
+      total: 0,
+      diagnostics: {
+        filters: [
+          { label: "colour", matched: 0, excludedKnown: 5, excludedUnknown: 0 },
+          { label: "at least 2400 dpi", matched: 0, excludedKnown: 5, excludedUnknown: 0 },
+        ],
+        unapplied: [],
+        insufficient: [],
+        relaxations: [{ droppedLabel: "at least 2400 dpi", resultCount: 6, query: "find colour printers" }],
+        orderingLabel: null,
+        catalogSize: 13,
+      },
+    }
+    const plan = buildResponse(execution)
+    const chips = plan.blocks.find(block => block.kind === "chips")
+    expect(chips).toBeDefined()
+    if (chips && chips.kind === "chips") {
+      expect(chips.chips[0].label).toContain("6 printers")
+    }
+  })
+})
+
+describe("suggestion integrity: every chip is an answerable, honest promise", () => {
+  it("the grades suggestion submits its own text and answers generally, never from the current printer", async () => {
+    // The exact reported-bug path: SUPPORT_QUERY response on a printer page
+    // offers a grades chip; clicking it must ask the general question and the
+    // answer must not mention the current printer or inject its grade.
+    const supportTurn = await runAssistant("how good is the linux support", LJ4_CONTEXT, data)
+    expect(supportTurn.execution.kind).toBe("support")
+    const chipsBlock = supportTurn.plan.blocks.find(block => block.kind === "chips")
+    expect(chipsBlock).toBeDefined()
+    if (!chipsBlock || chipsBlock.kind !== "chips") return
+    const gradesChip = chipsBlock.chips.find(chip => chip.label.toLowerCase().includes("grades"))
+    expect(gradesChip).toBeDefined()
+    if (!gradesChip) return
+    // The submitted message is exactly the suggestion text (modulo case and
+    // punctuation) - never a rewrite using current-page data.
+    expect(gradesChip.query.toLowerCase().replace(/[^a-z0-9 ]/g, "")).toBe(
+      gradesChip.label.toLowerCase().replace(/[^a-z0-9 ]/g, "")
+    )
+    const answer = await runAssistant(gradesChip.query, LJ4_CONTEXT, data)
+    expect(answer.execution.kind).toBe("info")
+    if (answer.execution.kind === "info") {
+      expect(answer.execution.topic).toBe("support-grades")
+    }
+    const answerText = allText(answer.plan)
+    expect(answerText).not.toContain("LaserJet 4")
+  })
+
+  it("meaning-questions with grade vocabulary answer generally on a printer page", async () => {
+    for (const q of ["what do the grades mean", "what does perfect support mean", "what does this printer's support grade mean"]) {
+      const turn = await runAssistant(q, LJ4_CONTEXT, data)
+      expect(turn.execution.kind, q).toBe("info")
+      expect(allText(turn.plan), q).not.toContain("LaserJet 4")
+    }
+  })
+
+  it("questions that DO reference this printer still resolve through context", async () => {
+    const turn = await runAssistant("what is the support status of this printer", LJ4_CONTEXT, data)
+    expect(turn.execution.kind).toBe("support")
+    expect(allText(turn.plan)).toContain("HP LaserJet 4")
+  })
+
+  it("'this driver' resolves through page context without injecting the driver id into the query", async () => {
+    const driverContext: AssistantPageContext = {
+      pageType: "driver",
+      route: "/foomatic/driver/hplip",
+      driverId: "hplip",
+    }
+    const turn = await runAssistant("which printers use this driver", driverContext, data)
+    expect(turn.execution.kind).toBe("driver-search")
+    if (turn.execution.kind === "driver-search") {
+      expect(turn.execution.driver.id).toBe("hplip")
+    }
+    // Without driver-page context the same question clarifies, never guesses.
+    const homeTurn = await runAssistant("which printers use this driver", HOME_CONTEXT, data)
+    expect(homeTurn.execution.kind).toBe("clarify")
+  })
+
+  it("every chip the system can produce parses to a supported, answerable query", async () => {
+    const contexts: AssistantPageContext[] = [
+      HOME_CONTEXT,
+      LJ4_CONTEXT,
+      { pageType: "driver", route: "/foomatic/driver/hplip", driverId: "hplip" },
+    ]
+    const seeds = [
+      "how good is the linux support",
+      "what printers are similar to this?",
+      "tell me about hp 2500c",
+      "what is the best printer?",
+      "what are better alternatives?",
+      "why was this recommended?",
+      "brother hl 2270dw",
+      "hp deskjet 5",
+      "colour dot matrix printers with perfect linux support and 2400 dpi",
+      "what can you do",
+    ]
+    for (const context of contexts) {
+      for (const chip of contextSuggestions(context)) {
+        const turn = await runAssistant(chip.query, context, data)
+        expect(turn.execution.kind, `${context.pageType}: "${chip.label}"`).not.toBe("unsupported")
+      }
+      for (const seed of seeds) {
+        const turn = await runAssistant(seed, context, data)
+        for (const block of turn.plan.blocks) {
+          if (block.kind !== "chips") continue
+          for (const chip of block.chips) {
+            const followUp = await runAssistant(chip.query, context, data)
+            expect(
+              followUp.execution.kind,
+              `${context.pageType}: "${seed}" -> chip "${chip.label}" (${chip.query})`
+            ).not.toBe("unsupported")
+            expect(followUp.execution.state).not.toBe("ERROR")
+          }
+        }
+      }
+    }
+  })
+})
+
+describe("error handling", () => {
+  it("wraps data failures into a retryable error response", async () => {
+    const failing = {
+      ...fixtureData(),
+      getCatalog: async () => {
+        throw new Error("network down")
+      },
+    }
+    const turn = await runAssistant("find a colour laser printer", HOME_CONTEXT, failing)
+    expect(turn.execution.kind).toBe("error")
+    const chips = turn.plan.blocks.find(block => block.kind === "chips")
+    expect(chips && chips.kind === "chips" && chips.chips[0].label).toBe("Try again")
+  })
+})
diff --git a/lib/assistant/constants.ts b/lib/assistant/constants.ts
new file mode 100644
index 00000000..94eacb79
--- /dev/null
+++ b/lib/assistant/constants.ts
@@ -0,0 +1,41 @@
+// Named tunables for the assistant. Every value here is documented in the
+// table in docs/foomatic-assistant.md, and tools/assistant-eval/run.ts fails
+// when the documented values drift from these (same convention as
+// tools/eval/check-docs.mjs for the recommendation pipeline).
+
+// Queries longer than this are truncated before parsing; no realistic printer
+// question needs more, and it bounds parser work on hostile input.
+export const MAX_QUERY_LENGTH = 300
+
+// Entity resolution: candidate scores. Exact id / exact "make model" name
+// matches resolve immediately; an exact model match resolves only when unique.
+export const SCORE_EXACT = 4
+export const SCORE_MODEL_EXACT = 3
+export const SCORE_MODEL_PREFIX = 1
+
+// A span resolves silently only at or above this score AND with a unique top
+// candidate; everything else surfaces as an ambiguity with candidates.
+export const RESOLVE_MIN_SCORE = 3
+
+// Leftover text longer than this (fused) is not treated as a near-miss model
+// number - real model names are short, and phrases like "100 percent
+// compatibility" must not be mistaken for one.
+export const NEAR_MISS_MAX_LENGTH = 20
+
+// How many candidates an ambiguity/clarification response carries.
+export const MAX_CANDIDATES = 5
+
+// How many result cards a search response renders (total count is stated).
+export const MAX_RESULT_CARDS = 5
+
+// "high resolution" is interpreted as at least this many dpi; the response
+// discloses the interpretation.
+export const HIGH_RES_MIN_DPI = 1200
+
+// When a filter excludes at least this fraction of the pre-filter candidates
+// because the field is unrecorded, the response must say so.
+export const UNKNOWN_REPORT_RATIO = 0.25
+
+// When a search yields fewer results than this, one-filter relaxations are
+// offered (never auto-applied).
+export const MIN_COMFORTABLE_RESULTS = 3
diff --git a/lib/assistant/context.ts b/lib/assistant/context.ts
new file mode 100644
index 00000000..3573efc2
--- /dev/null
+++ b/lib/assistant/context.ts
@@ -0,0 +1,41 @@
+// Route -> typed page context. This module is the only place the assistant
+// inspects URL strings; everything downstream consumes AssistantPageContext.
+// The parsing inverts printerHref()/driverHref() from lib/foomatic/routes.ts
+// and is round-trip tested against them, so context stays correct if the
+// canonical URL builders ever change shape (the test will fail loudly).
+
+import type { AssistantPageContext } from "./types"
+
+export function parsePageContext(pathname: string): AssistantPageContext {
+  const route = pathname || "/"
+  const segments = route.split("/").map(decodeSegment).filter(Boolean)
+
+  if (segments.length === 0) {
+    return { pageType: "home", route }
+  }
+
+  if (segments[0] === "foomatic") {
+    if (segments[1] === "printer" && segments.length === 4) {
+      return { pageType: "printer", route, printerId: segments[3] }
+    }
+    if (segments[1] === "driver" && segments.length === 3) {
+      return { pageType: "driver", route, driverId: segments[2] }
+    }
+    if (segments[1] === "printers" && segments.length === 2) {
+      return { pageType: "printer-directory", route }
+    }
+    if (segments[1] === "drivers" && segments.length === 2) {
+      return { pageType: "driver-directory", route }
+    }
+  }
+
+  return { pageType: "other", route }
+}
+
+function decodeSegment(segment: string): string {
+  try {
+    return decodeURIComponent(segment)
+  } catch {
+    return segment
+  }
+}
diff --git a/lib/assistant/data.ts b/lib/assistant/data.ts
new file mode 100644
index 00000000..f4c4779c
--- /dev/null
+++ b/lib/assistant/data.ts
@@ -0,0 +1,72 @@
+// Browser data source for the assistant. Every artifact is a static JSON file
+// under public/, fetched via withBasePath() and cached per tab with the same
+// promise-cache pattern as RecommendedPrintersSection.tsx: concurrent callers
+// share one request, a 404 resolves to the empty value (missing shards are
+// "no data", not an error - PR CI builds skip the similarity stage entirely),
+// and a network failure clears the cache entry so the next call retries
+// instead of reusing a rejected promise forever.
+//
+// Sizes (measured, gzip over the wire): catalogue ~70 KB once per tab,
+// driversMap ~5.5 KB once per tab, printer shards 0.8-10 KB and
+// recommendation shards ~0.5 KB per printer asked about.
+
+import { withBasePath } from "@/lib/foomatic/base-path"
+import type { DriverRecord, DriverSummary, Printer, PrinterSummary } from "@/lib/foomatic/types"
+import type { AssistantData, RecommendationEntry } from "./types"
+
+const cache = new Map<string, Promise<unknown>>()
+
+function cachedFetch<T>(path: string, onMissing: () => T): Promise<T> {
+  let entry = cache.get(path) as Promise<T> | undefined
+  if (!entry) {
+    entry = fetch(withBasePath(path))
+      .then(response => {
+        if (response.status === 404) return onMissing()
+        if (!response.ok) throw new Error(`Failed to load ${path}: ${response.status}`)
+        return response.json() as Promise<T>
+      })
+      .catch(error => {
+        cache.delete(path)
+        throw error
+      })
+    cache.set(path, entry)
+  }
+  return entry
+}
+
+export function createBrowserData(): AssistantData {
+  return {
+    async getCatalog() {
+      const payload = await cachedFetch<{ printers: PrinterSummary[] }>(
+        "/foomatic-db/printersMap.json",
+        () => ({ printers: [] })
+      )
+      return payload.printers
+    },
+    getPrinter(id: string) {
+      return cachedFetch<Printer | null>(
+        `/foomatic-db/printers/${encodeURIComponent(id)}.json`,
+        () => null
+      )
+    },
+    getRecommendations(id: string) {
+      return cachedFetch<RecommendationEntry[]>(
+        `/foomatic-db/recommendations/${encodeURIComponent(id)}.json`,
+        () => []
+      )
+    },
+    async getDriversMap() {
+      const payload = await cachedFetch<{ drivers: DriverSummary[] }>(
+        "/foomatic-db/driversMap.json",
+        () => ({ drivers: [] })
+      )
+      return payload.drivers
+    },
+    getDriver(id: string) {
+      return cachedFetch<DriverRecord | null>(
+        `/foomatic-db/drivers/${encodeURIComponent(id)}.json`,
+        () => null
+      )
+    },
+  }
+}
diff --git a/lib/assistant/engine.ts b/lib/assistant/engine.ts
new file mode 100644
index 00000000..df3052ed
--- /dev/null
+++ b/lib/assistant/engine.ts
@@ -0,0 +1,58 @@
+// Orchestrates one assistant turn: text + page context -> ResponsePlan.
+// Pure composition of the pipeline stages; the UI, the tests, and the eval
+// harness all call this same function with different AssistantData sources,
+// so what is tested is exactly what ships.
+
+import { buildDriverIndex, buildPrinterIndex, type DriverIndex, type PrinterIndex } from "./entities"
+import { executeQuery } from "./execute"
+import { parseQuery } from "./parse"
+import { buildResponse } from "./respond"
+import type { AssistantData, AssistantPageContext, AssistantQuery, Execution, ResponsePlan } from "./types"
+
+export interface AssistantTurn {
+  query: AssistantQuery
+  execution: Execution
+  plan: ResponsePlan
+}
+
+interface IndexCacheEntry {
+  printers: PrinterIndex
+  drivers: DriverIndex
+}
+
+// Indexes are derived from the catalogue/driversMap once per data source
+// (i.e. once per tab in the browser) and reused across turns.
+const indexCache = new WeakMap<AssistantData, Promise<IndexCacheEntry>>()
+
+async function getIndexes(data: AssistantData): Promise<IndexCacheEntry> {
+  let cached = indexCache.get(data)
+  if (!cached) {
+    cached = Promise.all([data.getCatalog(), data.getDriversMap()]).then(([catalog, drivers]) => ({
+      printers: buildPrinterIndex(catalog),
+      drivers: buildDriverIndex(drivers),
+    }))
+    indexCache.set(data, cached)
+  }
+  return cached
+}
+
+export async function runAssistant(
+  input: string,
+  context: AssistantPageContext,
+  data: AssistantData
+): Promise<AssistantTurn> {
+  // Any data failure (including the initial catalogue load) becomes a
+  // retryable error response; the failed index promise is evicted so the
+  // retry actually refetches instead of replaying a rejected promise.
+  let query: AssistantQuery = { intent: "UNSUPPORTED", reason: "empty" }
+  let execution: Execution
+  try {
+    const indexes = await getIndexes(data)
+    query = parseQuery(input, context, indexes)
+    execution = await executeQuery(query, context, data)
+  } catch {
+    indexCache.delete(data)
+    execution = { kind: "error", state: "ERROR", retryQuery: input }
+  }
+  return { query, execution, plan: buildResponse(execution) }
+}
diff --git a/lib/assistant/entities.ts b/lib/assistant/entities.ts
new file mode 100644
index 00000000..33dcbf58
--- /dev/null
+++ b/lib/assistant/entities.ts
@@ -0,0 +1,429 @@
+// Deterministic printer/driver entity resolution over the real catalogue.
+//
+// Strategy (layered, most exact first):
+//   L1 normalization/fusing happens in normalize.ts ("HL-1050" == "hl 1050").
+//   L2 manufacturer aliases map alternate make names onto catalogue makes.
+//   L3 exact lookups: printer id, fused "make model" name, fused model
+//      (model-only matches resolve only when unique across makes).
+//   L4 prefix scan for partial names ("hp laserjet" -> the LaserJet family).
+//   L5 thresholding: only exact-class unique matches resolve silently;
+//      everything else surfaces as an ambiguity with ranked candidates.
+// Ties are broken by id, mirroring scoreThenIdComparator's convention.
+//
+// The resolver never invents entities: every candidate id comes from the
+// loaded catalogue, and a miss produces an unresolved ref with near-miss
+// suggestions (e.g. "Brother HL-2270DW", which is not in the dataset).
+
+import type { DriverSummary, PrinterSummary } from "@/lib/foomatic/types"
+import { normalizeDriverFamily } from "@/lib/foomatic/driver-family"
+import { MAX_CANDIDATES, NEAR_MISS_MAX_LENGTH, RESOLVE_MIN_SCORE, SCORE_EXACT, SCORE_MODEL_EXACT, SCORE_MODEL_PREFIX } from "./constants"
+import { fuseText } from "./normalize"
+import type { DriverRef, PrinterCandidate, PrinterRef } from "./types"
+
+// Alternate manufacturer names seen in real queries. Canonical names on the
+// right must exist in the catalogue; the artifact test enforces that.
+export const MANUFACTURER_ALIASES: Record<string, string> = {
+  hewlettpackard: "HP",
+  hewlitpackard: "HP",
+  hplaserjet: "HP", // "HP LaserJet" queries lead with this fused prefix
+}
+
+// Tokens that are capability/query vocabulary, never part of an entity name.
+// Without this, "laser" would prefix-match every LaserJet model.
+const EXCLUDED_ENTITY_TOKENS = new Set([
+  "printer", "printers", "driver", "drivers", "laser", "inkjet", "ink", "jet",
+  "dot", "matrix", "impact", "colour", "color", "coloured", "colored", "mono",
+  "monochrome", "black", "white", "duplex", "sided", "postscript", "post",
+  "script", "pcl", "pclxl", "pcl5", "pcl5e", "pcl6", "ps2", "ps3",
+  "dpi", "resolution", "res", "linux", "support",
+  "supported", "supports", "supporting", "similar", "like", "alternative",
+  "alternatives", "recommend", "recommended", "recommendation", "recommendations",
+  "compare", "comparison", "versus", "vs", "best", "better", "good", "great",
+  "find", "show", "search", "list", "need", "want", "works", "work", "well",
+  "use", "uses", "using", "the", "a", "an", "with", "and", "for", "this", "that",
+  "what", "which", "why", "how", "does", "do", "is", "are", "to", "me", "my", "i",
+  "one", "same", "high", "level",
+])
+
+interface IndexedPrinter {
+  id: string
+  manufacturer: string
+  model: string
+  fName: string
+  fModel: string
+}
+
+export interface PrinterIndex {
+  byId: Map<string, IndexedPrinter>
+  byFusedId: Map<string, string[]>
+  byFusedName: Map<string, string[]>
+  byFusedModel: Map<string, string[]>
+  // Sorted for binary-search prefix scans.
+  nameList: { key: string; id: string }[]
+  modelList: { key: string; id: string }[]
+  makesByFused: Map<string, string>
+}
+
+function push(map: Map<string, string[]>, key: string, id: string) {
+  if (!key) return
+  const existing = map.get(key)
+  if (existing) {
+    if (!existing.includes(id)) existing.push(id)
+  } else {
+    map.set(key, [id])
+  }
+}
+
+export function buildPrinterIndex(catalog: PrinterSummary[]): PrinterIndex {
+  const index: PrinterIndex = {
+    byId: new Map(),
+    byFusedId: new Map(),
+    byFusedName: new Map(),
+    byFusedModel: new Map(),
+    nameList: [],
+    modelList: [],
+    makesByFused: new Map(),
+  }
+
+  // The catalogue contains casing variants of the same make ("Epson" and
+  // "EPSON"): the canonical spelling is the most frequent one, ties broken
+  // deterministically. Filtering compares fused names, so records under any
+  // variant still match.
+  const makeCounts = new Map<string, Map<string, number>>()
+  for (const printer of catalog) {
+    const fused = fuseText(printer.manufacturer)
+    const variants = makeCounts.get(fused) ?? new Map<string, number>()
+    variants.set(printer.manufacturer, (variants.get(printer.manufacturer) ?? 0) + 1)
+    makeCounts.set(fused, variants)
+  }
+  for (const [fused, variants] of makeCounts) {
+    const canonical = [...variants.entries()].sort(
+      (a, b) => b[1] - a[1] || a[0].localeCompare(b[0])
+    )[0][0]
+    index.makesByFused.set(fused, canonical)
+  }
+
+  for (const printer of catalog) {
+    const entry: IndexedPrinter = {
+      id: printer.id,
+      manufacturer: printer.manufacturer,
+      model: printer.model,
+      fName: fuseText(`${printer.manufacturer} ${printer.model}`),
+      fModel: fuseText(printer.model),
+    }
+    index.byId.set(printer.id, entry)
+    push(index.byFusedId, fuseText(printer.id), printer.id)
+    push(index.byFusedName, entry.fName, printer.id)
+    push(index.byFusedModel, entry.fModel, printer.id)
+    index.nameList.push({ key: entry.fName, id: printer.id })
+    index.modelList.push({ key: entry.fModel, id: printer.id })
+  }
+
+  for (const [alias, make] of Object.entries(MANUFACTURER_ALIASES)) {
+    if (index.makesByFused.has(fuseText(make))) {
+      index.makesByFused.set(alias, make)
+    }
+  }
+
+  const byKey = (a: { key: string; id: string }, b: { key: string; id: string }) =>
+    a.key.localeCompare(b.key) || a.id.localeCompare(b.id)
+  index.nameList.sort(byKey)
+  index.modelList.sort(byKey)
+
+  return index
+}
+
+function prefixScan(list: { key: string; id: string }[], prefix: string, cap: number): string[] {
+  if (prefix.length < 3) return []
+  let low = 0
+  let high = list.length
+  while (low < high) {
+    const mid = (low + high) >> 1
+    if (list[mid].key < prefix) low = mid + 1
+    else high = mid
+  }
+  const ids: string[] = []
+  for (let i = low; i < list.length && list[i].key.startsWith(prefix); i++) {
+    if (!ids.includes(list[i].id)) ids.push(list[i].id)
+    if (ids.length > cap) break
+  }
+  return ids
+}
+
+interface Span {
+  start: number
+  end: number // exclusive
+  score: number
+  ids: string[]
+  total: number
+}
+
+function toCandidates(index: PrinterIndex, ids: string[], score: number): PrinterCandidate[] {
+  return ids
+    .slice()
+    .sort((a, b) => a.localeCompare(b))
+    .slice(0, MAX_CANDIDATES)
+    .map(id => {
+      const entry = index.byId.get(id)
+      return {
+        id,
+        manufacturer: entry?.manufacturer ?? "",
+        model: entry?.model ?? "",
+        score,
+      }
+    })
+}
+
+export interface PrinterResolution {
+  refs: PrinterRef[]
+  makeOnly: string | null
+  consumed: Set<number>
+}
+
+// Scans the token stream for printer references. Marks consumed tokens so the
+// lexicon and unapplied-constraint detection only see what is left over.
+export function resolvePrintersInText(tokens: string[], index: PrinterIndex): PrinterResolution {
+  const consumed = new Set<number>()
+  const spans: Span[] = []
+
+  const windowFused = (start: number, end: number) => fuseText(tokens.slice(start, end).join(""))
+  // A usable entity window needs at least one token that is neither query
+  // vocabulary nor a bare number: "pcl 6" and "600" are capability phrases,
+  // not model names.
+  const windowUsable = (start: number, end: number) =>
+    tokens.slice(start, end).some(token => !EXCLUDED_ENTITY_TOKENS.has(token) && !/^\d+$/.test(token))
+
+  for (let size = Math.min(5, tokens.length); size >= 1; size--) {
+    for (let start = 0; start + size <= tokens.length; start++) {
+      const end = start + size
+      if (!windowUsable(start, end)) continue
+      const fused = windowFused(start, end)
+      if (fused.length < 2) continue
+
+      const exact = index.byFusedId.get(fused) ?? index.byFusedName.get(fused)
+      if (exact) {
+        spans.push({ start, end, score: SCORE_EXACT, ids: exact, total: exact.length })
+        continue
+      }
+
+      const modelExact = index.byFusedModel.get(fused)
+      if (modelExact) {
+        spans.push({ start, end, score: SCORE_MODEL_EXACT, ids: modelExact, total: modelExact.length })
+        continue
+      }
+
+      // Prefix matches only for windows that plausibly start a name: either
+      // beginning with a make/alias, containing a digit (model numbers), or
+      // long enough to be a family name ("laserjet", "stylus").
+      const startsWithMake = [...index.makesByFused.keys()].some(
+        make => fused.startsWith(make) && fused.length > make.length
+      )
+      // A bare make name is not a model prefix - the makeOnly handling below
+      // covers "show me Canon printers".
+      if (startsWithMake || /\d/.test(fused) || (fused.length >= 5 && !index.makesByFused.has(fused))) {
+        const nameHits = prefixScan(index.nameList, fused, 200)
+        const modelHits = prefixScan(index.modelList, fused, 200)
+        const ids = [...new Set([...nameHits, ...modelHits])]
+        if (ids.length > 0) {
+          spans.push({ start, end, score: SCORE_MODEL_PREFIX, ids, total: ids.length })
+        }
+      }
+    }
+  }
+
+  // A span directly followed by a model-number token failed to cover the
+  // full name the user typed: "hp deskjet" out of "hp deskjet 5" (the literal
+  // HP-DeskJet record must not swallow the 5), or "brother hl" out of
+  // "brother hl 2270dw". Skipping it during selection lets a longer prefix
+  // span - or the near-miss handling in parse.ts - answer honestly.
+  // Exception: "<model> 600 dpi", where the number belongs to a resolution
+  // constraint, not the name.
+  const truncatesModelNumber = (span: Span) => {
+    const next = span.end < tokens.length ? tokens[span.end] : null
+    return (
+      next !== null &&
+      !EXCLUDED_ENTITY_TOKENS.has(next) &&
+      /\d/.test(next) &&
+      tokens[span.end + 1] !== "dpi"
+    )
+  }
+
+  // Greedy selection: strongest, then longest, then leftmost; non-overlapping.
+  spans.sort((a, b) => b.score - a.score || (b.end - b.start) - (a.end - a.start) || a.start - b.start)
+  const chosen: Span[] = []
+  for (const span of spans) {
+    if (chosen.length >= 2) break
+    if (truncatesModelNumber(span)) continue
+    if (chosen.some(other => span.start < other.end && other.start < span.end)) continue
+    // A weaker span of the same text adds nothing next to a stronger one.
+    chosen.push(span)
+  }
+  chosen.sort((a, b) => a.start - b.start)
+
+  const refs: PrinterRef[] = []
+  for (const span of chosen) {
+    for (let i = span.start; i < span.end; i++) consumed.add(i)
+    const text = tokens.slice(span.start, span.end).join(" ")
+    if (span.ids.length === 1 && span.score >= RESOLVE_MIN_SCORE) {
+      refs.push({ kind: "resolved", id: span.ids[0] })
+    } else {
+      refs.push({
+        kind: "ambiguous",
+        text,
+        candidates: toCandidates(index, span.ids, span.score),
+        total: span.total,
+      })
+    }
+  }
+
+  // Standalone make mention ("show me Canon printers") -> manufacturer filter.
+  let makeOnly: string | null = null
+  if (refs.length === 0) {
+    for (let size = 2; size >= 1; size--) {
+      for (let start = 0; start + size <= tokens.length; start++) {
+        if (tokens.slice(start, start + size).some((_, j) => consumed.has(start + j))) continue
+        const make = index.makesByFused.get(windowFused(start, start + size))
+        if (make) {
+          makeOnly = make
+          for (let i = start; i < start + size; i++) consumed.add(i)
+          break
+        }
+      }
+      if (makeOnly) break
+    }
+  }
+
+  return { refs, makeOnly, consumed }
+}
+
+// Builds an unresolved near-miss reference from leftover model-looking tokens
+// ("brother hl 2270dw" when no such model exists). Called by parse.ts AFTER
+// the capability lexicon has consumed its tokens, so capability terms like
+// "pcl5e" or "600 dpi" can never be misread as model numbers. Suggestions are
+// real catalogue entries: model-prefix matches first, then same-make models.
+export function findNearMissPrinter(
+  tokens: string[],
+  consumed: Set<number>,
+  index: PrinterIndex,
+  make: string | null,
+  skipToken: (token: string) => boolean
+): { ref: PrinterRef; used: number[] } | null {
+  const leftover: number[] = []
+  for (let i = 0; i < tokens.length; i++) {
+    if (!consumed.has(i) && !EXCLUDED_ENTITY_TOKENS.has(tokens[i]) && !skipToken(tokens[i])) {
+      leftover.push(i)
+    }
+  }
+  if (leftover.length === 0) return null
+  const text = leftover.map(i => tokens[i]).join(" ")
+  const fused = fuseText(text)
+  const modelish =
+    fused.length >= 3 &&
+    fused.length <= NEAR_MISS_MAX_LENGTH &&
+    /\d/.test(fused) &&
+    (/[a-z]/.test(fused) || make !== null)
+  if (!modelish) return null
+
+  const suggestionIds = [
+    ...new Set([
+      ...prefixScan(index.modelList, fused.slice(0, 4), 50),
+      ...prefixScan(index.modelList, fused.slice(0, 3), 50),
+    ]),
+  ]
+  const withinMake = make
+    ? suggestionIds.filter(id => index.byId.get(id)?.manufacturer === make)
+    : suggestionIds
+  let pool = withinMake.length > 0 ? withinMake : suggestionIds
+  if (pool.length === 0 && make) {
+    // Fall back to the mentioned manufacturer's own models.
+    pool = [...index.byId.values()]
+      .filter(entry => entry.manufacturer === make)
+      .map(entry => entry.id)
+      .sort((a, b) => a.localeCompare(b))
+      .slice(0, 3)
+  }
+  return {
+    ref: {
+      kind: "unresolved",
+      text: make ? `${make} ${text}` : text,
+      suggestions: toCandidates(index, pool, SCORE_MODEL_PREFIX).slice(0, 3),
+    },
+    used: leftover,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Drivers
+
+export interface DriverIndex {
+  byFused: Map<string, string>
+  families: Map<string, string[]>
+  ids: string[]
+}
+
+export function buildDriverIndex(drivers: DriverSummary[]): DriverIndex {
+  const index: DriverIndex = { byFused: new Map(), families: new Map(), ids: [] }
+  for (const driver of drivers) {
+    index.ids.push(driver.id)
+    index.byFused.set(fuseText(driver.id), driver.id)
+    index.byFused.set(fuseText(driver.name), driver.id)
+    const family = normalizeDriverFamily(driver.id)
+    const members = index.families.get(family)
+    if (members) members.push(driver.id)
+    else index.families.set(family, [driver.id])
+  }
+  index.ids.sort((a, b) => a.localeCompare(b))
+  for (const members of index.families.values()) members.sort((a, b) => a.localeCompare(b))
+  return index
+}
+
+// Resolves a driver mention in the token stream. `required` is set when the
+// intent clearly asks about a driver, so a miss should produce an unresolved
+// ref with suggestions rather than silence.
+export function resolveDriverInText(
+  tokens: string[],
+  consumed: Set<number>,
+  index: DriverIndex,
+  required: boolean
+): DriverRef | null {
+  for (let size = 2; size >= 1; size--) {
+    for (let start = 0; start + size <= tokens.length; start++) {
+      const slice = tokens.slice(start, start + size)
+      if (slice.some((_, j) => consumed.has(start + j))) continue
+      if (slice.every(token => EXCLUDED_ENTITY_TOKENS.has(token))) continue
+      const fused = fuseText(slice.join(""))
+      if (fused.length < 3) continue
+
+      const exact = index.byFused.get(fused)
+      if (exact) {
+        for (let i = start; i < start + size; i++) consumed.add(i)
+        return { kind: "resolved", id: exact }
+      }
+
+      // A family name is never silently expanded to its members: the caller
+      // must ask the user which member driver they mean.
+      const family = index.families.get(fused)
+      if (family && family.length > 0) {
+        for (let i = start; i < start + size; i++) consumed.add(i)
+        if (family.length === 1) return { kind: "resolved", id: family[0] }
+        return { kind: "family", family: fused, members: family.slice(0, MAX_CANDIDATES) }
+      }
+    }
+  }
+
+  if (!required) return null
+
+  // The intent needs a driver but nothing matched: suggest near names.
+  for (let start = 0; start < tokens.length; start++) {
+    if (consumed.has(start) || EXCLUDED_ENTITY_TOKENS.has(tokens[start])) continue
+    const fused = fuseText(tokens[start])
+    if (fused.length < 3) continue
+    const suggestions = index.ids
+      .filter(id => fuseText(id).startsWith(fused.slice(0, 2)))
+      .slice(0, MAX_CANDIDATES)
+    consumed.add(start)
+    return { kind: "unresolved", text: tokens[start], suggestions }
+  }
+
+  return null
+}
diff --git a/lib/assistant/execute.ts b/lib/assistant/execute.ts
new file mode 100644
index 00000000..a585f935
--- /dev/null
+++ b/lib/assistant/execute.ts
@@ -0,0 +1,691 @@
+// Executes a typed AssistantQuery against the local Foomatic artifacts.
+// This is the only assistant layer that performs I/O, always through the
+// injected AssistantData source (browser fetches in production, in-memory
+// fixtures in tests, fs reads in the eval harness).
+//
+// Semantics enforced here:
+// - Unknown never means false: filters select on known values only, and every
+//   filter reports how many printers it excluded because the field is simply
+//   not recorded.
+// - Similarity answers come from the PR #224 recommendation shards verbatim:
+//   shard order is preserved, entries are only ever subset-filtered, and no
+//   score is recomputed or reinterpreted.
+// - "best"/"recommend" without criteria clarifies instead of ranking, and
+//   "better" without a dimension clarifies instead of assuming one.
+
+import type { PrinterSummary } from "@/lib/foomatic/types"
+import { normalizeDriverId } from "@/lib/foomatic/routes"
+import { fuseText } from "./normalize"
+import { MIN_COMFORTABLE_RESULTS } from "./constants"
+import type {
+  AssistantData,
+  AssistantPageContext,
+  AssistantQuery,
+  BetterDimension,
+  CapabilityFilters,
+  Chip,
+  DriverRef,
+  Execution,
+  FilterDiagnostics,
+  PrinterRef,
+  Relaxation,
+  SearchDiagnostics,
+} from "./types"
+
+export const STATUS_RANK: Record<string, number> = {
+  Perfect: 3,
+  Mostly: 2,
+  Unsupported: 1,
+  Unknown: 0,
+}
+
+export function printerName(p: { manufacturer?: string; model?: string; id: string }): string {
+  const name = `${p.manufacturer ?? ""} ${p.model ?? ""}`.trim()
+  return name || p.id
+}
+
+// ---------------------------------------------------------------------------
+// Filter specs: each maps one CapabilityFilters field onto catalogue fields
+// with explicit known/pass predicates so unknown counts stay distinguishable.
+
+interface FilterSpec {
+  label: string
+  known: (p: PrinterSummary) => boolean
+  pass: (p: PrinterSummary) => boolean
+}
+
+function buildSpecs(filters: CapabilityFilters): FilterSpec[] {
+  const specs: FilterSpec[] = []
+
+  if (filters.manufacturer !== undefined) {
+    const make = fuseText(filters.manufacturer)
+    // Fused comparison so casing variants of the same make ("Epson"/"EPSON")
+    // all match the canonical filter value.
+    specs.push({ label: filters.manufacturer, known: () => true, pass: p => fuseText(p.manufacturer) === make })
+  }
+  if (filters.type !== undefined) {
+    const type = filters.type
+    specs.push({
+      label: type === "dot-matrix" ? "dot-matrix" : type,
+      known: p => p.type !== "unknown" && p.type !== undefined,
+      pass: p => p.type === type,
+    })
+  }
+  if (filters.color !== undefined) {
+    const want = filters.color
+    specs.push({
+      label: want ? "colour" : "monochrome",
+      known: p => p.color === true || p.color === false,
+      pass: p => p.color === want,
+    })
+  }
+  if (filters.minDpi !== undefined) {
+    const min = filters.minDpi
+    specs.push({
+      label: `at least ${min} dpi`,
+      known: p => typeof p.maxDpi === "number",
+      pass: p => typeof p.maxDpi === "number" && p.maxDpi >= min,
+    })
+  }
+  if (filters.postscript !== undefined) {
+    const min = filters.postscript.minLevel
+    if (min !== undefined) {
+      specs.push({
+        label: `PostScript ${min}`,
+        known: p => typeof p.psLevel === "number",
+        pass: p => typeof p.psLevel === "number" && p.psLevel >= min,
+      })
+    } else {
+      // Positive evidence only: a printer without a recorded PS level or
+      // POSTSCRIPT token is unknown, not "no PostScript".
+      const evidenced = (p: PrinterSummary) =>
+        typeof p.psLevel === "number" || (p.cs ?? []).includes("POSTSCRIPT")
+      specs.push({ label: "PostScript", known: evidenced, pass: evidenced })
+    }
+  }
+  if (filters.pcl !== undefined) {
+    const min = filters.pcl.minLevel
+    const tokenFor = min === 6 ? "PCLXL" : min === 5 ? "PCL5E" : null
+    if (min !== undefined) {
+      specs.push({
+        label: `PCL ${min}`,
+        known: p =>
+          typeof p.pclLevel === "number" || (tokenFor !== null && (p.cs ?? []).includes(tokenFor)),
+        pass: p =>
+          (typeof p.pclLevel === "number" && p.pclLevel >= min) ||
+          (tokenFor !== null && (p.cs ?? []).includes(tokenFor)),
+      })
+    } else {
+      const evidenced = (p: PrinterSummary) =>
+        typeof p.pclLevel === "number" ||
+        (p.cs ?? []).some(token => token === "PCL" || token === "PCL5E" || token === "PCLXL")
+      specs.push({ label: "PCL", known: evidenced, pass: evidenced })
+    }
+  }
+  if (filters.support !== undefined) {
+    const want = filters.support
+    specs.push({
+      label: want === "perfect" ? "Perfect Linux support" : "good Linux support (Perfect or Mostly)",
+      known: p => p.status !== "Unknown" && p.status !== undefined,
+      pass: p => (want === "perfect" ? p.status === "Perfect" : p.status === "Perfect" || p.status === "Mostly"),
+    })
+  }
+
+  return specs
+}
+
+function applySpecs(pool: PrinterSummary[], specs: FilterSpec[]): {
+  matches: PrinterSummary[]
+  diagnostics: FilterDiagnostics[]
+} {
+  const diagnostics: FilterDiagnostics[] = []
+  let current = pool
+  for (const spec of specs) {
+    const matches: PrinterSummary[] = []
+    let excludedUnknown = 0
+    for (const printer of current) {
+      if (spec.pass(printer)) matches.push(printer)
+      else if (!spec.known(printer)) excludedUnknown++
+    }
+    diagnostics.push({
+      label: spec.label,
+      matched: matches.length,
+      excludedKnown: current.length - matches.length - excludedUnknown,
+      excludedUnknown,
+    })
+    current = matches
+  }
+  return { matches: current, diagnostics }
+}
+
+// Presentation order for search results: keys from explicitly requested
+// gradable criteria first, then the documented default
+// (status rank desc -> driverCount desc -> id asc). This is a disclosed
+// lexicographic sort over existing fields, not a score.
+function orderMatches(matches: PrinterSummary[], filters: CapabilityFilters): {
+  ordered: PrinterSummary[]
+  orderingLabel: string
+} {
+  const parts: string[] = []
+  const keys: ((a: PrinterSummary, b: PrinterSummary) => number)[] = []
+
+  if (filters.minDpi !== undefined) {
+    keys.push((a, b) => (b.maxDpi ?? 0) - (a.maxDpi ?? 0))
+    parts.push("recorded maximum resolution")
+  }
+  keys.push((a, b) => (STATUS_RANK[b.status ?? "Unknown"] ?? 0) - (STATUS_RANK[a.status ?? "Unknown"] ?? 0))
+  parts.push("Linux support status")
+  keys.push((a, b) => (b.driverCount ?? 0) - (a.driverCount ?? 0))
+  parts.push("number of listed drivers")
+
+  const ordered = [...matches].sort((a, b) => {
+    for (const key of keys) {
+      const cmp = key(a, b)
+      if (cmp !== 0) return cmp
+    }
+    return a.id.localeCompare(b.id)
+  })
+
+  return { ordered, orderingLabel: parts.join(", then ") }
+}
+
+// Rebuilds a canonical query string for a filter set, used by relaxation and
+// clarification chips so every chip resubmits through the normal pipeline.
+export function filtersToQueryText(filters: CapabilityFilters): string {
+  const parts: string[] = ["find"]
+  if (filters.color === true) parts.push("colour")
+  if (filters.color === false) parts.push("monochrome")
+  if (filters.manufacturer) parts.push(filters.manufacturer)
+  if (filters.type) parts.push(filters.type === "dot-matrix" ? "dot matrix" : filters.type)
+  parts.push("printers")
+  const withs: string[] = []
+  if (filters.postscript) {
+    withs.push(filters.postscript.minLevel ? `postscript ${filters.postscript.minLevel}` : "postscript")
+  }
+  if (filters.pcl) withs.push(filters.pcl.minLevel ? `pcl ${filters.pcl.minLevel}` : "pcl")
+  if (filters.minDpi !== undefined) withs.push(`${filters.minDpi} dpi`)
+  if (filters.support) withs.push(filters.support === "perfect" ? "perfect linux support" : "good linux support")
+  if (filters.duplex) withs.push("duplex")
+  if (withs.length > 0) parts.push("with", withs.join(" and "))
+  return parts.join(" ")
+}
+
+function computeRelaxations(catalog: PrinterSummary[], filters: CapabilityFilters): Relaxation[] {
+  const keys = Object.keys(filters).filter(key => key !== "duplex") as (keyof CapabilityFilters)[]
+  if (keys.length < 2) return []
+  const relaxations: Relaxation[] = []
+  for (const key of keys) {
+    const reduced: CapabilityFilters = { ...filters }
+    delete reduced[key]
+    delete reduced.duplex
+    const { matches } = applySpecs(catalog, buildSpecs(reduced))
+    if (matches.length > 0) {
+      // The dropped filter's label comes from its own spec, so it can never
+      // drift from the wording used elsewhere in the response.
+      const droppedLabel = buildSpecs({ [key]: filters[key] } as CapabilityFilters)[0]?.label ?? String(key)
+      relaxations.push({
+        droppedLabel,
+        resultCount: matches.length,
+        query: filtersToQueryText(reduced),
+      })
+    }
+  }
+  return relaxations
+}
+
+// ---------------------------------------------------------------------------
+// Reference resolution against the loaded catalogue
+
+type RefOutcome = { ok: true; summary: PrinterSummary } | { ok: false; execution: Execution }
+
+function resolveRef(
+  ref: PrinterRef,
+  context: AssistantPageContext,
+  byId: Map<string, PrinterSummary>,
+  alternative?: Chip
+): RefOutcome {
+  if (ref.kind === "resolved") {
+    const summary = byId.get(ref.id)
+    if (summary) return { ok: true, summary }
+    return {
+      ok: false,
+      execution: { kind: "entity-miss", state: "NO_MATCHES", text: ref.id, suggestions: [], driverSuggestions: [] },
+    }
+  }
+  if (ref.kind === "context") {
+    if (context.pageType === "printer") {
+      const summary = byId.get(context.printerId)
+      if (summary) return { ok: true, summary }
+    }
+    return {
+      ok: false,
+      execution: {
+        kind: "clarify",
+        state: "AMBIGUOUS",
+        question: { topic: "context-needed", subject: "printer", alternative },
+      },
+    }
+  }
+  if (ref.kind === "ambiguous") {
+    return {
+      ok: false,
+      execution: {
+        kind: "clarify",
+        state: "AMBIGUOUS",
+        question: { topic: "printer-ambiguous", text: ref.text, candidates: ref.candidates, total: ref.total },
+      },
+    }
+  }
+  return {
+    ok: false,
+    execution: {
+      kind: "entity-miss",
+      state: "NO_MATCHES",
+      text: ref.text,
+      suggestions: ref.suggestions,
+      driverSuggestions: [],
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+
+export async function executeQuery(
+  query: AssistantQuery,
+  context: AssistantPageContext,
+  data: AssistantData
+): Promise<Execution> {
+  switch (query.intent) {
+    case "UNSUPPORTED":
+      return { kind: "unsupported", state: "UNSUPPORTED", reason: query.reason }
+
+    case "GENERAL_INFO":
+      return { kind: "info", state: "SUCCESS", topic: query.topic }
+
+    case "PRINTER_LOOKUP": {
+      const byId = await catalogById(data)
+      const outcome = resolveRef(query.printer, context, byId)
+      if (!outcome.ok) return outcome.execution
+      const printer = await data.getPrinter(outcome.summary.id)
+      return { kind: "printer-details", state: "SUCCESS", summary: outcome.summary, printer }
+    }
+
+    case "SUPPORT_QUERY": {
+      const byId = await catalogById(data)
+      const outcome = resolveRef(query.printer, context, byId)
+      if (!outcome.ok) return outcome.execution
+      const printer = await data.getPrinter(outcome.summary.id)
+      return { kind: "support", state: "SUCCESS", summary: outcome.summary, printer }
+    }
+
+    case "DRIVER_LOOKUP": {
+      const byId = await catalogById(data)
+      const outcome = resolveRef(query.printer, context, byId)
+      if (!outcome.ok) return outcome.execution
+      const printer = await data.getPrinter(outcome.summary.id)
+      if (!printer) {
+        return { kind: "error", state: "ERROR", retryQuery: `which driver does ${printerName(outcome.summary)} use` }
+      }
+      return { kind: "driver-lookup", state: "SUCCESS", summary: outcome.summary, printer }
+    }
+
+    case "CAPABILITY_SEARCH":
+      return executeSearch(query.filters, query.unapplied, query.recommend, data)
+
+    case "SIMILAR_PRINTERS":
+      return executeSimilar(query.printer, query.filters, query.better ?? null, context, data)
+
+    case "EXPLANATION":
+      return executeExplanation(query.source, query.candidate, context, data)
+
+    case "DRIVER_SEARCH":
+      return executeDriverSearch(query.driver, context, data)
+
+    case "COMPARISON": {
+      const byId = await catalogById(data)
+      const first = resolveRef(query.printers[0], context, byId)
+      if (!first.ok) return first.execution
+      const second = resolveRef(query.printers[1], context, byId)
+      if (!second.ok) return second.execution
+      const [a, b] = await Promise.all([
+        data.getPrinter(first.summary.id),
+        data.getPrinter(second.summary.id),
+      ])
+      if (!a || !b) {
+        return {
+          kind: "error",
+          state: "ERROR",
+          retryQuery: `compare ${printerName(first.summary)} and ${printerName(second.summary)}`,
+        }
+      }
+      return { kind: "comparison", state: "SUCCESS", a, b }
+    }
+  }
+}
+
+const catalogCache = new WeakMap<AssistantData, Promise<Map<string, PrinterSummary>>>()
+
+async function catalogById(data: AssistantData): Promise<Map<string, PrinterSummary>> {
+  let cached = catalogCache.get(data)
+  if (!cached) {
+    cached = data.getCatalog().then(catalog => new Map(catalog.map(p => [p.id, p])))
+    catalogCache.set(data, cached)
+  }
+  return cached
+}
+
+async function executeSearch(
+  filters: CapabilityFilters,
+  unapplied: string[],
+  recommend: boolean,
+  data: AssistantData
+): Promise<Execution> {
+  const catalog = await data.getCatalog()
+
+  const applicable: CapabilityFilters = { ...filters }
+  const insufficient: string[] = []
+  if (applicable.duplex) {
+    // Recorded for zero printers in the current dataset: not filterable.
+    delete applicable.duplex
+    insufficient.push("duplex")
+  }
+
+  const specs = buildSpecs(applicable)
+
+  if (specs.length === 0) {
+    if (insufficient.length > 0 && unapplied.length === 0) {
+      return { kind: "insufficient", state: "INSUFFICIENT_DATA", message: { topic: "duplex", catalogSize: catalog.length } }
+    }
+    if (insufficient.length === 0 && recommend) {
+      return { kind: "clarify", state: "AMBIGUOUS", question: { topic: "criteria-needed" } }
+    }
+    // Only unrecognized constraints ("purple printer").
+    return {
+      kind: "search-results",
+      state: "UNSUPPORTED",
+      matches: [],
+      total: 0,
+      recommend,
+      diagnostics: {
+        filters: [],
+        unapplied,
+        insufficient,
+        relaxations: [],
+        orderingLabel: null,
+        catalogSize: catalog.length,
+      },
+    }
+  }
+
+  const { matches, diagnostics } = applySpecs(catalog, specs)
+  const { ordered, orderingLabel } = orderMatches(matches, applicable)
+
+  const relaxations =
+    ordered.length < MIN_COMFORTABLE_RESULTS ? computeRelaxations(catalog, applicable) : []
+
+  return {
+    kind: "search-results",
+    state: ordered.length === 0 ? "NO_MATCHES" : "SUCCESS",
+    matches: ordered,
+    total: ordered.length,
+    recommend,
+    diagnostics: {
+      filters: diagnostics,
+      unapplied,
+      insufficient,
+      relaxations,
+      orderingLabel,
+      catalogSize: catalog.length,
+    },
+  }
+}
+
+async function executeSimilar(
+  ref: PrinterRef,
+  filters: CapabilityFilters,
+  better: BetterDimension | "unspecified" | null,
+  context: AssistantPageContext,
+  data: AssistantData
+): Promise<Execution> {
+  const byId = await catalogById(data)
+  const outcome = resolveRef(ref, context, byId)
+  if (!outcome.ok) return outcome.execution
+  const source = outcome.summary
+
+  if (better === "unspecified") {
+    return {
+      kind: "clarify",
+      state: "AMBIGUOUS",
+      question: { topic: "better-dimension", anchorName: printerName(source) },
+    }
+  }
+
+  const entries = await data.getRecommendations(source.id)
+  if (entries.length === 0) {
+    return {
+      kind: "insufficient",
+      state: "INSUFFICIENT_DATA",
+      message: { topic: "no-recommendation-data", printerName: printerName(source) },
+    }
+  }
+
+  let filtered = entries
+  let sourceMaxDpi: number | null = null
+
+  if (better === "support") {
+    const sourceRank = STATUS_RANK[source.status ?? "Unknown"] ?? 0
+    filtered = filtered.filter(
+      entry => entry.status !== "Unknown" && (STATUS_RANK[entry.status] ?? 0) > sourceRank
+    )
+  } else if (better === "drivers") {
+    filtered = filtered.filter(entry => entry.driverCount > (source.driverCount ?? 0))
+  } else if (better === "resolution") {
+    sourceMaxDpi = typeof source.maxDpi === "number" ? source.maxDpi : null
+    if (sourceMaxDpi === null) {
+      return {
+        kind: "insufficient",
+        state: "INSUFFICIENT_DATA",
+        message: {
+          topic: "field-unrecorded",
+          printerName: printerName(source),
+          fieldLabel: "maximum resolution",
+        },
+      }
+    }
+    const anchor = sourceMaxDpi
+    filtered = filtered.filter(entry => {
+      const candidate = byId.get(entry.id)
+      return typeof candidate?.maxDpi === "number" && candidate.maxDpi > anchor
+    })
+  }
+
+  // Optional capability filters ("similar printers with colour") subset the
+  // shard's top-K in place; shard order is never changed.
+  let diagnostics: SearchDiagnostics | null = null
+  const applicable: CapabilityFilters = { ...filters }
+  delete applicable.duplex
+  const specs = buildSpecs(applicable)
+  if (specs.length > 0) {
+    const summaries = filtered
+      .map(entry => byId.get(entry.id))
+      .filter((summary): summary is PrinterSummary => summary !== undefined)
+    const { matches, diagnostics: filterDiagnostics } = applySpecs(summaries, specs)
+    const kept = new Set(matches.map(match => match.id))
+    filtered = filtered.filter(entry => kept.has(entry.id))
+    diagnostics = {
+      filters: filterDiagnostics,
+      unapplied: [],
+      insufficient: filters.duplex ? ["duplex"] : [],
+      relaxations: [],
+      orderingLabel: null,
+      catalogSize: byId.size,
+    }
+  } else if (filters.duplex) {
+    diagnostics = {
+      filters: [],
+      unapplied: [],
+      insufficient: ["duplex"],
+      relaxations: [],
+      orderingLabel: null,
+      catalogSize: byId.size,
+    }
+  }
+
+  return {
+    kind: "similar",
+    state: "SUCCESS",
+    source,
+    entries: filtered,
+    totalBeforeFilters: entries.length,
+    diagnostics,
+    better,
+    sourceMaxDpi,
+  }
+}
+
+async function executeExplanation(
+  source: PrinterRef,
+  candidate: PrinterRef | null,
+  context: AssistantPageContext,
+  data: AssistantData
+): Promise<Execution> {
+  const byId = await catalogById(data)
+
+  // If we are not on a printer page, there is no recommendation list to
+  // explain; when a candidate was named, offer its similarity list instead.
+  let alternative: Chip | undefined
+  if (candidate && candidate.kind === "resolved") {
+    const candidateSummary = byId.get(candidate.id)
+    if (candidateSummary) {
+      alternative = {
+        label: `Printers similar to ${printerName(candidateSummary)}`,
+        query: `printers similar to ${printerName(candidateSummary)}`,
+      }
+    }
+  }
+  const sourceOutcome = resolveRef(source, context, byId, alternative)
+  if (!sourceOutcome.ok) return sourceOutcome.execution
+  const sourceSummary = sourceOutcome.summary
+
+  const entries = await data.getRecommendations(sourceSummary.id)
+  if (entries.length === 0) {
+    return {
+      kind: "insufficient",
+      state: "INSUFFICIENT_DATA",
+      message: { topic: "no-recommendation-data", printerName: printerName(sourceSummary) },
+    }
+  }
+
+  if (!candidate) {
+    return {
+      kind: "clarify",
+      state: "AMBIGUOUS",
+      question: {
+        topic: "explanation-candidate",
+        sourceName: printerName(sourceSummary),
+        topRecommendations: entries.slice(0, 3),
+      },
+    }
+  }
+
+  const candidateOutcome = resolveRef(candidate, context, byId)
+  if (!candidateOutcome.ok) return candidateOutcome.execution
+
+  const entry = entries.find(item => item.id === candidateOutcome.summary.id)
+  if (!entry) {
+    return {
+      kind: "explanation-none",
+      state: "NO_MATCHES",
+      source: sourceSummary,
+      candidateName: printerName(candidateOutcome.summary),
+    }
+  }
+
+  return { kind: "explanation", state: "SUCCESS", source: sourceSummary, entry }
+}
+
+async function executeDriverSearch(
+  ref: DriverRef,
+  context: AssistantPageContext,
+  data: AssistantData
+): Promise<Execution> {
+  if (ref.kind === "family") {
+    return {
+      kind: "clarify",
+      state: "AMBIGUOUS",
+      question: { topic: "driver-family", family: ref.family, members: ref.members },
+    }
+  }
+  if (ref.kind === "unresolved") {
+    return {
+      kind: "clarify",
+      state: "AMBIGUOUS",
+      question: { topic: "driver-unresolved", text: ref.text, suggestions: ref.suggestions },
+    }
+  }
+
+  if (ref.kind === "context") {
+    // "this driver" resolves through the page context only - never through a
+    // value injected into the query text.
+    if (context.pageType !== "driver") {
+      return {
+        kind: "clarify",
+        state: "AMBIGUOUS",
+        question: { topic: "context-needed", subject: "driver" },
+      }
+    }
+    const driver = await data.getDriver(context.driverId)
+    if (!driver) {
+      return {
+        kind: "clarify",
+        state: "AMBIGUOUS",
+        question: { topic: "driver-unresolved", text: context.driverId, suggestions: [] },
+      }
+    }
+    return { kind: "driver-search", state: "SUCCESS", driver, anchor: null, anchorDriverName: null }
+  }
+
+  if (ref.kind === "same-as") {
+    const byId = await catalogById(data)
+    const outcome = resolveRef(ref.printer, context, byId)
+    if (!outcome.ok) return outcome.execution
+    const printer = await data.getPrinter(outcome.summary.id)
+    if (!printer) {
+      return { kind: "error", state: "ERROR", retryQuery: `which printers use the same driver as ${printerName(outcome.summary)}` }
+    }
+    const recommended = (printer.recommended_driver ?? "").trim()
+    if (!recommended) {
+      return {
+        kind: "insufficient",
+        state: "INSUFFICIENT_DATA",
+        message: {
+          topic: "field-unrecorded",
+          printerName: printerName(outcome.summary),
+          fieldLabel: "recommended driver",
+        },
+      }
+    }
+    const driverId = normalizeDriverId(recommended)
+    const driver = await data.getDriver(driverId)
+    if (!driver) {
+      return { kind: "error", state: "ERROR", retryQuery: `which printers use ${driverId}` }
+    }
+    return {
+      kind: "driver-search",
+      state: "SUCCESS",
+      driver,
+      anchor: outcome.summary,
+      anchorDriverName: driverId,
+    }
+  }
+
+  const driver = await data.getDriver(ref.id)
+  if (!driver) {
+    return {
+      kind: "clarify",
+      state: "AMBIGUOUS",
+      question: { topic: "driver-unresolved", text: ref.id, suggestions: [] },
+    }
+  }
+  return { kind: "driver-search", state: "SUCCESS", driver, anchor: null, anchorDriverName: null }
+}
diff --git a/lib/assistant/lexicon.ts b/lib/assistant/lexicon.ts
new file mode 100644
index 00000000..e39d841f
--- /dev/null
+++ b/lib/assistant/lexicon.ts
@@ -0,0 +1,132 @@
+// Capability lexicon: maps natural-language phrases onto typed catalogue
+// filters. The table is data - contributors add a row, not logic - and every
+// row is grounded in a real catalogue field (see docs/foomatic-assistant.md).
+//
+// Matching is token-based with consumption: each matched phrase marks its
+// tokens as consumed so that leftover content words can be surfaced as
+// unapplied constraints ("purple") instead of being silently ignored.
+
+import { HIGH_RES_MIN_DPI } from "./constants"
+import type { CapabilityFilters } from "./types"
+
+interface LexiconRule {
+  phrase: string[]
+  apply: (filters: CapabilityFilters) => void
+}
+
+// Longest phrases are matched first so "good linux support" is consumed as a
+// support filter before "linux" or "good" could be misread individually.
+const RULES: LexiconRule[] = [
+  // Linux support grade. "good" maps to Perfect|Mostly, the two grades the
+  // site itself presents as working; "perfect"-class wording maps to Perfect.
+  { phrase: ["good", "linux", "support"], apply: f => { f.support = "good" } },
+  { phrase: ["great", "linux", "support"], apply: f => { f.support = "good" } },
+  { phrase: ["solid", "linux", "support"], apply: f => { f.support = "good" } },
+  { phrase: ["good", "support"], apply: f => { f.support = "good" } },
+  { phrase: ["works", "well", "on", "linux"], apply: f => { f.support = "good" } },
+  { phrase: ["work", "well", "on", "linux"], apply: f => { f.support = "good" } },
+  { phrase: ["works", "well", "with", "linux"], apply: f => { f.support = "good" } },
+  { phrase: ["works", "on", "linux"], apply: f => { f.support = "good" } },
+  { phrase: ["works", "well"], apply: f => { f.support = "good" } },
+  { phrase: ["well", "supported"], apply: f => { f.support = "good" } },
+  { phrase: ["perfect", "linux", "support"], apply: f => { f.support = "perfect" } },
+  { phrase: ["excellent", "linux", "support"], apply: f => { f.support = "perfect" } },
+  { phrase: ["best", "linux", "support"], apply: f => { f.support = "perfect" } },
+  { phrase: ["better", "linux", "support"], apply: f => { f.support = "good" } },
+  { phrase: ["better", "support"], apply: f => { f.support = "good" } },
+  { phrase: ["perfect", "support"], apply: f => { f.support = "perfect" } },
+  { phrase: ["excellent", "support"], apply: f => { f.support = "perfect" } },
+  { phrase: ["best", "support"], apply: f => { f.support = "perfect" } },
+  { phrase: ["fully", "supported"], apply: f => { f.support = "perfect" } },
+
+  // Colour capability (tri-state color field; mono selects known-false).
+  { phrase: ["black", "and", "white"], apply: f => { f.color = false } },
+  { phrase: ["black", "white"], apply: f => { f.color = false } },
+  { phrase: ["monochrome"], apply: f => { f.color = false } },
+  { phrase: ["mono"], apply: f => { f.color = false } },
+  { phrase: ["b", "w"], apply: f => { f.color = false } },
+  { phrase: ["colour"], apply: f => { f.color = true } },
+  { phrase: ["color"], apply: f => { f.color = true } },
+  { phrase: ["coloured"], apply: f => { f.color = true } },
+  { phrase: ["colored"], apply: f => { f.color = true } },
+
+  // Mechanism type.
+  { phrase: ["laser"], apply: f => { f.type = "laser" } },
+  { phrase: ["inkjet"], apply: f => { f.type = "inkjet" } },
+  { phrase: ["ink", "jet"], apply: f => { f.type = "inkjet" } },
+  { phrase: ["dot", "matrix"], apply: f => { f.type = "dot-matrix" } },
+  { phrase: ["dotmatrix"], apply: f => { f.type = "dot-matrix" } },
+  { phrase: ["impact"], apply: f => { f.type = "dot-matrix" } },
+
+  // Duplex terminology is understood, but the dataset records duplex for zero
+  // printers - execution answers honestly instead of filtering.
+  { phrase: ["duplex"], apply: f => { f.duplex = true } },
+  { phrase: ["two", "sided"], apply: f => { f.duplex = true } },
+  { phrase: ["double", "sided"], apply: f => { f.duplex = true } },
+  { phrase: ["2", "sided"], apply: f => { f.duplex = true } },
+
+  // Page description languages. Levels come from psLevel/pclLevel; presence
+  // may also be established by commandset tokens (see execute.ts).
+  { phrase: ["postscript", "level", "3"], apply: f => { f.postscript = { minLevel: 3 } } },
+  { phrase: ["postscript", "level", "2"], apply: f => { f.postscript = { minLevel: 2 } } },
+  { phrase: ["postscript", "3"], apply: f => { f.postscript = { minLevel: 3 } } },
+  { phrase: ["postscript", "2"], apply: f => { f.postscript = { minLevel: 2 } } },
+  { phrase: ["ps3"], apply: f => { f.postscript = { minLevel: 3 } } },
+  { phrase: ["ps2"], apply: f => { f.postscript = { minLevel: 2 } } },
+  { phrase: ["postscript"], apply: f => { f.postscript = f.postscript ?? {} } },
+  { phrase: ["post", "script"], apply: f => { f.postscript = f.postscript ?? {} } },
+  { phrase: ["pcl", "xl"], apply: f => { f.pcl = { minLevel: 6 } } },
+  { phrase: ["pclxl"], apply: f => { f.pcl = { minLevel: 6 } } },
+  { phrase: ["pcl", "6"], apply: f => { f.pcl = { minLevel: 6 } } },
+  { phrase: ["pcl6"], apply: f => { f.pcl = { minLevel: 6 } } },
+  { phrase: ["pcl", "5e"], apply: f => { f.pcl = { minLevel: 5 } } },
+  { phrase: ["pcl5e"], apply: f => { f.pcl = { minLevel: 5 } } },
+  { phrase: ["pcl", "5"], apply: f => { f.pcl = { minLevel: 5 } } },
+  { phrase: ["pcl5"], apply: f => { f.pcl = { minLevel: 5 } } },
+  { phrase: ["pcl"], apply: f => { f.pcl = f.pcl ?? {} } },
+
+  // Resolution. Vague wording maps to a disclosed threshold.
+  { phrase: ["high", "resolution"], apply: f => { f.minDpi = HIGH_RES_MIN_DPI } },
+  { phrase: ["high", "res"], apply: f => { f.minDpi = HIGH_RES_MIN_DPI } },
+]
+
+export interface LexiconResult {
+  filters: CapabilityFilters
+  consumed: Set<number>
+}
+
+export function extractFilters(tokens: string[]): LexiconResult {
+  const filters: CapabilityFilters = {}
+  const consumed = new Set<number>()
+
+  for (const rule of [...RULES].sort((a, b) => b.phrase.length - a.phrase.length)) {
+    for (let i = 0; i + rule.phrase.length <= tokens.length; i++) {
+      let matches = true
+      for (let j = 0; j < rule.phrase.length; j++) {
+        if (tokens[i + j] !== rule.phrase[j] || consumed.has(i + j)) {
+          matches = false
+          break
+        }
+      }
+      if (matches) {
+        rule.apply(filters)
+        for (let j = 0; j < rule.phrase.length; j++) consumed.add(i + j)
+      }
+    }
+  }
+
+  // "600 dpi" / "at least 600 dpi": a number token directly before "dpi".
+  for (let i = 1; i < tokens.length; i++) {
+    if (tokens[i] === "dpi" && !consumed.has(i) && /^\d{2,4}$/.test(tokens[i - 1]) && !consumed.has(i - 1)) {
+      filters.minDpi = Number(tokens[i - 1])
+      consumed.add(i)
+      consumed.add(i - 1)
+    }
+  }
+
+  return { filters, consumed }
+}
+
+export function countFilters(filters: CapabilityFilters): number {
+  return Object.keys(filters).length
+}
diff --git a/lib/assistant/normalize.ts b/lib/assistant/normalize.ts
new file mode 100644
index 00000000..7c2b2d4e
--- /dev/null
+++ b/lib/assistant/normalize.ts
@@ -0,0 +1,25 @@
+// Text normalization for the assistant's NLU. Two canonical forms:
+// - normalized: lowercased, punctuation collapsed to single spaces
+//   ("Brother HL-1050!" -> "brother hl 1050")
+// - fused: alphanumerics only ("HL-1050" and "HL 1050" both -> "hl1050")
+// Model numbers are the dominant query shape, and punctuation/spacing variants
+// must unify by construction rather than by enumeration.
+
+import { MAX_QUERY_LENGTH } from "./constants"
+
+export function normalizeText(input: string): string {
+  return input
+    .slice(0, MAX_QUERY_LENGTH)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim()
+}
+
+export function fuseText(input: string): string {
+  return input.slice(0, MAX_QUERY_LENGTH).toLowerCase().replace(/[^a-z0-9]+/g, "")
+}
+
+export function tokenize(input: string): string[] {
+  const normalized = normalizeText(input)
+  return normalized ? normalized.split(" ") : []
+}
diff --git a/lib/assistant/parse.ts b/lib/assistant/parse.ts
new file mode 100644
index 00000000..7cda3393
--- /dev/null
+++ b/lib/assistant/parse.ts
@@ -0,0 +1,336 @@
+// Free text -> typed AssistantQuery.
+//
+// Intent classification is an ordered, deterministic rule cascade. The
+// precedence is deliberate and documented in docs/foomatic-assistant.md:
+//
+//   1. COMPARISON        (two printer refs + compare marker)
+//   2. EXPLANATION       (why + recommendation vocabulary)
+//   3. SIMILAR_PRINTERS  (similar/alternatives/better vocabulary)
+//   4. DRIVER_SEARCH     (printers-for-driver phrasing, "same driver")
+//   5. DRIVER_LOOKUP     (driver-of-printer phrasing)
+//   6. GENERAL_INFO      (meta questions about grades/similarity/help -
+//                         above SUPPORT_QUERY so meaning-questions are never
+//                         captured by printer-page context)
+//   7. SUPPORT_QUERY     (support question about one specific printer)
+//   8. CAPABILITY_SEARCH (recommend/best or any capability filters)
+//   9. PRINTER_LOOKUP    (a printer reference and nothing more specific)
+//  10. UNSUPPORTED       (unclear-but-domain or out-of-domain)
+//
+// Specific rules sit above generic ones so "why was this recommended?" can
+// never be swallowed by the recommendation rule, and "compare X and Y" can
+// never be read as a lookup of X.
+
+import type { DriverIndex, PrinterIndex } from "./entities"
+import { findNearMissPrinter, resolveDriverInText, resolvePrintersInText } from "./entities"
+import { countFilters, extractFilters } from "./lexicon"
+import { tokenize } from "./normalize"
+import type { AssistantPageContext, AssistantQuery, BetterDimension, PrinterRef } from "./types"
+
+// Words that are query mechanics, not constraints: leftovers on this list are
+// ignored; anything else left over surfaces as an unapplied constraint.
+const STOPWORDS = new Set([
+  "a", "an", "the", "i", "me", "my", "we", "you", "it", "they", "them", "please",
+  "find", "show", "search", "list", "give", "get", "need", "want", "looking",
+  "buy", "tell", "about", "suggest", "recommend", "recommended", "recommendation",
+  "recommendations", "best", "better", "good", "great", "top",
+  "printer", "printers", "device", "machine", "model", "models", "driver", "drivers",
+  "with", "and", "or", "that", "which", "what", "who", "why", "how", "when",
+  "is", "are", "was", "were", "be", "been", "does", "do", "did", "has", "have",
+  "can", "could", "would", "should", "will",
+  "in", "on", "to", "of", "for", "at", "by", "from", "as",
+  "this", "one", "some", "any", "all", "more", "most", "very",
+  "similar", "like", "alternative", "alternatives", "replacement", "instead",
+  "compare", "comparison", "versus", "vs",
+  "support", "supported", "supports", "supporting", "linux",
+  "works", "work", "well", "use", "uses", "using", "used", "same",
+  "prints", "printing", "print", "there", "than", "no", "not", "if",
+  "higher", "lower", "level", "so", "just", "really", "am", "s", "least",
+  "resolution", "res", "options", "similarity", "status", "grade", "grades",
+])
+
+const CONTEXT_PHRASES: string[][] = [
+  ["this", "printer"],
+  ["this", "driver"],
+  ["this", "one"],
+  ["this", "model"],
+  ["this", "device"],
+]
+
+export interface ParseInputs {
+  printers: PrinterIndex
+  drivers: DriverIndex
+}
+
+export function parseQuery(
+  input: string,
+  context: AssistantPageContext,
+  indexes: ParseInputs
+): AssistantQuery {
+  const tokens = tokenize(input)
+  if (tokens.length === 0) {
+    return { intent: "UNSUPPORTED", reason: "empty" }
+  }
+
+  const has = (word: string) => tokens.includes(word)
+  const hasPhrase = (phrase: string[]) =>
+    tokens.some((_, i) => phrase.every((word, j) => tokens[i + j] === word))
+
+  // --- signals (read from the raw token stream, independent of consumption)
+  const compareSignal =
+    has("compare") || has("comparison") || has("versus") || has("vs") ||
+    has("difference") || has("differences")
+  const whySignal = has("why")
+  const recommendSignal =
+    has("recommend") || has("recommended") || has("recommendation") ||
+    has("recommendations") || has("suggest") || has("suggested") || has("suggests") ||
+    hasPhrase(["should", "i"])
+  const similarSignal =
+    has("similar") || has("alternative") || has("alternatives") ||
+    has("replacement") || hasPhrase(["like", "this"]) || hasPhrase(["instead", "of"])
+  const betterSignal = has("better") || hasPhrase(["best", "alternatives"]) || hasPhrase(["best", "alternative"])
+  const bestSignal = has("best")
+  const driverWord = has("driver") || has("drivers")
+  const printersPlural = has("printers")
+  const supportSignal = has("support") || has("supported") || has("linux")
+  const listVerb =
+    has("find") || has("show") || has("search") || has("list") ||
+    has("need") || has("want") || has("looking") || has("get") || has("give")
+  const meaningSignal = has("mean") || has("means") || has("meaning") || has("meant")
+  const helpSignal =
+    hasPhrase(["what", "can", "you", "do"]) || hasPhrase(["who", "are", "you"]) ||
+    (tokens.length <= 2 && has("help"))
+
+  // --- context references ("this printer", bare "this"/"it" in short queries)
+  const contextRef =
+    CONTEXT_PHRASES.some(hasPhrase) ||
+    has("this") ||
+    (has("it") && tokens.length <= 7)
+
+  // Definition-shaped questions ("what is PostScript?", "what is a printer
+  // driver?") ask for meanings the Foomatic data does not record. They must
+  // never be captured by page context or answered with a printer list -
+  // detection excludes "what is the ..." (a lookup shape) and any query that
+  // carries an explicit reference.
+  const definitionSignal =
+    (hasPhrase(["what", "is"]) || hasPhrase(["what", "are"])) &&
+    !hasPhrase(["what", "is", "the"]) &&
+    !hasPhrase(["what", "are", "the"]) &&
+    !contextRef &&
+    !listVerb
+
+  // --- entity resolution (before the lexicon: model names such as
+  // "Color LaserJet 4500" contain capability words that must not be eaten)
+  const printerScan = resolvePrintersInText(tokens, indexes.printers)
+  const refs = printerScan.refs
+  const consumed = printerScan.consumed
+
+  const printerRef = (): PrinterRef => refs[0] ?? { kind: "context" }
+
+  // --- capability filters on what remains
+  const lexicon = extractFilters(tokens.map((token, i) => (consumed.has(i) ? "" : token)))
+  const filters = lexicon.filters
+  for (const i of lexicon.consumed) consumed.add(i)
+  if (printerScan.makeOnly) {
+    filters.manufacturer = printerScan.makeOnly
+  }
+
+  // --- near-miss models ("brother hl 2270dw"): after the lexicon, so
+  // capability tokens can never be misread as model numbers. Skipped for
+  // driver-shaped queries, whose leftover token is a driver name.
+  const driverShaped =
+    driverWord || hasPhrase(["same", "driver"]) || hasPhrase(["same", "drivers"]) ||
+    (printersPlural && (has("use") || has("uses") || has("using") || has("work") || has("works")))
+  if (refs.length === 0 && !driverShaped) {
+    const nearMiss = findNearMissPrinter(
+      tokens,
+      consumed,
+      indexes.printers,
+      printerScan.makeOnly,
+      token => STOPWORDS.has(token)
+    )
+    if (nearMiss) {
+      refs.push(nearMiss.ref)
+      for (const i of nearMiss.used) consumed.add(i)
+      delete filters.manufacturer
+    }
+  }
+
+  // --- unapplied constraints: leftover content words
+  const unapplied: string[] = []
+  for (let i = 0; i < tokens.length; i++) {
+    if (!consumed.has(i) && !STOPWORDS.has(tokens[i]) && !/^\d+$/.test(tokens[i])) {
+      unapplied.push(tokens[i])
+    }
+  }
+
+  // --- "better" comparison dimension, when one was named
+  const wantsBetter = betterSignal || (bestSignal && similarSignal)
+  const betterDimension = ((): BetterDimension | null => {
+    if (!wantsBetter && !similarSignal) return null
+    if (wantsBetter && filters.support) return "support"
+    if ((wantsBetter || has("higher")) && (has("resolution") || has("res"))) return "resolution"
+    if (hasPhrase(["driver", "options"]) || hasPhrase(["more", "drivers"]) || (wantsBetter && driverWord)) return "drivers"
+    if (wantsBetter && has("similarity")) return "similarity"
+    return null
+  })()
+
+  // ------------------------------------------------------------- cascade
+
+  // 1. COMPARISON
+  if (compareSignal) {
+    if (refs.length === 2) {
+      return { intent: "COMPARISON", printers: [refs[0], refs[1]] }
+    }
+    if (refs.length === 1 && (contextRef || context.pageType === "printer")) {
+      return { intent: "COMPARISON", printers: [{ kind: "context" }, refs[0]] }
+    }
+    return { intent: "UNSUPPORTED", reason: "unclear" }
+  }
+
+  // 2. EXPLANATION
+  if (whySignal && (recommendSignal || similarSignal)) {
+    // "why was X recommended?" reads X as the recommended candidate and the
+    // current page's printer as the recommendation source.
+    const candidate = refs[0] ?? null
+    return { intent: "EXPLANATION", source: { kind: "context" }, candidate }
+  }
+
+  // 3. SIMILAR_PRINTERS (including "better alternatives")
+  if (similarSignal || wantsBetter) {
+    const better = betterDimension ?? (wantsBetter ? "unspecified" : undefined)
+    if (better) {
+      // The support filter extracted from "better linux support" is the
+      // comparison dimension here, not a result filter.
+      if (betterDimension === "support") delete filters.support
+      return { intent: "SIMILAR_PRINTERS", printer: printerRef(), filters, unapplied, better }
+    }
+    return { intent: "SIMILAR_PRINTERS", printer: printerRef(), filters, unapplied }
+  }
+
+  // 4. DRIVER_SEARCH ("which printers use ...", "same driver as this")
+  if (hasPhrase(["same", "driver"]) || hasPhrase(["same", "drivers"])) {
+    return { intent: "DRIVER_SEARCH", driver: { kind: "same-as", printer: printerRef() } }
+  }
+  if (printersPlural && (driverWord || has("use") || has("uses") || has("using") || has("work") || has("works"))) {
+    // Fresh consumption set: in a printers-for-driver query, the driver name
+    // may have been speculatively claimed by the printer scan ("laserjet").
+    const driverRef = resolveDriverInText(tokens, new Set(), indexes.drivers, true)
+    if (driverRef) {
+      return { intent: "DRIVER_SEARCH", driver: driverRef }
+    }
+    // "which printers use this driver": a contextual driver reference, valid
+    // only because the phrase itself refers to the current page.
+    if (hasPhrase(["this", "driver"]) || (contextRef && context.pageType === "driver")) {
+      return { intent: "DRIVER_SEARCH", driver: { kind: "context" } }
+    }
+  }
+  // "what does this driver do?" - an explicit reference to the current
+  // driver page answers with that driver's own record.
+  if (hasPhrase(["this", "driver"])) {
+    return { intent: "DRIVER_SEARCH", driver: { kind: "context" } }
+  }
+
+  // 5. DRIVER_LOOKUP ("which driver does X use", "driver for this printer").
+  // Definition questions ("what is a printer driver?") are excluded: bare
+  // page context must not turn a vocabulary question into this printer's
+  // driver list.
+  if (
+    driverWord &&
+    !printersPlural &&
+    !definitionSignal &&
+    (refs.length > 0 || contextRef || context.pageType === "printer")
+  ) {
+    // A resolved driver mention plus a printer would be ambiguous phrasing;
+    // prefer the printer's driver question, which is the common ask.
+    return { intent: "DRIVER_LOOKUP", printer: printerRef() }
+  }
+
+  // 6. GENERAL_INFO (closed topics only). Deliberately ABOVE SUPPORT_QUERY:
+  // "what does perfect support mean?" asks for the meaning of the grade
+  // vocabulary, and page context must never capture a meaning-question and
+  // answer it with the current printer's own values.
+  if (helpSignal) {
+    return { intent: "GENERAL_INFO", topic: "assistant-help" }
+  }
+  if (meaningSignal || hasPhrase(["how", "does"]) || has("explain")) {
+    if (has("perfect") || has("mostly") || has("unsupported") || has("grade") || has("grades") || has("functionality")) {
+      return { intent: "GENERAL_INFO", topic: "support-grades" }
+    }
+    if (has("similarity") || has("score") || has("confidence") || has("tier") || has("recommendation") || has("recommendations")) {
+      return { intent: "GENERAL_INFO", topic: "similarity" }
+    }
+    // "what does Linux support mean?" - the grades answer IS the definition
+    // of Linux support in this database.
+    if (supportSignal && refs.length === 0 && !contextRef) {
+      return { intent: "GENERAL_INFO", topic: "support-grades" }
+    }
+  }
+  // "what are the grades?" with no printer in sight is also the general
+  // question; with a printer reference it falls through to that printer.
+  if ((has("grades") || has("grade")) && refs.length === 0 && !contextRef) {
+    return { intent: "GENERAL_INFO", topic: "support-grades" }
+  }
+  // Remaining definition questions ("what is PostScript?"): the data records
+  // which printers support such things, not what they are. Answer with an
+  // honest scope statement instead of a printer list or a captured context.
+  if (definitionSignal && refs.length === 0) {
+    if (supportSignal) {
+      return { intent: "GENERAL_INFO", topic: "support-grades" }
+    }
+    return { intent: "UNSUPPORTED", reason: "unclear" }
+  }
+
+  // 7. SUPPORT_QUERY (about one specific printer, not a filtered list).
+  // A duplex question ("does this printer support duplex?") is excluded: the
+  // dataset records duplex for no printer at all, and the honest answer is
+  // the duplex data-gap response, not the printer's Linux support grade.
+  if (
+    supportSignal &&
+    !printersPlural &&
+    !listVerb &&
+    !recommendSignal &&
+    !filters.duplex &&
+    (refs.length > 0 || contextRef || context.pageType === "printer")
+  ) {
+    return { intent: "SUPPORT_QUERY", printer: printerRef() }
+  }
+
+  // 8. CAPABILITY_SEARCH / recommendation requests
+  const hasFilters = countFilters(filters) > 0
+  const domainWord = has("printer") || has("printers") || driverWord || supportSignal
+  if (recommendSignal || bestSignal) {
+    return { intent: "CAPABILITY_SEARCH", filters, unapplied, recommend: true }
+  }
+
+  // Duplex questions get the duplex data-gap answer even when a specific
+  // printer was named or implied - the gap is catalogue-wide, and a lookup
+  // response would sidestep the question that was actually asked.
+  if (filters.duplex) {
+    return { intent: "CAPABILITY_SEARCH", filters, unapplied, recommend: false }
+  }
+
+  // 9. PRINTER_LOOKUP
+  if (refs.length > 0) {
+    return { intent: "PRINTER_LOOKUP", printer: refs[0] }
+  }
+  if (contextRef && context.pageType === "printer") {
+    return { intent: "PRINTER_LOOKUP", printer: { kind: "context" } }
+  }
+  // "what about this?" on a driver page refers to the driver, not a printer.
+  if (contextRef && context.pageType === "driver") {
+    return { intent: "DRIVER_SEARCH", driver: { kind: "context" } }
+  }
+
+  if (hasFilters || (unapplied.length > 0 && domainWord)) {
+    return { intent: "CAPABILITY_SEARCH", filters, unapplied, recommend: false }
+  }
+
+  // "find me a good printer": a list request with no usable criteria asks for
+  // criteria instead of dead-ending.
+  if (domainWord && listVerb && unapplied.length === 0) {
+    return { intent: "CAPABILITY_SEARCH", filters, unapplied, recommend: true }
+  }
+
+  // 10. UNSUPPORTED
+  return { intent: "UNSUPPORTED", reason: domainWord ? "unclear" : "out-of-domain" }
+}
diff --git a/lib/assistant/respond.ts b/lib/assistant/respond.ts
new file mode 100644
index 00000000..be7ff6ec
--- /dev/null
+++ b/lib/assistant/respond.ts
@@ -0,0 +1,746 @@
+// Execution -> ResponsePlan. Pure templates over typed retrieved data: every
+// dynamic value interpolated here comes from an Execution field, which in turn
+// came from the local artifacts. This module performs no I/O and never
+// receives raw user text (entity/constraint echoes travel through the typed
+// Execution).
+//
+// Language rules (mirrors PR #224's conventions in lib/foomatic/scoring.ts):
+// - the score is "N% similarity", never a match percentage or probability;
+// - the confidence tier describes evidence alignment, not compatibility;
+// - a printer's Foomatic status is its own Linux support grade, stated
+//   separately from similarity;
+// - unknown data is "not recorded", never a negative claim.
+
+import { confidenceTier } from "@/lib/foomatic/scoring"
+import type { Printer, PrinterSummary } from "@/lib/foomatic/types"
+import { MAX_RESULT_CARDS, UNKNOWN_REPORT_RATIO } from "./constants"
+import { printerName } from "./execute"
+import type {
+  AssistantPageContext,
+  Chip,
+  ComparisonRow,
+  Execution,
+  PrinterCardData,
+  RecommendationEntry,
+  ResponseBlock,
+  ResponsePlan,
+  SearchDiagnostics,
+} from "./types"
+
+// Suggestion rule: a chip is a product promise. Its query is the exact text
+// of its label (modulo casing/punctuation), it must parse to a supported
+// intent, and it must never smuggle current-page values into the question.
+const EXAMPLE_CHIPS: Chip[] = [
+  { label: "Find a colour laser printer", query: "find a colour laser printer" },
+  { label: "Find printers with good Linux support", query: "find printers with good linux support" },
+  { label: "What can you do?", query: "what can you do" },
+]
+
+function text(value: string): ResponseBlock {
+  return { kind: "text", text: value }
+}
+
+function chips(items: Chip[]): ResponseBlock {
+  return { kind: "chips", chips: items }
+}
+
+function summaryCard(summary: PrinterSummary): PrinterCardData {
+  return {
+    id: summary.id,
+    manufacturer: summary.manufacturer,
+    model: summary.model,
+    status: summary.status ?? "Unknown",
+    type: summary.type !== "unknown" ? summary.type : undefined,
+    driverCount: summary.driverCount,
+    features: summaryFeatures(summary),
+  }
+}
+
+// Capability chips show established values only; unknown fields are simply
+// absent (detail views spell out "not recorded").
+function summaryFeatures(summary: PrinterSummary): string[] {
+  const features: string[] = []
+  if (summary.color === true) features.push("Colour")
+  if (summary.color === false) features.push("Monochrome")
+  if (typeof summary.maxDpi === "number") features.push(`${summary.maxDpi} dpi`)
+  if (typeof summary.psLevel === "number" && summary.psLevel > 0) features.push(`PostScript ${summary.psLevel}`)
+  if (typeof summary.pclLevel === "number" && summary.pclLevel > 0) features.push(`PCL ${summary.pclLevel}`)
+  return features
+}
+
+function recommendationCard(entry: RecommendationEntry): PrinterCardData {
+  const tier = confidenceTier(entry.score)
+  return {
+    id: entry.id,
+    manufacturer: entry.manufacturer ?? "",
+    model: entry.model ?? entry.id,
+    status: entry.status,
+    type: entry.type !== "unknown" ? entry.type : undefined,
+    driverCount: entry.driverCount,
+    score: entry.score,
+    tierLabel: tier.label,
+    tierTone: tier.tone,
+  }
+}
+
+function similarityPercent(score: number): string {
+  return `${Math.round(score * 100)}% similarity`
+}
+
+function unknownNotes(diagnostics: SearchDiagnostics): string[] {
+  const notes: string[] = []
+  for (const filter of diagnostics.filters) {
+    const pool = filter.matched + filter.excludedKnown + filter.excludedUnknown
+    if (pool > 0 && filter.excludedUnknown / pool >= UNKNOWN_REPORT_RATIO) {
+      notes.push(
+        `${filter.excludedUnknown} more printers don't record the data needed for the "${filter.label}" requirement, so they are not shown - that is missing data, not a "no".`
+      )
+    }
+  }
+  return notes
+}
+
+function duplexNote(catalogSize: number): string {
+  return (
+    `The Foomatic database doesn't record duplex (two-sided printing) capability for any of its ` +
+    `${catalogSize} printers, so I can't filter by duplex - please check the manufacturer's specifications for that.`
+  )
+}
+
+const FILTERABLE_SUMMARY =
+  "I can filter by colour vs monochrome, printer type (laser, inkjet, dot-matrix), resolution, PostScript/PCL, manufacturer, and Linux support grade."
+
+export function buildResponse(execution: Execution): ResponsePlan {
+  switch (execution.kind) {
+    case "unsupported": {
+      if (execution.reason === "empty") {
+        return { blocks: [text("Type a question about printers, drivers, or Linux support to get started."), chips(EXAMPLE_CHIPS)] }
+      }
+      if (execution.reason === "unclear") {
+        return {
+          blocks: [
+            text(`I didn't catch what you're looking for. ${FILTERABLE_SUMMARY}`),
+            chips(EXAMPLE_CHIPS),
+          ],
+        }
+      }
+      return {
+        blocks: [
+          text(
+            "I can only answer questions about the printers, drivers, and Linux support information in OpenPrinting's Foomatic database - that one is outside my data."
+          ),
+          chips(EXAMPLE_CHIPS),
+        ],
+      }
+    }
+
+    case "info":
+      return buildInfo(execution.topic)
+
+    case "error":
+      return {
+        blocks: [
+          text("I couldn't load the data needed to answer that - the request failed. Please try again."),
+          chips([{ label: "Try again", query: execution.retryQuery }]),
+        ],
+      }
+
+    case "clarify":
+      return buildClarify(execution)
+
+    case "insufficient": {
+      const message = execution.message
+      if (message.topic === "duplex") {
+        return { blocks: [text(duplexNote(message.catalogSize)), chips(EXAMPLE_CHIPS)] }
+      }
+      if (message.topic === "no-recommendation-data") {
+        return {
+          blocks: [text(`No similarity data is available for ${message.printerName}, so I can't list similar printers for it.`)],
+        }
+      }
+      return {
+        blocks: [
+          text(
+            `The Foomatic data doesn't record ${message.fieldLabel} for ${message.printerName}, so I can't answer that from the available data.`
+          ),
+        ],
+      }
+    }
+
+    case "entity-miss": {
+      const blocks: ResponseBlock[] = [
+        text(`I couldn't find a printer matching "${execution.text}" in the OpenPrinting database.`),
+      ]
+      if (execution.suggestions.length > 0) {
+        blocks.push(text("Closest model names in the catalogue:"))
+        blocks.push({
+          kind: "printer-cards",
+          printers: execution.suggestions.map(candidate => ({
+            id: candidate.id,
+            manufacturer: candidate.manufacturer,
+            model: candidate.model,
+            status: "Unknown",
+          })),
+        })
+        blocks.push(
+          chips(
+            execution.suggestions.map(candidate => ({
+              label: `Tell me about ${candidate.manufacturer} ${candidate.model}`,
+              query: `tell me about ${candidate.manufacturer} ${candidate.model}`,
+            }))
+          )
+        )
+      }
+      return { blocks }
+    }
+
+    case "printer-details":
+      return buildPrinterDetails(execution.summary, execution.printer)
+
+    case "support":
+      return buildSupport(execution.summary, execution.printer)
+
+    case "driver-lookup":
+      return buildDriverLookup(execution.summary, execution.printer)
+
+    case "driver-search": {
+      const driver = execution.driver
+      const blocks: ResponseBlock[] = []
+      if (execution.anchor && execution.anchorDriverName) {
+        blocks.push(
+          text(
+            `${printerName(execution.anchor)}'s recommended driver is ${execution.anchorDriverName}. ` +
+              `Printers that also list ${execution.anchorDriverName}:`
+          )
+        )
+      } else {
+        blocks.push(text(`${driver.printers.length} printers in the database list the ${driver.name} driver:`))
+      }
+      blocks.push({
+        kind: "driver-card",
+        driver: {
+          id: driver.id,
+          name: driver.name,
+          supplier: driver.supplier,
+          type: driver.type,
+          printerCount: driver.printerCount,
+        },
+      })
+      const shown = driver.printers.slice(0, MAX_RESULT_CARDS)
+      blocks.push({
+        kind: "printer-cards",
+        printers: shown.map(printer => ({
+          id: printer.id,
+          manufacturer: printer.manufacturer,
+          model: printer.model,
+          status: printer.status ?? "Unknown",
+        })),
+      })
+      if (driver.printers.length > shown.length) {
+        blocks.push(
+          text(`Showing ${shown.length} of ${driver.printers.length} - the full list is on the driver page.`)
+        )
+      }
+      return { blocks }
+    }
+
+    case "comparison":
+      return buildComparison(execution.a, execution.b)
+
+    case "explanation":
+      return buildExplanation(execution.source, execution.entry)
+
+    case "explanation-none":
+      return {
+        blocks: [
+          text(
+            `${execution.candidateName} is not in ${printerName(execution.source)}'s similar-printers list, so there is no recommendation to explain for that pair.`
+          ),
+          chips([
+            {
+              label: `Printers similar to ${printerName(execution.source)}`,
+              query: `printers similar to ${printerName(execution.source)}`,
+            },
+          ]),
+        ],
+      }
+
+    case "similar":
+      return buildSimilar(execution)
+
+    case "search-results":
+      return buildSearch(execution)
+  }
+}
+
+function buildInfo(topic: "support-grades" | "similarity" | "assistant-help"): ResponsePlan {
+  if (topic === "support-grades") {
+    return {
+      blocks: [
+        text(
+          "Foomatic grades how well a printer works with the free Linux drivers it lists: " +
+            '"Perfect" means the upstream functionality grade A (everything works), "Mostly" covers grades B and C ' +
+            '(works with some limitations), "Unsupported" means no working driver is known, and "Unknown" means ' +
+            "the database simply has no grade recorded. The grade describes the printer's own driver situation - " +
+            "it is separate from any similarity score."
+        ),
+        chips(EXAMPLE_CHIPS),
+      ],
+    }
+  }
+  if (topic === "similarity") {
+    return {
+      blocks: [
+        text(
+          "The similarity score compares two printers' recorded features - shared driver families, mechanism type, " +
+            "colour capability, command sets, and resolution. It is a deterministic feature comparison, not a " +
+            "probability and not a compatibility promise. The tiers (High confidence, Good match, Moderate match, " +
+            "Limited evidence) describe how much recorded evidence supports the similarity, and each recommended " +
+            "printer's own Linux support grade is always shown separately."
+        ),
+        chips(EXAMPLE_CHIPS),
+      ],
+    }
+  }
+  return {
+    blocks: [
+      text(
+        "I answer questions from OpenPrinting's Foomatic printer database: look up printers, filter by capabilities, " +
+          "list similar printers, explain recommendations, compare two models, and find drivers. " +
+          FILTERABLE_SUMMARY
+      ),
+      chips(EXAMPLE_CHIPS),
+    ],
+  }
+}
+
+function buildClarify(execution: Extract<Execution, { kind: "clarify" }>): ResponsePlan {
+  const question = execution.question
+  switch (question.topic) {
+    case "printer-ambiguous": {
+      const blocks: ResponseBlock[] = [
+        text(
+          question.total > question.candidates.length
+            ? `"${question.text}" matches ${question.total} printers in the database. Did you mean one of these?`
+            : `"${question.text}" matches more than one printer. Did you mean one of these?`
+        ),
+        {
+          kind: "printer-cards",
+          printers: question.candidates.map(candidate => ({
+            id: candidate.id,
+            manufacturer: candidate.manufacturer,
+            model: candidate.model,
+            status: "Unknown",
+          })),
+        },
+        chips(
+          question.candidates.map(candidate => ({
+            label: `Tell me about ${candidate.manufacturer} ${candidate.model}`,
+            query: `tell me about ${candidate.manufacturer} ${candidate.model}`,
+          }))
+        ),
+      ]
+      return { blocks }
+    }
+    case "criteria-needed":
+      return {
+        blocks: [
+          text(
+            "The database doesn't rank printers overall, so there is no single \"best\" printer to point to. " +
+              "Tell me what you need and I can filter the catalogue."
+          ),
+          chips([
+            { label: "Find colour laser printers", query: "find colour laser printers" },
+            { label: "Find printers with good Linux support", query: "find printers with good linux support" },
+            { label: "Find printers with PostScript", query: "find printers with postscript" },
+            { label: "Find inkjet printers", query: "find inkjet printers" },
+          ]),
+        ],
+      }
+    case "better-dimension":
+      return {
+        blocks: [
+          text(
+            `Better in what way? The database can compare these dimensions for printers similar to ${question.anchorName}:`
+          ),
+          chips([
+            { label: "Linux support", query: `alternatives to ${question.anchorName} with better linux support` },
+            { label: "Overall similarity", query: `printers similar to ${question.anchorName}` },
+            { label: "Resolution", query: `alternatives to ${question.anchorName} with higher resolution` },
+            { label: "Driver options", query: `alternatives to ${question.anchorName} with more driver options` },
+          ]),
+        ],
+      }
+    case "driver-family":
+      return {
+        blocks: [
+          text(
+            `"${question.family}" is a driver family, not a single driver. Which of these drivers do you mean?`
+          ),
+          chips(question.members.map(member => ({ label: member, query: `which printers use ${member}` }))),
+        ],
+      }
+    case "driver-unresolved": {
+      const blocks: ResponseBlock[] = [
+        text(`I couldn't find a driver named "${question.text}" in the OpenPrinting database.`),
+      ]
+      if (question.suggestions.length > 0) {
+        blocks.push(text("Did you mean:"))
+        blocks.push(
+          chips(question.suggestions.map(id => ({ label: id, query: `which printers use ${id}` })))
+        )
+      }
+      return { blocks }
+    }
+    case "context-needed": {
+      const blocks: ResponseBlock[] = [
+        text(
+          question.subject === "printer"
+            ? "I can't tell which printer you mean from this page - which model are you asking about?"
+            : "I can't tell which driver you mean from this page - which driver are you asking about?"
+        ),
+      ]
+      if (question.alternative) {
+        blocks.push(chips([question.alternative]))
+      }
+      return { blocks }
+    }
+    case "explanation-candidate":
+      return {
+        blocks: [
+          text(`Which of ${question.sourceName}'s recommendations should I explain?`),
+          chips(
+            question.topRecommendations.map(entry => {
+              const name = `${entry.manufacturer ?? ""} ${entry.model ?? entry.id}`.trim()
+              return { label: `Why was ${name} recommended?`, query: `why was ${name} recommended` }
+            })
+          ),
+        ],
+      }
+  }
+}
+
+function describeTriState(value: boolean | "unknown" | undefined, yes: string, no: string): string {
+  if (value === true) return yes
+  if (value === false) return no
+  return "not recorded"
+}
+
+function buildPrinterDetails(summary: PrinterSummary, printer: Printer | null): ResponsePlan {
+  const name = printerName(summary)
+  const facts: string[] = []
+  facts.push(
+    summary.type && summary.type !== "unknown"
+      ? `${name} is a ${summary.type === "dot-matrix" ? "dot-matrix" : summary.type} printer`
+      : `${name}'s mechanism type is not recorded`
+  )
+  facts.push(`its Foomatic Linux support grade is ${summary.status ?? "Unknown"}`)
+  facts.push(`colour printing: ${describeTriState(summary.color, "yes", "no (monochrome)")}`)
+  if (typeof summary.maxDpi === "number") {
+    facts.push(`maximum recorded resolution ${summary.maxDpi} dpi`)
+  }
+  facts.push(`${summary.driverCount ?? 0} drivers are listed`)
+  const recommended = (printer?.recommended_driver ?? "").trim()
+  if (recommended) {
+    facts.push(`the recommended driver is ${recommended.replace(/^driver\//, "")}`)
+  }
+
+  return {
+    blocks: [
+      text(`${facts.join("; ")}.`),
+      { kind: "printer-cards", printers: [summaryCard(summary)] },
+      chips([
+        { label: `Printers similar to ${name}`, query: `printers similar to ${name}` },
+        { label: `Linux support for ${name}`, query: `linux support for ${name}` },
+        { label: `Which driver does ${name} use?`, query: `which driver does ${name} use` },
+      ]),
+    ],
+  }
+}
+
+function buildSupport(summary: PrinterSummary, printer: Printer | null): ResponsePlan {
+  const name = printerName(summary)
+  const status = summary.status ?? "Unknown"
+  const grade = summary.functionality && summary.functionality !== "?" ? summary.functionality : null
+  const parts: string[] = []
+  if (status === "Unknown") {
+    parts.push(`The Foomatic database has no Linux support grade recorded for ${name}.`)
+  } else {
+    parts.push(
+      `${name}'s Foomatic Linux support status is ${status}` +
+        (grade ? ` (upstream functionality grade ${grade})` : "") +
+        "."
+    )
+  }
+  parts.push(`${summary.driverCount ?? 0} drivers are listed for it.`)
+  const recommended = (printer?.recommended_driver ?? "").trim()
+  if (recommended) {
+    parts.push(`The recommended driver is ${recommended.replace(/^driver\//, "")}.`)
+  }
+  return {
+    blocks: [
+      text(parts.join(" ")),
+      { kind: "printer-cards", printers: [summaryCard(summary)] },
+      chips([{ label: "What do the support grades mean?", query: "what do the support grades mean" }]),
+    ],
+  }
+}
+
+function buildDriverLookup(summary: PrinterSummary, printer: Printer): ResponsePlan {
+  const name = printerName(summary)
+  const recommended = (printer.recommended_driver ?? "").trim().replace(/^driver\//, "")
+  const others = (printer.drivers ?? [])
+    .map(driver => driver.name)
+    .filter(driverName => driverName && driverName !== recommended)
+
+  const blocks: ResponseBlock[] = []
+  if (recommended) {
+    blocks.push(text(`${name}'s recommended driver is ${recommended}.`))
+  } else if (others.length > 0) {
+    blocks.push(text(`The database records no recommended driver for ${name}.`))
+  } else {
+    blocks.push(text(`The database lists no drivers for ${name}.`))
+  }
+  if (others.length > 0) {
+    blocks.push(text(`Also listed: ${others.slice(0, 8).join(", ")}${others.length > 8 ? ` and ${others.length - 8} more` : ""}.`))
+  }
+  if (recommended) {
+    blocks.push(
+      chips([
+        { label: `Printers using ${recommended}`, query: `which printers use ${recommended}` },
+      ])
+    )
+  }
+  return { blocks }
+}
+
+function comparisonValue(printer: Printer, field: "type" | "color" | "maxDpi" | "psLevel" | "pclLevel"): string {
+  switch (field) {
+    case "type":
+      return printer.type && printer.type !== "unknown" ? printer.type : "Not recorded"
+    case "color":
+      return printer.color === true ? "Colour" : printer.color === false ? "Monochrome" : "Not recorded"
+    case "maxDpi":
+      return typeof printer.maxDpi === "number" ? `${printer.maxDpi} dpi` : "Not recorded"
+    case "psLevel":
+      return typeof printer.psLevel === "number" && printer.psLevel > 0 ? `Level ${printer.psLevel}` : "Not recorded"
+    case "pclLevel":
+      return typeof printer.pclLevel === "number" && printer.pclLevel > 0 ? `Level ${printer.pclLevel}` : "Not recorded"
+  }
+}
+
+function buildComparison(a: Printer, b: Printer): ResponsePlan {
+  const aName = printerName(a)
+  const bName = printerName(b)
+  const rows: ComparisonRow[] = [
+    { label: "Linux support", a: a.status ?? "Unknown", b: b.status ?? "Unknown" },
+    { label: "Type", a: comparisonValue(a, "type"), b: comparisonValue(b, "type") },
+    { label: "Colour", a: comparisonValue(a, "color"), b: comparisonValue(b, "color") },
+    { label: "Max resolution", a: comparisonValue(a, "maxDpi"), b: comparisonValue(b, "maxDpi") },
+    { label: "PostScript", a: comparisonValue(a, "psLevel"), b: comparisonValue(b, "psLevel") },
+    { label: "PCL", a: comparisonValue(a, "pclLevel"), b: comparisonValue(b, "pclLevel") },
+    { label: "Listed drivers", a: String((a.drivers ?? []).length), b: String((b.drivers ?? []).length) },
+    {
+      label: "Recommended driver",
+      a: (a.recommended_driver ?? "").replace(/^driver\//, "") || "Not recorded",
+      b: (b.recommended_driver ?? "").replace(/^driver\//, "") || "Not recorded",
+    },
+  ]
+  return {
+    blocks: [
+      text(
+        `Here is what the Foomatic data records for ${aName} and ${bName}. "Not recorded" means the database has no ` +
+          `data for that field - the data doesn't rank one printer above the other overall.`
+      ),
+      { kind: "comparison", aName, bName, rows },
+    ],
+  }
+}
+
+function buildExplanation(source: PrinterSummary, entry: RecommendationEntry): ResponsePlan {
+  const sourceName = printerName(source)
+  const entryName = `${entry.manufacturer ?? ""} ${entry.model ?? entry.id}`.trim()
+  const tier = confidenceTier(entry.score)
+  const blocks: ResponseBlock[] = [
+    text(
+      `${entryName} appears in ${sourceName}'s similar-printers list with a ${similarityPercent(entry.score)} score, ` +
+        `in the "${tier.label}" tier. The score is a comparison of recorded printer features - it is not a promise that ` +
+        `one printer can replace the other. ${entryName}'s own Foomatic Linux support grade is ${entry.status}, with ` +
+        `${entry.driverCount} listed drivers.`
+    ),
+  ]
+  if (entry.sharedFeatures.length > 0) {
+    // The shard's own explanation strings, verbatim, one per line.
+    blocks.push({ kind: "list", title: "Why it's similar:", items: entry.sharedFeatures })
+  } else {
+    blocks.push(text("The recommendation lists no individual shared features for this pair."))
+  }
+  blocks.push({ kind: "printer-cards", printers: [recommendationCard(entry)] })
+  return { blocks }
+}
+
+function buildSimilar(execution: Extract<Execution, { kind: "similar" }>): ResponsePlan {
+  const sourceName = printerName(execution.source)
+  const blocks: ResponseBlock[] = []
+  const shown = execution.entries.slice(0, MAX_RESULT_CARDS)
+
+  if (execution.better === "support") {
+    const sourceStatus = execution.source.status ?? "Unknown"
+    if (execution.entries.length === 0) {
+      blocks.push(
+        text(
+          sourceStatus === "Perfect"
+            ? `${sourceName}'s own Linux support grade is already Perfect - none of its most similar printers have a higher grade.`
+            : `Comparing Foomatic Linux support grades only: none of the ${execution.totalBeforeFilters} printers most similar to ${sourceName} have a grade above ${sourceStatus}. (Printers with an Unknown grade are excluded - unknown is not comparable.)`
+        )
+      )
+    } else {
+      blocks.push(
+        text(
+          `Comparing Foomatic Linux support grades only: ${execution.entries.length} of the ${execution.totalBeforeFilters} printers most similar to ${sourceName} have a higher grade than its ${sourceStatus}. This compares support grades, not overall quality.`
+        )
+      )
+    }
+  } else if (execution.better === "resolution") {
+    blocks.push(
+      text(
+        `Comparing recorded maximum resolution only: ${execution.entries.length} of the ${execution.totalBeforeFilters} printers most similar to ${sourceName} record a higher resolution than its ${execution.sourceMaxDpi} dpi. Printers without recorded resolution are excluded - that is missing data, not a lower resolution.`
+      )
+    )
+  } else if (execution.better === "drivers") {
+    blocks.push(
+      text(
+        `Comparing the number of listed drivers only: ${execution.entries.length} of the ${execution.totalBeforeFilters} printers most similar to ${sourceName} list more drivers than its ${execution.source.driverCount ?? 0}.`
+      )
+    )
+  } else if (execution.diagnostics && execution.diagnostics.filters.length > 0) {
+    blocks.push(
+      text(
+        `${execution.entries.length} of the ${execution.totalBeforeFilters} printers most similar to ${sourceName} match your requirements:`
+      )
+    )
+  } else {
+    blocks.push(
+      text(
+        `These are the printers most similar to ${sourceName}, by shared recorded features. Each one's own Linux support grade is shown - similarity is not a compatibility promise.`
+      )
+    )
+  }
+
+  if (execution.diagnostics?.insufficient.includes("duplex")) {
+    blocks.push(text(duplexNote(execution.diagnostics.catalogSize)))
+  }
+
+  if (shown.length > 0) {
+    blocks.push({ kind: "printer-cards", printers: shown.map(recommendationCard) })
+  }
+  if (execution.entries.length > shown.length) {
+    blocks.push(text(`Showing ${shown.length} of ${execution.entries.length}.`))
+  }
+  if (execution.entries.length === 0 && execution.better === null) {
+    blocks.push(
+      text(
+        `None of the ${execution.totalBeforeFilters} most similar printers match those requirements on recorded data.`
+      )
+    )
+  }
+  if (shown.length > 0) {
+    const top = shown[0]
+    const topName = `${top.manufacturer ?? ""} ${top.model ?? top.id}`.trim()
+    blocks.push(
+      chips([
+        { label: `Why was ${topName} recommended?`, query: `why was ${topName} recommended` },
+        { label: `Compare ${sourceName} and ${topName}`, query: `compare ${sourceName} and ${topName}` },
+      ])
+    )
+  }
+  return { blocks }
+}
+
+function buildSearch(execution: Extract<Execution, { kind: "search-results" }>): ResponsePlan {
+  const diagnostics = execution.diagnostics
+  const blocks: ResponseBlock[] = []
+
+  for (const unappliedNote of buildUnappliedNotes(diagnostics.unapplied)) {
+    blocks.push(text(unappliedNote))
+  }
+  if (diagnostics.insufficient.includes("duplex")) {
+    blocks.push(text(duplexNote(diagnostics.catalogSize)))
+  }
+
+  if (execution.state === "UNSUPPORTED") {
+    blocks.push(chips(EXAMPLE_CHIPS))
+    return { blocks }
+  }
+
+  const requirements = diagnostics.filters.map(filter => filter.label).join(", ")
+
+  if (execution.state === "NO_MATCHES") {
+    const narrowing = [...diagnostics.filters].sort((a, b) => a.matched - b.matched)[0]
+    blocks.push(
+      text(
+        `No printers in the catalogue match ${requirements} on recorded data.` +
+          (narrowing ? ` The "${narrowing.label}" requirement narrowed it furthest.` : "")
+      )
+    )
+  } else {
+    const shown = execution.matches.slice(0, MAX_RESULT_CARDS)
+    blocks.push(
+      text(
+        `${execution.total} printers match ${requirements}. Showing the first ${shown.length}, ordered by ${diagnostics.orderingLabel}.`
+      )
+    )
+    blocks.push({ kind: "printer-cards", printers: shown.map(summaryCard) })
+  }
+
+  for (const note of unknownNotes(diagnostics)) {
+    blocks.push(text(note))
+  }
+
+  if (diagnostics.relaxations.length > 0) {
+    blocks.push(text("Without one of the requirements:"))
+    blocks.push(
+      chips(
+        diagnostics.relaxations.map(relaxation => ({
+          label: `Drop "${relaxation.droppedLabel}" (${relaxation.resultCount} printers)`,
+          query: relaxation.query,
+        }))
+      )
+    )
+  }
+
+  return { blocks }
+}
+
+function buildUnappliedNotes(unapplied: string[]): string[] {
+  if (unapplied.length === 0) return []
+  const list = unapplied.map(word => `"${word}"`).join(", ")
+  return [
+    `I can't filter by ${list} - the database doesn't record that about printers. ${FILTERABLE_SUMMARY}`,
+  ]
+}
+
+// Same suggestion rule as EXAMPLE_CHIPS: the query IS the label text.
+// Contextual phrasing ("this printer"/"this driver") stays in the submitted
+// message and resolves through the page-context provider - current-page
+// values are never substituted into the question.
+export function contextSuggestions(context: AssistantPageContext): Chip[] {
+  if (context.pageType === "printer") {
+    return [
+      { label: "What printers are similar to this one?", query: "what printers are similar to this one" },
+      { label: "How good is the Linux support?", query: "how good is the linux support" },
+      { label: "Which driver does this printer use?", query: "which driver does this printer use" },
+    ]
+  }
+  if (context.pageType === "driver") {
+    return [
+      { label: "Which printers use this driver?", query: "which printers use this driver" },
+      { label: "Find a colour laser printer", query: "find a colour laser printer" },
+    ]
+  }
+  return [
+    { label: "Find a colour laser printer", query: "find a colour laser printer" },
+    { label: "Find printers with good Linux support", query: "find printers with good linux support" },
+    { label: "Compare HP 2500C and HP DeskJet 560C", query: "compare HP 2500C and HP DeskJet 560C" },
+  ]
+}
diff --git a/lib/assistant/types.ts b/lib/assistant/types.ts
new file mode 100644
index 00000000..7ec2705f
--- /dev/null
+++ b/lib/assistant/types.ts
@@ -0,0 +1,273 @@
+// Shared types for the printer assistant.
+//
+// The pipeline is: free text -> parse (nlu) -> AssistantQuery (typed IR)
+// -> execute (the only layer that touches data) -> Execution (typed result)
+// -> respond (pure templates) -> ResponsePlan (typed blocks) -> React.
+// Natural language never controls execution directly, and rendered output is
+// always assembled from typed fields of retrieved records - the assistant has
+// no way to state a fact that is not present in the local Foomatic artifacts.
+
+import type { Printer, PrinterSummary, DriverSummary, DriverRecord } from "@/lib/foomatic/types"
+
+// ---------------------------------------------------------------------------
+// Page context
+
+export type AssistantPageContext =
+  | { pageType: "printer"; route: string; printerId: string }
+  | { pageType: "driver"; route: string; driverId: string }
+  | { pageType: "printer-directory"; route: string }
+  | { pageType: "driver-directory"; route: string }
+  | { pageType: "home"; route: string }
+  | { pageType: "other"; route: string }
+
+// ---------------------------------------------------------------------------
+// Entity references
+
+export interface PrinterCandidate {
+  id: string
+  manufacturer: string
+  model: string
+  score: number
+}
+
+export type PrinterRef =
+  | { kind: "resolved"; id: string }
+  | { kind: "context" }
+  | { kind: "ambiguous"; text: string; candidates: PrinterCandidate[]; total: number }
+  | { kind: "unresolved"; text: string; suggestions: PrinterCandidate[] }
+
+export type DriverRef =
+  | { kind: "resolved"; id: string }
+  | { kind: "context" }
+  | { kind: "same-as"; printer: PrinterRef }
+  | { kind: "family"; family: string; members: string[] }
+  | { kind: "unresolved"; text: string; suggestions: string[] }
+
+// ---------------------------------------------------------------------------
+// Capability filters
+//
+// Unknown never means false: every filter selects on known-positive (or
+// known-negative, for mono) values only. Records whose field is unrecorded
+// are excluded from the result AND counted separately, so responses can say
+// "N more printers don't record this" instead of implying absence.
+
+export interface PdlFilter {
+  // Minimum language level when the user named one ("PostScript 3", "PCL 6").
+  minLevel?: number
+}
+
+export interface CapabilityFilters {
+  color?: boolean
+  type?: "laser" | "inkjet" | "dot-matrix"
+  minDpi?: number
+  postscript?: PdlFilter
+  pcl?: PdlFilter
+  support?: "perfect" | "good"
+  manufacturer?: string
+  // Recognized so duplex queries are understood, but the current dataset
+  // records duplex for zero printers - execution reports INSUFFICIENT_DATA
+  // instead of pretending an empty result means "no duplex printers exist".
+  duplex?: true
+}
+
+export type BetterDimension = "support" | "similarity" | "resolution" | "drivers"
+
+// ---------------------------------------------------------------------------
+// Typed query IR
+
+export type GeneralInfoTopic = "support-grades" | "similarity" | "assistant-help"
+
+export type AssistantQuery =
+  | { intent: "PRINTER_LOOKUP"; printer: PrinterRef }
+  | {
+      intent: "CAPABILITY_SEARCH"
+      filters: CapabilityFilters
+      // Constraint words the parser recognized as constraints but cannot map
+      // to any catalogue field ("purple", "wireless"). Never dropped silently.
+      unapplied: string[]
+      // True when phrased as a recommendation request ("recommend", "best").
+      // With no filters this must clarify, never rank.
+      recommend: boolean
+    }
+  | {
+      intent: "SIMILAR_PRINTERS"
+      printer: PrinterRef
+      filters: CapabilityFilters
+      unapplied: string[]
+      // "better alternatives": undefined = plain similarity request;
+      // "unspecified" = user said better without a dimension -> clarify.
+      better?: BetterDimension | "unspecified"
+    }
+  | { intent: "EXPLANATION"; source: PrinterRef; candidate: PrinterRef | null }
+  | { intent: "SUPPORT_QUERY"; printer: PrinterRef }
+  | { intent: "DRIVER_LOOKUP"; printer: PrinterRef }
+  | { intent: "DRIVER_SEARCH"; driver: DriverRef }
+  | { intent: "COMPARISON"; printers: [PrinterRef, PrinterRef] }
+  | { intent: "GENERAL_INFO"; topic: GeneralInfoTopic }
+  | { intent: "UNSUPPORTED"; reason: "out-of-domain" | "empty" | "unclear" }
+
+// ---------------------------------------------------------------------------
+// Execution results
+
+export type ResultState =
+  | "SUCCESS"
+  | "NO_MATCHES"
+  | "AMBIGUOUS"
+  | "INSUFFICIENT_DATA"
+  | "UNSUPPORTED"
+  | "ERROR"
+
+export interface FilterDiagnostics {
+  // Human-readable name of the constraint ("colour", "laser", "600+ dpi").
+  label: string
+  matched: number
+  excludedKnown: number
+  excludedUnknown: number
+}
+
+export interface Relaxation {
+  droppedLabel: string
+  resultCount: number
+  query: string
+}
+
+export interface SearchDiagnostics {
+  filters: FilterDiagnostics[]
+  unapplied: string[]
+  // Filters that could not be evaluated because the catalogue records the
+  // field for (almost) no printers - currently only duplex.
+  insufficient: string[]
+  relaxations: Relaxation[]
+  orderingLabel: string | null
+  catalogSize: number
+}
+
+export interface RecommendationEntry {
+  // Schema of public/foomatic-db/recommendations/<id>.json entries
+  // (docs/foomatic-data-formats.md). Produced by PR #224's pipeline;
+  // consumed verbatim - never re-scored or re-ranked here.
+  id: string
+  score: number
+  sharedFeatures: string[]
+  manufacturer?: string
+  model?: string
+  status: string
+  type: string
+  driverCount: number
+}
+
+export type Execution =
+  | { kind: "printer-details"; state: ResultState; summary: PrinterSummary; printer: Printer | null }
+  | {
+      kind: "search-results"
+      state: ResultState
+      matches: PrinterSummary[]
+      total: number
+      diagnostics: SearchDiagnostics
+      recommend: boolean
+    }
+  | {
+      kind: "similar"
+      state: ResultState
+      source: PrinterSummary
+      entries: RecommendationEntry[]
+      totalBeforeFilters: number
+      diagnostics: SearchDiagnostics | null
+      better: BetterDimension | null
+      // For the resolution dimension: the anchor's own recorded maxDpi.
+      sourceMaxDpi: number | null
+    }
+  | { kind: "explanation"; state: ResultState; source: PrinterSummary; entry: RecommendationEntry }
+  | { kind: "explanation-none"; state: "NO_MATCHES"; source: PrinterSummary; candidateName: string }
+  | { kind: "support"; state: ResultState; summary: PrinterSummary; printer: Printer | null }
+  | { kind: "driver-lookup"; state: ResultState; summary: PrinterSummary; printer: Printer }
+  | {
+      kind: "driver-search"
+      state: ResultState
+      driver: DriverRecord
+      // Present for "same driver as X": names the interpretation used.
+      anchor: PrinterSummary | null
+      anchorDriverName: string | null
+    }
+  | { kind: "comparison"; state: ResultState; a: Printer; b: Printer }
+  | { kind: "clarify"; state: "AMBIGUOUS"; question: ClarifyQuestion }
+  | { kind: "info"; state: "SUCCESS"; topic: GeneralInfoTopic }
+  | { kind: "insufficient"; state: "INSUFFICIENT_DATA"; message: InsufficientReason }
+  | { kind: "entity-miss"; state: "NO_MATCHES"; text: string; suggestions: PrinterCandidate[]; driverSuggestions: string[] }
+  | { kind: "unsupported"; state: "UNSUPPORTED"; reason: "out-of-domain" | "empty" | "unclear" }
+  | { kind: "error"; state: "ERROR"; retryQuery: string }
+
+export type InsufficientReason =
+  | { topic: "duplex"; catalogSize: number }
+  | { topic: "no-recommendation-data"; printerName: string }
+  | { topic: "field-unrecorded"; printerName: string; fieldLabel: string }
+
+export type ClarifyQuestion =
+  | { topic: "printer-ambiguous"; text: string; candidates: PrinterCandidate[]; total: number }
+  | { topic: "criteria-needed" }
+  | { topic: "better-dimension"; anchorName: string }
+  | { topic: "driver-family"; family: string; members: string[] }
+  | { topic: "driver-unresolved"; text: string; suggestions: string[] }
+  | { topic: "context-needed"; subject: "printer" | "driver"; alternative?: Chip }
+  | { topic: "explanation-candidate"; sourceName: string; topRecommendations: RecommendationEntry[] }
+
+// ---------------------------------------------------------------------------
+// Response plan (typed blocks; the UI renders these with React only)
+
+export interface PrinterCardData {
+  id: string
+  manufacturer: string
+  model: string
+  status: string
+  type?: string
+  driverCount?: number
+  // Present only for recommendation-backed cards.
+  score?: number
+  tierLabel?: string
+  tierTone?: "high" | "good" | "moderate" | "limited"
+  // Known capability chips ("Colour", "600 dpi") - only rendered for
+  // established values, never for unknowns.
+  features?: string[]
+}
+
+export interface DriverCardData {
+  id: string
+  name: string
+  supplier?: string | null
+  type?: string | null
+  printerCount: number
+}
+
+export interface ComparisonRow {
+  label: string
+  a: string
+  b: string
+}
+
+export interface Chip {
+  label: string
+  query: string
+}
+
+export type ResponseBlock =
+  | { kind: "text"; text: string }
+  | { kind: "list"; title: string; items: string[] }
+  | { kind: "printer-cards"; printers: PrinterCardData[] }
+  | { kind: "driver-card"; driver: DriverCardData }
+  | { kind: "comparison"; aName: string; bName: string; rows: ComparisonRow[] }
+  | { kind: "chips"; chips: Chip[] }
+
+export interface ResponsePlan {
+  blocks: ResponseBlock[]
+}
+
+// ---------------------------------------------------------------------------
+// Data access
+
+export interface AssistantData {
+  getCatalog(): Promise<PrinterSummary[]>
+  getPrinter(id: string): Promise<Printer | null>
+  getRecommendations(id: string): Promise<RecommendationEntry[]>
+  getDriversMap(): Promise<DriverSummary[]>
+  getDriver(id: string): Promise<DriverRecord | null>
+}
diff --git a/lib/foomatic/__tests__/catalog-artifact.test.ts b/lib/foomatic/__tests__/catalog-artifact.test.ts
new file mode 100644
index 00000000..9261042d
--- /dev/null
+++ b/lib/foomatic/__tests__/catalog-artifact.test.ts
@@ -0,0 +1,119 @@
+import fs from "node:fs"
+import path from "node:path"
+import { beforeAll, describe, expect, it } from "vitest"
+import { toPrinterSummary } from "../catalog"
+import type { Printer, PrinterSummary } from "../types"
+
+// Validates the generated printersMap.json artifact against its source of
+// truth (printers.json) via the same builder the pipeline uses.
+//
+// These artifacts are gitignored build outputs, so this suite skips when they
+// are absent (e.g. CI runs `yarn test` before `yarn generate`, and a fresh
+// checkout has no generated data). Locally, run the pipeline first:
+//   yarn tsx scripts/foomatic/split-printers.ts
+// Skipping is not a pass for the artifact itself — the unit tests in
+// catalog.test.ts always run and pin the builder's behavior.
+
+const DB_DIR = path.join(process.cwd(), "public", "foomatic-db")
+const PRINTERS_PATH = path.join(DB_DIR, "printers.json")
+const MAP_PATH = path.join(DB_DIR, "printersMap.json")
+
+const artifactsPresent = fs.existsSync(PRINTERS_PATH) && fs.existsSync(MAP_PATH)
+
+const KNOWN_TYPES = new Set(["laser", "inkjet", "dot-matrix", "unknown"])
+const KNOWN_STATUSES = new Set(["Perfect", "Mostly", "Unsupported", "Unknown"])
+
+describe.skipIf(!artifactsPresent)("generated printersMap.json artifact", () => {
+  let source: Printer[]
+  let rawMap: string
+  let records: PrinterSummary[]
+
+  beforeAll(() => {
+    source = (JSON.parse(fs.readFileSync(PRINTERS_PATH, "utf8")) as { printers: Printer[] }).printers
+    rawMap = fs.readFileSync(MAP_PATH, "utf8")
+    records = (JSON.parse(rawMap) as { printers: PrinterSummary[] }).printers
+  })
+
+  it("is minified", () => {
+    expect(rawMap.startsWith('{"printers":[{')).toBe(true)
+  })
+
+  it("has exactly one record per source printer, with unique ids", () => {
+    expect(records.length).toBe(source.length)
+    const ids = new Set(records.map(record => record.id))
+    expect(ids.size).toBe(records.length)
+    for (const record of records) {
+      expect(record.id.length).toBeGreaterThan(0)
+    }
+  })
+
+  it("matches the builder output for every source record, byte for byte", () => {
+    const mismatches: string[] = []
+    for (let i = 0; i < source.length; i++) {
+      const expected = JSON.stringify(toPrinterSummary(source[i]))
+      const actual = JSON.stringify(records[i])
+      if (expected !== actual) {
+        mismatches.push(source[i].id)
+      }
+    }
+    expect(mismatches).toEqual([])
+  })
+
+  it("preserves tri-state and enum domains", () => {
+    for (const record of records) {
+      expect([true, false, "unknown"]).toContain(record.color)
+      expect(KNOWN_TYPES.has(record.type ?? ""), `type ${record.type} (${record.id})`).toBe(true)
+      expect(KNOWN_STATUSES.has(record.status ?? ""), `status ${record.status} (${record.id})`).toBe(true)
+    }
+  })
+
+  it("emits capability fields only with established values, and never duplex", () => {
+    for (const record of records) {
+      expect("duplex" in record).toBe(false)
+      if ("maxDpi" in record) {
+        // getMaxDpi() returns null for non-positive resolutions, so a stored
+        // maxDpi is always a positive number.
+        expect(Number.isFinite(record.maxDpi), `maxDpi ${record.maxDpi} (${record.id})`).toBe(true)
+        expect(record.maxDpi!).toBeGreaterThan(0)
+      }
+      for (const field of ["psLevel", "pclLevel"] as const) {
+        // 0 is a real domain value here: the printer declares the language
+        // node but its level string did not resolve (getPSLevel/getPCLLevel).
+        if (field in record) {
+          const value = record[field] as number
+          expect(Number.isFinite(value), `${field} ${value} (${record.id})`).toBe(true)
+          expect(value).toBeGreaterThanOrEqual(0)
+        }
+      }
+      if ("cs" in record) {
+        expect(Array.isArray(record.cs)).toBe(true)
+        expect(record.cs!.length).toBeGreaterThan(0)
+        for (const token of record.cs!) {
+          expect(typeof token).toBe("string")
+          expect(token.length).toBeGreaterThan(0)
+        }
+      }
+      if ("rd" in record) {
+        expect(typeof record.rd).toBe("string")
+        expect(record.rd!.length).toBeGreaterThan(0)
+        expect(record.rd!.startsWith("driver/")).toBe(false)
+      }
+    }
+  })
+
+  it("has real coverage for every capability field", () => {
+    const coverage = {
+      maxDpi: records.filter(record => "maxDpi" in record).length,
+      psLevel: records.filter(record => "psLevel" in record).length,
+      pclLevel: records.filter(record => "pclLevel" in record).length,
+      cs: records.filter(record => "cs" in record).length,
+      rd: records.filter(record => "rd" in record).length,
+    }
+    // Logged so pipeline runs leave a coverage trail in test output.
+    console.log(`printersMap capability coverage (${records.length} records):`, coverage)
+    for (const [field, count] of Object.entries(coverage)) {
+      expect(count, `expected some coverage for ${field}`).toBeGreaterThan(0)
+      expect(count).toBeLessThanOrEqual(records.length)
+    }
+  })
+})
diff --git a/lib/foomatic/__tests__/catalog.test.ts b/lib/foomatic/__tests__/catalog.test.ts
new file mode 100644
index 00000000..a292a607
--- /dev/null
+++ b/lib/foomatic/__tests__/catalog.test.ts
@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest"
+import { toPrinterSummary } from "../catalog"
+import type { Driver, Printer } from "../types"
+
+// Minimal factory mirroring the style of printer-attributes.test.ts: every test
+// states only the fields it cares about.
+const printer = (overrides: Partial<Printer> = {}): Printer => ({
+  id: "Test-Printer",
+  manufacturer: "Test",
+  model: "Printer",
+  ...overrides,
+})
+
+const drivers = (count: number): Driver[] =>
+  Array.from({ length: count }, (_, i) => ({ id: `driver/d${i}`, name: `d${i}` }))
+
+// Keys the projection may ever emit. The artifact test cross-checks the real
+// generated file against this same builder, so a new key added here without a
+// deliberate schema decision should fail review, not slip through.
+const ALLOWED_KEYS = new Set([
+  "id", "manufacturer", "model", "type", "status", "functionality",
+  "driverCount", "color", "maxDpi", "psLevel", "pclLevel", "cs", "rd",
+])
+
+describe("toPrinterSummary base fields (legacy printersMap projection)", () => {
+  it("preserves the original projection defaults for a bare record", () => {
+    // These defaults are what split-printers.ts emitted before the capability
+    // extension; existing consumers (directory page, static params, search
+    // index builder) rely on them.
+    expect(toPrinterSummary(printer())).toEqual({
+      id: "Test-Printer",
+      manufacturer: "Test",
+      model: "Printer",
+      type: "unknown",
+      status: "Unknown",
+      functionality: "?",
+      driverCount: 0,
+      color: "unknown",
+    })
+  })
+
+  it("copies known base fields verbatim", () => {
+    const summary = toPrinterSummary(printer({
+      type: "laser",
+      status: "Perfect",
+      functionality: "A",
+      drivers: drivers(3),
+      color: false,
+    }))
+    expect(summary.type).toBe("laser")
+    expect(summary.status).toBe("Perfect")
+    expect(summary.functionality).toBe("A")
+    expect(summary.driverCount).toBe(3)
+    expect(summary.color).toBe(false)
+  })
+
+  it("preserves the color tri-state without collapsing unknown", () => {
+    expect(toPrinterSummary(printer({ color: true })).color).toBe(true)
+    expect(toPrinterSummary(printer({ color: false })).color).toBe(false)
+    expect(toPrinterSummary(printer({ color: "unknown" })).color).toBe("unknown")
+    expect(toPrinterSummary(printer({})).color).toBe("unknown")
+  })
+})
+
+describe("toPrinterSummary capability fields (omit-when-unknown)", () => {
+  it("copies numeric capability fields when the source records them", () => {
+    const summary = toPrinterSummary(printer({ maxDpi: 600, psLevel: 2, pclLevel: 5 }))
+    expect(summary.maxDpi).toBe(600)
+    expect(summary.psLevel).toBe(2)
+    expect(summary.pclLevel).toBe(5)
+  })
+
+  it("omits numeric capability fields for null and undefined, not emitting null", () => {
+    for (const summary of [
+      toPrinterSummary(printer({ maxDpi: null, psLevel: null, pclLevel: null })),
+      toPrinterSummary(printer({})),
+    ]) {
+      expect("maxDpi" in summary).toBe(false)
+      expect("psLevel" in summary).toBe(false)
+      expect("pclLevel" in summary).toBe(false)
+    }
+  })
+
+  it("copies commandset tokens only when non-empty, as an independent array", () => {
+    const tokens = ["POSTSCRIPT", "PCL5E"]
+    const summary = toPrinterSummary(printer({ commandsetTokens: tokens }))
+    expect(summary.cs).toEqual(["POSTSCRIPT", "PCL5E"])
+    expect(summary.cs).not.toBe(tokens)
+
+    expect("cs" in toPrinterSummary(printer({ commandsetTokens: [] }))).toBe(false)
+    expect("cs" in toPrinterSummary(printer({}))).toBe(false)
+  })
+
+  it("normalizes the recommended driver onto its family for rd", () => {
+    // Same normalization the similarity features use (driver-family.ts):
+    // the "driver/" prefix is stripped and prefix rules collapse variants.
+    expect(toPrinterSummary(printer({ recommended_driver: "driver/ljet4" })).rd).toBe("laserjet")
+    expect(toPrinterSummary(printer({ recommended_driver: "driver/gimp-print-ijs" })).rd).toBe("gutenprint")
+    expect(toPrinterSummary(printer({ recommended_driver: "driver/Postscript-hp" })).rd).toBe("postscript")
+    expect(toPrinterSummary(printer({ recommended_driver: "driver/epson" })).rd).toBe("epson")
+  })
+
+  it("omits rd when no recommended driver is recorded", () => {
+    expect("rd" in toPrinterSummary(printer({}))).toBe(false)
+    expect("rd" in toPrinterSummary(printer({ recommended_driver: "" }))).toBe(false)
+    expect("rd" in toPrinterSummary(printer({ recommended_driver: "   " }))).toBe(false)
+  })
+})
+
+describe("toPrinterSummary exclusions and determinism", () => {
+  it("never emits duplex, even if the source were to record it", () => {
+    // Approved design decision: duplex is recorded for zero printers upstream,
+    // so it is not part of the catalogue and must not leak in if upstream data
+    // ever starts carrying it without a deliberate schema decision here.
+    const summary = toPrinterSummary(printer({ duplex: true }))
+    expect("duplex" in summary).toBe(false)
+  })
+
+  it("emits no keys outside the documented schema", () => {
+    const summary = toPrinterSummary(printer({
+      maxDpi: 1200,
+      psLevel: 3,
+      pclLevel: 6,
+      commandsetTokens: ["PCLXL"],
+      recommended_driver: "driver/hplip",
+      duplex: "unknown",
+      notes: "<b>html</b>",
+      hasOwnEntry: false,
+    }))
+    for (const key of Object.keys(summary)) {
+      expect(ALLOWED_KEYS.has(key), `unexpected key ${key}`).toBe(true)
+    }
+  })
+
+  it("is deterministic, including key order", () => {
+    const input = printer({
+      maxDpi: 600,
+      psLevel: 2,
+      commandsetTokens: ["POSTSCRIPT"],
+      recommended_driver: "driver/hplip",
+    })
+    expect(JSON.stringify(toPrinterSummary(input))).toBe(JSON.stringify(toPrinterSummary(input)))
+  })
+})
diff --git a/lib/foomatic/__tests__/driver-family.test.ts b/lib/foomatic/__tests__/driver-family.test.ts
new file mode 100644
index 00000000..a47e1905
--- /dev/null
+++ b/lib/foomatic/__tests__/driver-family.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest"
+import {
+  normalizeDriverFamily,
+  getRecommendedDriverFamily,
+  getSupportedDriverFamilies,
+} from "../driver-family"
+import type { Printer } from "../types"
+
+describe("normalizeDriverFamily", () => {
+  it("collapses known driver name prefixes into families", () => {
+    expect(normalizeDriverFamily("Postscript-hp")).toBe("postscript")
+    expect(normalizeDriverFamily("hpijs-pcl5")).toBe("hpijs")
+    expect(normalizeDriverFamily("gimp-print-ijs")).toBe("gutenprint")
+    expect(normalizeDriverFamily("ljet4")).toBe("laserjet")
+  })
+
+  it("strips a driver/ id prefix before matching", () => {
+    expect(normalizeDriverFamily("driver/Postscript")).toBe("postscript")
+  })
+
+  it("lowercases unrecognized driver names instead of dropping them", () => {
+    expect(normalizeDriverFamily("SomeNewDriver")).toBe("somenewdriver")
+  })
+})
+
+describe("getRecommendedDriverFamily", () => {
+  it("normalizes the printer's recommended driver", () => {
+    const printer = { recommended_driver: "driver/hpijs-pcl5" } as Printer
+    expect(getRecommendedDriverFamily(printer)).toBe("hpijs")
+  })
+
+  it("returns null when there is no recommended driver", () => {
+    expect(getRecommendedDriverFamily({} as Printer)).toBeNull()
+  })
+})
+
+describe("getSupportedDriverFamilies", () => {
+  it("de-dupes driver families across the printer's driver list", () => {
+    const printer = {
+      drivers: [
+        { id: "driver/a", name: "Postscript-a" },
+        { id: "driver/b", name: "Postscript-b" },
+        { id: "driver/c", name: "hpijs" },
+      ],
+    } as Printer
+
+    expect(getSupportedDriverFamilies(printer).sort()).toEqual(["hpijs", "postscript"])
+  })
+
+  it("returns an empty array when the printer has no drivers", () => {
+    expect(getSupportedDriverFamilies({} as Printer)).toEqual([])
+  })
+})
diff --git a/lib/foomatic/__tests__/printer-attributes.test.ts b/lib/foomatic/__tests__/printer-attributes.test.ts
new file mode 100644
index 00000000..acfe2ebc
--- /dev/null
+++ b/lib/foomatic/__tests__/printer-attributes.test.ts
@@ -0,0 +1,213 @@
+import { describe, expect, it } from "vitest"
+import {
+  getFunctionalityStatus,
+  getPrinterType,
+  normalizeCommandsetToken,
+  getCommandsetTokens,
+  getBooleanCapability,
+  getColorCapability,
+  getMaxDpi,
+  getPSLevel,
+  getPCLLevel,
+  encodeFunctionality,
+} from "../printer-attributes"
+
+describe("getFunctionalityStatus", () => {
+  it("maps A to Perfect", () => {
+    expect(getFunctionalityStatus("A")).toBe("Perfect")
+  })
+
+  it("maps B and C to Mostly", () => {
+    expect(getFunctionalityStatus("B")).toBe("Mostly")
+    expect(getFunctionalityStatus("C")).toBe("Mostly")
+  })
+
+  it("maps missing or '?' functionality to Unknown", () => {
+    expect(getFunctionalityStatus(undefined)).toBe("Unknown")
+    expect(getFunctionalityStatus("?")).toBe("Unknown")
+  })
+
+  it("maps any other code to Unsupported", () => {
+    expect(getFunctionalityStatus("D")).toBe("Unsupported")
+    expect(getFunctionalityStatus("")).toBe("Unknown")
+  })
+})
+
+describe("encodeFunctionality", () => {
+  it("encodes the four functionality grades to their documented weights", () => {
+    expect(encodeFunctionality("A")).toBe(1.0)
+    expect(encodeFunctionality("B")).toBe(0.66)
+    expect(encodeFunctionality("C")).toBe(0.33)
+    expect(encodeFunctionality("D")).toBe(0.0)
+  })
+
+  it("is case-insensitive", () => {
+    expect(encodeFunctionality("a")).toBe(1.0)
+  })
+
+  it("defaults to 0 for missing values", () => {
+    expect(encodeFunctionality(undefined)).toBe(0.0)
+  })
+})
+
+describe("getPrinterType", () => {
+  it("detects inkjet from the mechanism.inkjet key", () => {
+    expect(getPrinterType({ mechanism: { inkjet: {} } })).toBe("inkjet")
+  })
+
+  it("detects laser from the mechanism.laser key", () => {
+    expect(getPrinterType({ mechanism: { laser: {} } })).toBe("laser")
+  })
+
+  it("detects dot-matrix from the mechanism.dotmatrix key", () => {
+    expect(getPrinterType({ mechanism: { dotmatrix: {} } })).toBe("dot-matrix")
+  })
+
+  it("falls back to transfer code 'i' for inkjet and 't' for laser", () => {
+    expect(getPrinterType({ mechanism: { transfer: "i" } })).toBe("inkjet")
+    expect(getPrinterType({ mechanism: { transfer: "t" } })).toBe("laser")
+  })
+
+  it("returns unknown when there is no mechanism data", () => {
+    expect(getPrinterType({})).toBe("unknown")
+    expect(getPrinterType({ mechanism: { transfer: "x" } })).toBe("unknown")
+  })
+})
+
+describe("normalizeCommandsetToken", () => {
+  it("folds PostScript variants to a single canonical token", () => {
+    expect(normalizeCommandsetToken("PostScript")).toBe("POSTSCRIPT")
+    expect(normalizeCommandsetToken("PS2")).toBe("POSTSCRIPT")
+    expect(normalizeCommandsetToken("Adobe PostScript")).toBe("POSTSCRIPT")
+  })
+
+  it("folds PCLXL variants to PCLXL", () => {
+    expect(normalizeCommandsetToken("PCL-XL")).toBe("PCLXL")
+    expect(normalizeCommandsetToken("PCL6")).toBe("PCLXL")
+    expect(normalizeCommandsetToken("HP ENHANCED PCL6")).toBe("PCLXL")
+  })
+
+  it("folds PCL5 variants to PCL5E", () => {
+    expect(normalizeCommandsetToken("PCL5e")).toBe("PCL5E")
+    expect(normalizeCommandsetToken("ENHANCED PCL5")).toBe("PCL5E")
+  })
+
+  it("discards noise tokens", () => {
+    expect(normalizeCommandsetToken("NONE")).toBeNull()
+    expect(normalizeCommandsetToken("RASTER")).toBeNull()
+    expect(normalizeCommandsetToken("")).toBeNull()
+    expect(normalizeCommandsetToken("   ")).toBeNull()
+  })
+
+  it("passes through unrecognized tokens uppercased", () => {
+    expect(normalizeCommandsetToken("escp2")).toBe("ESCP2")
+  })
+})
+
+describe("getCommandsetTokens", () => {
+  it("returns an empty array when there is no autodetect data", () => {
+    expect(getCommandsetTokens({})).toEqual([])
+  })
+
+  it("merges, normalizes, de-dupes, and sorts commandsets from multiple sources", () => {
+    const printer = {
+      autodetect: {
+        general: { commandset: "PostScript,PCL6" },
+        usb: { commandset: "PS2" },
+        parallel: { commandset: "PCL-XL" },
+      },
+    }
+
+    expect(getCommandsetTokens(printer)).toEqual(["PCLXL", "POSTSCRIPT"])
+  })
+
+  it("extracts commandsets embedded in an IEEE1284 device ID", () => {
+    const printer = {
+      autodetect: {
+        general: { ieee1284: "MFG:HP;MDL:LaserJet;CMD:PCL,PJL;" },
+      },
+    }
+
+    expect(getCommandsetTokens(printer)).toEqual(["PCL", "PJL"])
+  })
+})
+
+describe("getBooleanCapability", () => {
+  it("recognizes common truthy and falsy text values", () => {
+    expect(getBooleanCapability("yes")).toBe(true)
+    expect(getBooleanCapability("color")).toBe(true)
+    expect(getBooleanCapability("no")).toBe(false)
+    expect(getBooleanCapability("monochrome")).toBe(false)
+  })
+
+  it("passes through native booleans", () => {
+    expect(getBooleanCapability(true)).toBe(true)
+    expect(getBooleanCapability(false)).toBe(false)
+  })
+
+  it("returns 'unknown' for missing or unrecognized values", () => {
+    expect(getBooleanCapability(undefined)).toBe("unknown")
+    expect(getBooleanCapability("maybe")).toBe("unknown")
+  })
+})
+
+describe("getColorCapability", () => {
+  it("returns true when mechanism has a color key", () => {
+    expect(getColorCapability({ mechanism: { color: {} } })).toBe(true)
+  })
+
+  it("returns false when mechanism exists but has no color key", () => {
+    expect(getColorCapability({ mechanism: { laser: {} } })).toBe(false)
+  })
+
+  it("falls back to top-level color fields when there is no mechanism data", () => {
+    expect(getColorCapability({ color: "yes" })).toBe(true)
+    expect(getColorCapability({ colors: "no" })).toBe(false)
+    expect(getColorCapability({})).toBe("unknown")
+  })
+})
+
+describe("getMaxDpi", () => {
+  it("returns the larger of x/y resolution", () => {
+    expect(getMaxDpi({ mechanism: { resolution: { dpi: { x: 600, y: 1200 } } } })).toBe(1200)
+  })
+
+  it("returns null when there is no resolution data", () => {
+    expect(getMaxDpi({})).toBeNull()
+  })
+
+  it("returns null when resolution is zero", () => {
+    expect(getMaxDpi({ mechanism: { resolution: { dpi: { x: 0, y: 0 } } } })).toBeNull()
+  })
+})
+
+describe("getPSLevel", () => {
+  it("parses numeric and roman-numeral PostScript levels", () => {
+    expect(getPSLevel({ lang: { postscript: "3" } })).toBe(3)
+    expect(getPSLevel({ lang: { postscript: "II" } })).toBe(2)
+    expect(getPSLevel({ lang: { postscript: { level: "1" } } })).toBe(1)
+  })
+
+  it("returns 0 for unrecognized non-empty levels", () => {
+    expect(getPSLevel({ lang: { postscript: "weird" } })).toBe(0)
+  })
+
+  it("returns null when PostScript is not supported at all", () => {
+    expect(getPSLevel({})).toBeNull()
+    expect(getPSLevel({ lang: { postscript: "?" } })).toBeNull()
+  })
+})
+
+describe("getPCLLevel", () => {
+  it("detects PCL6", () => {
+    expect(getPCLLevel({ lang: { pcl: "6" } })).toBe(6)
+  })
+
+  it("detects PCL5 variants", () => {
+    expect(getPCLLevel({ lang: { pcl: "5e" } })).toBe(5)
+  })
+
+  it("returns null when PCL is not supported at all", () => {
+    expect(getPCLLevel({})).toBeNull()
+  })
+})
diff --git a/lib/foomatic/__tests__/scoring.test.ts b/lib/foomatic/__tests__/scoring.test.ts
new file mode 100644
index 00000000..cd20eed2
--- /dev/null
+++ b/lib/foomatic/__tests__/scoring.test.ts
@@ -0,0 +1,235 @@
+import { describe, expect, it } from "vitest"
+import {
+  COLOR_CONFLICT_PENALTY,
+  CONFIDENCE_GOOD_THRESHOLD,
+  CONFIDENCE_HIGH_THRESHOLD,
+  CONFIDENCE_MODERATE_THRESHOLD,
+  EVIDENCE_TAU,
+  MIN_SIMILARITY_SCORE,
+  RESOLUTION_CONFLICT_PENALTY,
+  RESOLUTION_CONFLICT_RATIO,
+  TYPE_CONFLICT_PENALTY,
+  confidenceTier,
+  conflictPenalty,
+  evidenceWeight,
+  overlapCount,
+  resolutionTier,
+  scoreThenIdComparator,
+} from "../scoring"
+import type { Printer } from "../types"
+
+const printer = (overrides: Partial<Printer>): Printer =>
+  ({ id: "test", manufacturer: "Test", model: "T", ...overrides }) as Printer
+
+describe("evidenceWeight", () => {
+  it("gives zero confidence to zero overlap", () => {
+    expect(evidenceWeight(0)).toBe(0)
+  })
+
+  it("is strictly monotonic in the amount of evidence", () => {
+    let prev = evidenceWeight(0)
+    for (let k = 1; k <= 20; k++) {
+      const w = evidenceWeight(k)
+      expect(w).toBeGreaterThan(prev)
+      prev = w
+    }
+  })
+
+  it("never exceeds 1, and stays below 1 across the realistic evidence range", () => {
+    // In exact arithmetic 1 - exp(-k/tau) < 1 for all finite k, but in float64
+    // the difference underflows to exactly 1 once exp(-k/tau) < 2^-53. The
+    // guarantee that matters is: <= 1 always, and strictly < 1 for overlaps a
+    // real printer pair can produce (well past the 463-feature space).
+    expect(evidenceWeight(50)).toBeLessThan(1)
+    expect(evidenceWeight(10000)).toBeLessThanOrEqual(1)
+  })
+
+  it("matches the documented damping curve for tau", () => {
+    expect(evidenceWeight(EVIDENCE_TAU)).toBeCloseTo(1 - Math.exp(-1), 10)
+  })
+
+  it("keeps a single-signal pair below the score floor even at perfect cosine", () => {
+    // The invariant that removes "recommended because both use a catch-all
+    // driver": cosine can be at most 1, so a one-dimension overlap can never
+    // clear MIN_SIMILARITY_SCORE.
+    expect(1.0 * evidenceWeight(1)).toBeLessThan(MIN_SIMILARITY_SCORE)
+  })
+
+  it("ranks a well-evidenced match above a thin one at equal cosine", () => {
+    expect(0.9 * evidenceWeight(8)).toBeGreaterThan(1.0 * evidenceWeight(1))
+  })
+})
+
+describe("overlapCount", () => {
+  it("returns zero when the vectors share no active dimension", () => {
+    expect(overlapCount([1, 0, 2], [0, 3, 0])).toBe(0)
+  })
+
+  it("counts only dimensions active in both vectors", () => {
+    expect(overlapCount([1, 2, 0, 4], [5, 0, 6, 7])).toBe(2)
+  })
+
+  it("ignores the magnitude of the weights", () => {
+    expect(overlapCount([0.001, 9], [100, 0.5])).toBe(2)
+  })
+})
+
+describe("conflictPenalty", () => {
+  it("is neutral when nothing conflicts", () => {
+    const a = printer({ type: "laser", color: true, maxDpi: 600 })
+    const b = printer({ type: "laser", color: true, maxDpi: 1200 })
+    expect(conflictPenalty(a, b)).toBe(1)
+  })
+
+  it("penalizes a known mechanism-type conflict", () => {
+    const a = printer({ type: "inkjet" })
+    const b = printer({ type: "laser" })
+    expect(conflictPenalty(a, b)).toBe(TYPE_CONFLICT_PENALTY)
+  })
+
+  it("does not penalize when either type is unknown", () => {
+    expect(conflictPenalty(printer({ type: "unknown" }), printer({ type: "laser" }))).toBe(1)
+    expect(conflictPenalty(printer({}), printer({ type: "laser" }))).toBe(1)
+  })
+
+  it("penalizes colour vs monochrome in both directions", () => {
+    expect(conflictPenalty(printer({ color: true }), printer({ color: false }))).toBe(
+      COLOR_CONFLICT_PENALTY
+    )
+    expect(conflictPenalty(printer({ color: false }), printer({ color: true }))).toBe(
+      COLOR_CONFLICT_PENALTY
+    )
+  })
+
+  it("treats unknown colour as no evidence, not as a conflict", () => {
+    expect(conflictPenalty(printer({ color: "unknown" }), printer({ color: true }))).toBe(1)
+  })
+
+  it("penalizes an extreme resolution gap but not a moderate one", () => {
+    const ratio = RESOLUTION_CONFLICT_RATIO
+    expect(conflictPenalty(printer({ maxDpi: 300 }), printer({ maxDpi: 300 * ratio }))).toBe(
+      RESOLUTION_CONFLICT_PENALTY
+    )
+    expect(
+      conflictPenalty(printer({ maxDpi: 300 }), printer({ maxDpi: 300 * ratio - 1 }))
+    ).toBe(1)
+  })
+
+  it("stacks independent conflicts multiplicatively", () => {
+    const a = printer({ type: "inkjet", color: true, maxDpi: 4800 })
+    const b = printer({ type: "laser", color: false, maxDpi: 300 })
+    expect(conflictPenalty(a, b)).toBeCloseTo(
+      TYPE_CONFLICT_PENALTY * COLOR_CONFLICT_PENALTY * RESOLUTION_CONFLICT_PENALTY,
+      10
+    )
+  })
+
+  it("keeps the combined score inside [0, 1)", () => {
+    const a = printer({ type: "inkjet", color: true, maxDpi: 4800 })
+    const b = printer({ type: "laser", color: false, maxDpi: 300 })
+    const worst = 1.0 * evidenceWeight(500) * conflictPenalty(a, b)
+    expect(worst).toBeGreaterThan(0)
+    expect(worst).toBeLessThan(1)
+  })
+})
+
+describe("resolutionTier", () => {
+  it("returns null when resolution is unknown", () => {
+    expect(resolutionTier(null)).toBeNull()
+    expect(resolutionTier(undefined)).toBeNull()
+  })
+
+  it("assigns tier boundaries inclusively at the top of each range", () => {
+    expect(resolutionTier(300)).toBe("up to 300 dpi")
+    expect(resolutionTier(301)).toBe("300-600 dpi")
+    expect(resolutionTier(600)).toBe("300-600 dpi")
+    expect(resolutionTier(601)).toBe("600-1200 dpi")
+    expect(resolutionTier(1200)).toBe("600-1200 dpi")
+    expect(resolutionTier(1201)).toBe("over 1200 dpi")
+  })
+
+  it("never labels a tier with a bare exact figure", () => {
+    // 720 dpi printers were previously labelled "1200 dpi resolution". Tier
+    // labels must always read as ranges, not as a specific capability claim.
+    for (const dpi of [120, 306, 720, 1440, 5760]) {
+      expect(resolutionTier(dpi)).toMatch(/^(up to|over|\d+-)/)
+    }
+  })
+})
+
+describe("confidenceTier", () => {
+  const LABELS = ["High confidence", "Good match", "Moderate match", "Limited evidence"]
+
+  it("assigns every representable score to exactly one tier", () => {
+    // Scores are rounded to 3 decimals upstream, so sweep that whole domain.
+    for (let i = 0; i <= 1000; i++) {
+      const tier = confidenceTier(i / 1000)
+      expect(LABELS).toContain(tier.label)
+    }
+  })
+
+  it("maps tier boundaries inclusively at the lower edge", () => {
+    expect(confidenceTier(CONFIDENCE_HIGH_THRESHOLD).label).toBe("High confidence")
+    expect(confidenceTier(CONFIDENCE_HIGH_THRESHOLD - 0.001).label).toBe("Good match")
+    expect(confidenceTier(CONFIDENCE_GOOD_THRESHOLD).label).toBe("Good match")
+    expect(confidenceTier(CONFIDENCE_GOOD_THRESHOLD - 0.001).label).toBe("Moderate match")
+    expect(confidenceTier(CONFIDENCE_MODERATE_THRESHOLD).label).toBe("Moderate match")
+    expect(confidenceTier(CONFIDENCE_MODERATE_THRESHOLD - 0.001).label).toBe("Limited evidence")
+  })
+
+  it("covers the observed score range without an unreachable tier", () => {
+    // Measured bounds of the generated artifacts: min 0.351, max 0.991.
+    expect(confidenceTier(0.351).label).toBe("Limited evidence")
+    expect(confidenceTier(0.991).label).toBe("High confidence")
+    // Even a hypothetical perfect score gets similarity wording, never a
+    // claim of exactness: the model measures similarity, not identity.
+    expect(confidenceTier(1.0).label).toBe("High confidence")
+  })
+
+  it("never labels any score as an exact match", () => {
+    for (let i = 0; i <= 1000; i++) {
+      expect(confidenceTier(i / 1000).label).not.toMatch(/exact/i)
+    }
+  })
+
+  it("keeps a single-signal pair out of every tier above Limited evidence", () => {
+    // evidenceWeight(1) caps a one-dimension overlap at ~0.22 even at perfect
+    // cosine, which is below the Moderate threshold.
+    expect(1.0 * evidenceWeight(1)).toBeLessThan(CONFIDENCE_MODERATE_THRESHOLD)
+    expect(confidenceTier(1.0 * evidenceWeight(1)).label).toBe("Limited evidence")
+  })
+
+  it("is deterministic", () => {
+    for (const s of [0, 0.393, 0.5, 0.7, 0.85, 0.991]) {
+      expect(confidenceTier(s)).toEqual(confidenceTier(s))
+    }
+  })
+})
+
+describe("scoreThenIdComparator", () => {
+  const ids = ["Alps-MD-1000", "Canon-BJC-50", "Epson-LQ-570"]
+  const cmp = scoreThenIdComparator<{ index: number; score: number }>((i) => ids[i])
+
+  it("orders by score descending first", () => {
+    const sorted = [
+      { index: 0, score: 0.5 },
+      { index: 1, score: 0.9 },
+    ].sort(cmp)
+    expect(sorted.map((c) => c.index)).toEqual([1, 0])
+  })
+
+  it("breaks exact ties by id ascending, independent of input order", () => {
+    const a = [
+      { index: 2, score: 0.7 },
+      { index: 0, score: 0.7 },
+      { index: 1, score: 0.7 },
+    ].sort(cmp)
+    const b = [
+      { index: 1, score: 0.7 },
+      { index: 2, score: 0.7 },
+      { index: 0, score: 0.7 },
+    ].sort(cmp)
+    expect(a.map((c) => c.index)).toEqual([0, 1, 2])
+    expect(b.map((c) => c.index)).toEqual([0, 1, 2])
+  })
+})
diff --git a/lib/foomatic/__tests__/similarity-math.test.ts b/lib/foomatic/__tests__/similarity-math.test.ts
new file mode 100644
index 00000000..7a7aca89
--- /dev/null
+++ b/lib/foomatic/__tests__/similarity-math.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest"
+import { cosineSimilarity, dotProduct, magnitude, insertTopK } from "../similarity-math"
+import type { ScoredCandidate } from "../similarity-math"
+
+describe("cosineSimilarity", () => {
+  it("returns 1 for identical vectors", () => {
+    const a = [1, 2, 3]
+    expect(cosineSimilarity(a, a, magnitude(a), magnitude(a))).toBeCloseTo(1)
+  })
+
+  it("returns 0 for orthogonal vectors", () => {
+    const a = [1, 0]
+    const b = [0, 1]
+    expect(cosineSimilarity(a, b, magnitude(a), magnitude(b))).toBe(0)
+  })
+
+  it("returns 0 when either magnitude is 0, instead of dividing by zero", () => {
+    const a = [0, 0]
+    const b = [1, 1]
+    expect(cosineSimilarity(a, b, magnitude(a), magnitude(b))).toBe(0)
+  })
+
+  it("scales with the angle between two non-identical vectors", () => {
+    const a = [1, 1]
+    const b = [1, 0]
+    const score = cosineSimilarity(a, b, magnitude(a), magnitude(b))
+    expect(score).toBeGreaterThan(0)
+    expect(score).toBeLessThan(1)
+  })
+})
+
+describe("dotProduct / magnitude", () => {
+  it("computes the dot product element-wise", () => {
+    expect(dotProduct([1, 2, 3], [4, 5, 6])).toBe(32)
+  })
+
+  it("computes the Euclidean magnitude", () => {
+    expect(magnitude([3, 4])).toBe(5)
+  })
+})
+
+describe("insertTopK", () => {
+  it("keeps the list sorted ascending by score while under capacity", () => {
+    const topK: ScoredCandidate[] = []
+    insertTopK(topK, { index: 0, score: 0.5 }, 3)
+    insertTopK(topK, { index: 1, score: 0.2 }, 3)
+    insertTopK(topK, { index: 2, score: 0.8 }, 3)
+
+    expect(topK.map((c) => c.score)).toEqual([0.2, 0.5, 0.8])
+  })
+
+  it("evicts the lowest-scoring candidate once at capacity", () => {
+    const topK: ScoredCandidate[] = [
+      { index: 0, score: 0.1 },
+      { index: 1, score: 0.5 },
+    ]
+
+    insertTopK(topK, { index: 2, score: 0.9 }, 2)
+
+    expect(topK.map((c) => c.index)).toEqual([1, 2])
+  })
+
+  it("does not insert a candidate that scores below the current minimum once at capacity", () => {
+    const topK: ScoredCandidate[] = [
+      { index: 0, score: 0.4 },
+      { index: 1, score: 0.6 },
+    ]
+
+    insertTopK(topK, { index: 2, score: 0.1 }, 2)
+
+    expect(topK.map((c) => c.index)).toEqual([0, 1])
+  })
+})
diff --git a/lib/foomatic/__tests__/utils.test.ts b/lib/foomatic/__tests__/utils.test.ts
new file mode 100644
index 00000000..d72900cb
--- /dev/null
+++ b/lib/foomatic/__tests__/utils.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest"
+import { calculateAccurateStatus } from "../utils"
+import type { Printer, PrinterSummary } from "../types"
+
+describe("calculateAccurateStatus", () => {
+  it("maps grade A/Perfect to Perfect", () => {
+    expect(calculateAccurateStatus({ functionality: "A" } as PrinterSummary)).toBe("Perfect")
+    expect(calculateAccurateStatus({ functionality: "Perfect" } as PrinterSummary)).toBe("Perfect")
+  })
+
+  it("maps grades B/C/Good/Partial to Mostly", () => {
+    expect(calculateAccurateStatus({ functionality: "B" } as PrinterSummary)).toBe("Mostly")
+    expect(calculateAccurateStatus({ functionality: "C" } as PrinterSummary)).toBe("Mostly")
+    expect(calculateAccurateStatus({ functionality: "Good" } as PrinterSummary)).toBe("Mostly")
+    expect(calculateAccurateStatus({ functionality: "Partial" } as PrinterSummary)).toBe("Mostly")
+  })
+
+  it("is case-insensitive on the functionality grade", () => {
+    expect(calculateAccurateStatus({ functionality: "a" } as PrinterSummary)).toBe("Perfect")
+  })
+
+  it("treats missing/unknown functionality with no drivers as Unsupported", () => {
+    expect(calculateAccurateStatus({ functionality: "?", driverCount: 0 } as PrinterSummary)).toBe(
+      "Unsupported"
+    )
+    expect(
+      calculateAccurateStatus({ functionality: "unknown", driverCount: 0 } as PrinterSummary)
+    ).toBe("Unsupported")
+  })
+
+  it("treats missing/unknown functionality with drivers present as Unknown", () => {
+    expect(calculateAccurateStatus({ functionality: "?", driverCount: 2 } as PrinterSummary)).toBe(
+      "Unknown"
+    )
+  })
+
+  it("falls back to driver count when the functionality grade is unrecognized", () => {
+    expect(calculateAccurateStatus({ functionality: "X", driverCount: 0 } as PrinterSummary)).toBe(
+      "Unsupported"
+    )
+    expect(calculateAccurateStatus({ functionality: "X", driverCount: 1 } as PrinterSummary)).toBe(
+      "Unknown"
+    )
+  })
+
+  it("derives driver count from the full Printer.drivers array when driverCount is absent", () => {
+    const printer = {
+      status: "?",
+      drivers: [{ id: "driver/a", name: "a" }],
+    } as unknown as Printer
+
+    expect(calculateAccurateStatus(printer)).toBe("Unknown")
+  })
+
+  it("falls back to the Printer.status field when functionality is absent", () => {
+    const printer = { status: "A", drivers: [] } as unknown as Printer
+    expect(calculateAccurateStatus(printer)).toBe("Perfect")
+  })
+})
diff --git a/lib/foomatic/catalog.ts b/lib/foomatic/catalog.ts
new file mode 100644
index 00000000..3a524887
--- /dev/null
+++ b/lib/foomatic/catalog.ts
@@ -0,0 +1,55 @@
+// Builder for the printersMap.json catalogue projection.
+//
+// This module is the single source of truth for the shape of a catalogue
+// record: split-printers.ts calls it for every printer, and the tests in
+// __tests__/catalog.test.ts and __tests__/catalog-artifact.test.ts validate
+// both the builder and the generated artifact against it.
+//
+// Field semantics: the capability fields (maxDpi, psLevel, pclLevel, cs, rd)
+// are OMITTED when the source data does not establish them, instead of being
+// emitted as null/"unknown"/[]. An absent key always means "not recorded in
+// Foomatic", never "the printer lacks this capability". The tri-state fields
+// carried over from the original projection (color, type) keep their explicit
+// "unknown" values because existing consumers already branch on them.
+//
+// duplex is deliberately NOT part of this projection: the upstream data
+// records it for zero printers, so there is nothing to store or filter on.
+
+import { getRecommendedDriverFamily } from "./driver-family"
+import type { Printer, PrinterSummary } from "./types"
+
+export function toPrinterSummary(printer: Printer): PrinterSummary {
+  const summary: PrinterSummary = {
+    id: printer.id,
+    manufacturer: printer.manufacturer,
+    model: printer.model,
+    type: printer.type || "unknown",
+    status: printer.status || "Unknown",
+    functionality: printer.functionality || "?",
+    driverCount: printer.drivers ? printer.drivers.length : 0,
+    color: printer.color ?? "unknown",
+  }
+
+  if (typeof printer.maxDpi === "number") {
+    summary.maxDpi = printer.maxDpi
+  }
+
+  if (typeof printer.psLevel === "number") {
+    summary.psLevel = printer.psLevel
+  }
+
+  if (typeof printer.pclLevel === "number") {
+    summary.pclLevel = printer.pclLevel
+  }
+
+  if (printer.commandsetTokens && printer.commandsetTokens.length > 0) {
+    summary.cs = [...printer.commandsetTokens]
+  }
+
+  const family = getRecommendedDriverFamily(printer)
+  if (family) {
+    summary.rd = family
+  }
+
+  return summary
+}
diff --git a/lib/foomatic/driver-family.ts b/lib/foomatic/driver-family.ts
new file mode 100644
index 00000000..a97fb379
--- /dev/null
+++ b/lib/foomatic/driver-family.ts
@@ -0,0 +1,64 @@
+// Driver-name normalization shared by the vectorization and similarity stages.
+// Upstream driver entries name the same underlying driver family in many ways
+// (Postscript-hp, gimp-print-ijs, ljet4, ...), so names are collapsed onto a
+// canonical family before they are used as similarity features.
+
+import type { Printer } from "./types"
+
+// Add new entries here to fold another upstream driver naming variant onto an
+// existing family. Order matters: the first matching pattern wins.
+const DRIVER_PREFIX_NORMALIZERS: Array<[RegExp, string]> = [
+  [/^Postscript/i, "postscript"],
+  [/^PDF/i, "pdf"],
+  [/^pxlmono/i, "pxlmono"],
+  [/^pxlcolor/i, "pxlcolor"],
+  [/^foo2zjs/i, "foo2zjs"],
+  [/^foo2hp/i, "foo2hp"],
+  [/^foo2qpdl/i, "foo2qpdl"],
+  [/^hpijs/i, "hpijs"],
+  [/^gutenprint/i, "gutenprint"],
+  [/^gimp-print/i, "gutenprint"],
+  [/^hplip/i, "hplip"],
+  [/^ljet/i, "laserjet"],
+  [/^lj/i, "laserjet"],
+]
+
+export function trim(value: string | undefined): string {
+  return (value ?? "").trim()
+}
+
+export function normalizeDriverFamily(driverName: string): string {
+  const normalized = trim(driverName).replace(/^driver\//i, "")
+
+  for (const [pattern, family] of DRIVER_PREFIX_NORMALIZERS) {
+    if (pattern.test(normalized)) {
+      return family
+    }
+  }
+
+  return normalized.toLowerCase()
+}
+
+export function getRecommendedDriverFamily(printer: Printer): string | null {
+  const driver = trim(printer.recommended_driver)
+
+  if (!driver) {
+    return null
+  }
+
+  return normalizeDriverFamily(driver)
+}
+
+export function getSupportedDriverFamilies(printer: Printer): string[] {
+  const families = new Set<string>()
+
+  for (const driver of printer.drivers ?? []) {
+    const family = normalizeDriverFamily(driver.name)
+
+    if (family) {
+      families.add(family)
+    }
+  }
+
+  return [...families]
+}
diff --git a/lib/foomatic/printer-attributes.ts b/lib/foomatic/printer-attributes.ts
new file mode 100644
index 00000000..aac5a0ed
--- /dev/null
+++ b/lib/foomatic/printer-attributes.ts
@@ -0,0 +1,246 @@
+// Pure helpers for deriving normalized printer attributes from raw
+// foomatic-db XML (already parsed to JSON). Shared between
+// scripts/foomatic/combine-data.ts, the vectorization stage, and their tests.
+
+// Raw printer XML, already parsed to JSON by fast-xml-parser. Shape varies
+// freely per upstream entry and is accessed via deep optional-chained
+// property paths below, so it is intentionally untyped at this boundary.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type RawXmlNode = any
+
+export function getText(value: unknown): string | undefined {
+  if (value === undefined || value === null) {
+    return undefined
+  }
+
+  if (typeof value === "string") {
+    return value.trim() || undefined
+  }
+
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value)
+  }
+
+  if (Array.isArray(value)) {
+    const text = value.map(getText).filter(Boolean).join(", ").trim()
+    return text || undefined
+  }
+
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>
+
+    if (typeof obj.en === "string") {
+      return obj.en.trim() || undefined
+    }
+
+    if (typeof obj["#text"] === "string") {
+      return obj["#text"].trim() || undefined
+    }
+
+    for (const key of Object.keys(obj)) {
+      const nested = getText(obj[key])
+      if (nested) {
+        return nested
+      }
+    }
+  }
+
+  return undefined
+}
+
+export function getFunctionalityStatus(func: string | undefined): string {
+  if (!func || func === "?") {
+    return "Unknown"
+  }
+
+  switch (func) {
+    case "A":
+      return "Perfect"
+    case "B":
+    case "C":
+      return "Mostly"
+    default:
+      return "Unsupported"
+  }
+}
+
+export function getPrinterType(printer: RawXmlNode): string {
+  if (!printer.mechanism) {
+    return "unknown"
+  }
+
+  const mechanism = printer.mechanism
+
+  if (mechanism.inkjet !== undefined) {
+    return "inkjet"
+  }
+
+  if (mechanism.laser !== undefined) {
+    return "laser"
+  }
+
+  if (mechanism.dotmatrix !== undefined) {
+    return "dot-matrix"
+  }
+
+  if (mechanism.transfer === "i") {
+    return "inkjet"
+  }
+
+  if (mechanism.transfer === "t") {
+    return "laser"
+  }
+
+  return "unknown"
+}
+
+export function normalizeCommandsetToken(raw: string): string | null {
+  const t = raw.trim()
+  if (!t) return null
+  const u = t.toUpperCase()
+  if (
+    /^(POSTSCRIPT\d*|ADOBE\s+POSTSCRIPT|ADOBE\s+LEVEL\s+\d+\s+POSTSCRIPT|PS\d?|POSTS$|POSTSCRIP$|POSTSCRI$|POSTSCRIPT\s+EMULATION|POSTSCRIPT\s+LEVEL|POSTSCRIPT\s+LE$|POSTSCRIPT\s+LEV$)/.test(
+      u
+    )
+  )
+    return "POSTSCRIPT"
+  if (/^(PCLXL|PCXL|PCL-XL|PCL6|PCL 6 EMULATION|HP ENHANCED PCL6)$/.test(u)) return "PCLXL"
+  if (/^(PCL5[CE]?\d*|HP ENHANCED PCL5[E]?|ENHANCED PCL5|PCL 5 EMULATION)$/.test(u))
+    return "PCL5E"
+  if (/^(DW-PCL)$/.test(u)) return "PCL"
+  if (
+    /^(NONE|NA|P$|LPT1|1284\.4|DW-$|AUTOMATIC|DOWNLOAD|RASTER|GDI;MDL|PRINTGEAR;PCL;PLJ)$/.test(
+      u
+    )
+  )
+    return null
+  return u
+}
+
+// Normalized autodetect command-set tokens (POSTSCRIPT, PCLXL, ...). These are
+// the machine-comparable tokens used as similarity features, as opposed to the
+// human-readable `commandsets` labels shown in the UI.
+export function getCommandsetTokens(printer: RawXmlNode): string[] {
+  const a = printer.autodetect
+  if (!a) return []
+
+  const rawTokens: string[] = []
+
+  const pushCommaSplit = (val: unknown) => {
+    if (!val) return
+    for (const t of String(val).split(",")) rawTokens.push(t.trim())
+  }
+
+  pushCommaSplit(a.general?.commandset)
+  pushCommaSplit(a.usb?.commandset)
+  pushCommaSplit(a.parallel?.commandset)
+
+  if (a.general?.ieee1284) {
+    const m = String(a.general.ieee1284).match(/CMD:([^;]+)/i)
+    if (m) pushCommaSplit(m[1])
+  }
+
+  const seen = new Set<string>()
+  const result: string[] = []
+  for (const raw of rawTokens) {
+    const norm = normalizeCommandsetToken(raw)
+    if (norm && !seen.has(norm)) {
+      seen.add(norm)
+      result.push(norm)
+    }
+  }
+  return result.sort()
+}
+
+export function getBooleanCapability(value: unknown): boolean | "unknown" {
+  if (value === undefined || value === null) {
+    return "unknown"
+  }
+
+  if (typeof value === "boolean") {
+    return value
+  }
+
+  const text = getText(value)?.toLowerCase()
+  if (!text) {
+    return "unknown"
+  }
+
+  if (["1", "true", "yes", "y", "color", "duplex"].includes(text)) {
+    return true
+  }
+
+  if (["0", "false", "no", "n", "mono", "monochrome", "simplex"].includes(text)) {
+    return false
+  }
+
+  return "unknown"
+}
+
+export function getColorCapability(printer: RawXmlNode): boolean | "unknown" {
+  if (printer.mechanism && "color" in printer.mechanism) {
+    return true
+  }
+
+  if (printer.mechanism && Object.keys(printer.mechanism).length > 0) {
+    return false
+  }
+
+  return getBooleanCapability(
+    printer.color ?? printer.colors ?? printer.colorDevice ?? printer.capabilities?.color
+  )
+}
+
+export function getDuplexCapability(printer: RawXmlNode): boolean | "unknown" {
+  return getBooleanCapability(
+    printer.duplex ?? printer.duplexer ?? printer.capabilities?.duplex
+  )
+}
+
+export function getMaxDpi(printer: RawXmlNode): number | null {
+  const dpi = printer.mechanism?.resolution?.dpi
+  if (!dpi) return null
+  const x = Number(dpi.x ?? dpi["@x"] ?? 0)
+  const y = Number(dpi.y ?? dpi["@y"] ?? 0)
+  const max = Math.max(x, y)
+  return max > 0 ? max : null
+}
+
+export function getPSLevel(printer: RawXmlNode): number | null {
+  const ps = printer.lang?.postscript
+  if (ps === undefined) return null
+  const raw = typeof ps === "object" && ps !== null ? ps["@level"] ?? ps.level ?? "" : String(ps)
+  const s = String(raw).trim()
+  if (!s || s === "?") return null
+  if (["3", "III", "3.0"].includes(s)) return 3
+  if (["2", "II"].includes(s)) return 2
+  if (["1", "I"].includes(s)) return 1
+  return 0
+}
+
+export function getPCLLevel(printer: RawXmlNode): number | null {
+  const pcl = printer.lang?.pcl
+  if (pcl === undefined) return null
+  const raw =
+    typeof pcl === "object" && pcl !== null ? pcl["@level"] ?? pcl.level ?? "" : String(pcl)
+  const s = String(raw).trim()
+  if (!s || s === "?") return null
+  if (/^6|\/6$|,\s*6$|^6\//i.test(s)) return 6
+  if (/5[eEcC]/.test(s) || /^5/.test(s)) return 5
+  if (/^4/.test(s)) return 4
+  if (/^3/.test(s)) return 3
+  return 0
+}
+
+export function encodeFunctionality(value: string | undefined): number {
+  switch ((value ?? "").toUpperCase()) {
+    case "A":
+      return 1.0
+    case "B":
+      return 0.66
+    case "C":
+      return 0.33
+    default:
+      return 0.0
+  }
+}
diff --git a/lib/foomatic/sanitize.ts b/lib/foomatic/sanitize.ts
new file mode 100644
index 00000000..7c97ff5f
--- /dev/null
+++ b/lib/foomatic/sanitize.ts
@@ -0,0 +1,31 @@
+"use client"
+
+import DOMPurify from "dompurify"
+
+// foomatic-db XML accepts external contributions and intentionally embeds
+// HTML in comments/notes fields, so it must be sanitized before rendering.
+const ALLOWED_TAGS = [
+  "a",
+  "b",
+  "strong",
+  "i",
+  "em",
+  "u",
+  "br",
+  "p",
+  "ul",
+  "ol",
+  "li",
+  "code",
+  "span",
+]
+
+const ALLOWED_ATTR = ["href", "title", "target", "rel"]
+
+export function sanitizeFoomaticHtml(html: string): string {
+  return DOMPurify.sanitize(html, {
+    ALLOWED_TAGS,
+    ALLOWED_ATTR,
+    ALLOW_DATA_ATTR: false,
+  })
+}
diff --git a/lib/foomatic/scoring.ts b/lib/foomatic/scoring.ts
new file mode 100644
index 00000000..4e5de96b
--- /dev/null
+++ b/lib/foomatic/scoring.ts
@@ -0,0 +1,126 @@
+// Scoring model for the recommendation engine, shared between
+// scripts/foomatic/compute-similarity.ts and its test suite.
+//
+// The published score is not a bare cosine:
+//
+//   score(a, b) = cos(a, b) * (1 - exp(-k / EVIDENCE_TAU)) * conflictPenalty(a, b)
+//
+// where k counts feature dimensions on which both printers are non-zero.
+// Each factor exists because a measured failure mode demanded it — see
+// docs/foomatic-recommendation-quality.md for the evidence.
+
+import type { Printer } from "./types"
+
+// Cosine on sparse one-hot vectors saturates at 1.0 whenever both vectors are
+// nearly empty: two printers that share a single dimension and have no other
+// known attributes are geometrically identical, yet that is almost no evidence.
+// tau = 4 maps overlap 1 -> 0.22, 4 -> 0.63, 8 -> 0.86, 12 -> 0.95.
+export const EVIDENCE_TAU = 4
+
+// Floor applied to the fully-damped score. Because evidenceWeight(1) ~= 0.22,
+// any pair resting on a single shared dimension falls below this automatically,
+// which is what removes "recommended because both use a catch-all driver".
+export const MIN_SIMILARITY_SCORE = 0.35
+
+// The feature vector only rewards agreement; it has no way to express that two
+// capabilities actively conflict. A mono printer sharing a driver family with a
+// colour one still scored well, even though it cannot substitute for it. These
+// multiplicative penalties encode hard substitution barriers.
+export const TYPE_CONFLICT_PENALTY = 0.5
+export const COLOR_CONFLICT_PENALTY = 0.6
+export const RESOLUTION_CONFLICT_PENALTY = 0.7
+export const RESOLUTION_CONFLICT_RATIO = 4
+
+export function evidenceWeight(overlap: number): number {
+  return 1 - Math.exp(-overlap / EVIDENCE_TAU)
+}
+
+// Count dimensions where both vectors carry a non-zero weight.
+export function overlapCount(a: number[], b: number[]): number {
+  let n = 0
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== 0 && b[i] !== 0) n++
+  }
+  return n
+}
+
+export function conflictPenalty(a: Printer, b: Printer): number {
+  let penalty = 1
+
+  if (
+    a.type &&
+    b.type &&
+    a.type !== "unknown" &&
+    b.type !== "unknown" &&
+    a.type !== b.type
+  ) {
+    penalty *= TYPE_CONFLICT_PENALTY
+  }
+
+  if (
+    (a.color === true && b.color === false) ||
+    (a.color === false && b.color === true)
+  ) {
+    penalty *= COLOR_CONFLICT_PENALTY
+  }
+
+  if (a.maxDpi != null && b.maxDpi != null && a.maxDpi > 0 && b.maxDpi > 0) {
+    const ratio = Math.max(a.maxDpi, b.maxDpi) / Math.min(a.maxDpi, b.maxDpi)
+
+    if (ratio >= RESOLUTION_CONFLICT_RATIO) {
+      penalty *= RESOLUTION_CONFLICT_PENALTY
+    }
+  }
+
+  return penalty
+}
+
+// Resolution explanations name the tier's range, never a specific figure, so
+// the UI cannot claim a DPI that neither printer actually has.
+export function resolutionTier(dpi: number | null | undefined): string | null {
+  if (dpi == null) return null
+  if (dpi <= 300) return "up to 300 dpi"
+  if (dpi <= 600) return "300-600 dpi"
+  if (dpi <= 1200) return "600-1200 dpi"
+  return "over 1200 dpi"
+}
+
+// User-facing interpretation of the final score. The score is an engineered
+// similarity value (IDF-weighted cosine, damped by evidence, penalized for
+// capability conflicts) — it is not a probability and not a validated
+// compatibility guarantee, so tier wording deliberately avoids implying either.
+//
+// Thresholds sit at the midpoints between the mean scores of the observed
+// evidence bands (<=1 shared feature: 0.393, 2-3: 0.593, 4-6: 0.787,
+// 7+: 0.921), so each tier corresponds to a real difference in supporting
+// evidence rather than to a cosmetic share of the distribution. Measured on
+// the full artifact set: "High confidence" recommendations are 90% 7+-feature
+// matches with zero capability conflicts, while every generic-driver-only
+// pair falls in "Limited evidence".
+export const CONFIDENCE_HIGH_THRESHOLD = 0.85
+export const CONFIDENCE_GOOD_THRESHOLD = 0.7
+export const CONFIDENCE_MODERATE_THRESHOLD = 0.5
+
+export type ConfidenceTone = "high" | "good" | "moderate" | "limited"
+
+export interface ConfidenceTier {
+  label: string
+  tone: ConfidenceTone
+}
+
+export function confidenceTier(score: number): ConfidenceTier {
+  if (score >= CONFIDENCE_HIGH_THRESHOLD) return { label: "High confidence", tone: "high" }
+  if (score >= CONFIDENCE_GOOD_THRESHOLD) return { label: "Good match", tone: "good" }
+  if (score >= CONFIDENCE_MODERATE_THRESHOLD) return { label: "Moderate match", tone: "moderate" }
+  return { label: "Limited evidence", tone: "limited" }
+}
+
+// Candidates with byte-identical feature vectors are genuinely
+// indistinguishable given the recorded data, so ties are broken by id to keep
+// output deterministic across runs and platforms rather than pretending to a
+// ranking the data cannot support.
+export function scoreThenIdComparator<T extends { index: number; score: number }>(
+  idOf: (index: number) => string
+): (x: T, y: T) => number {
+  return (x, y) => y.score - x.score || idOf(x.index).localeCompare(idOf(y.index))
+}
diff --git a/lib/foomatic/similarity-math.ts b/lib/foomatic/similarity-math.ts
new file mode 100644
index 00000000..4a998f9c
--- /dev/null
+++ b/lib/foomatic/similarity-math.ts
@@ -0,0 +1,54 @@
+// Pure vector maths shared by the vectorization and similarity stages of the
+// recommendation pipeline. Kept dependency-free so it can be unit tested
+// without touching the filesystem or generated artifacts.
+
+export function dotProduct(a: number[], b: number[]): number {
+  let sum = 0
+
+  for (let i = 0; i < a.length; i++) {
+    sum += a[i] * b[i]
+  }
+
+  return sum
+}
+
+export function magnitude(vec: number[]): number {
+  return Math.sqrt(dotProduct(vec, vec))
+}
+
+export function cosineSimilarity(
+  a: number[],
+  b: number[],
+  magA: number,
+  magB: number
+): number {
+  if (magA === 0 || magB === 0) {
+    return 0
+  }
+
+  return dotProduct(a, b) / (magA * magB)
+}
+
+export interface ScoredCandidate {
+  index: number
+  score: number
+}
+
+// Maintains `topK` as a min-heap-like array sorted ascending by score, so the
+// weakest surviving candidate is always at index 0 and cheap to evict.
+export function insertTopK(
+  topK: ScoredCandidate[],
+  candidate: ScoredCandidate,
+  k: number
+): void {
+  if (topK.length < k) {
+    topK.push(candidate)
+    topK.sort((a, b) => a.score - b.score)
+    return
+  }
+
+  if (candidate.score > topK[0].score) {
+    topK[0] = candidate
+    topK.sort((a, b) => a.score - b.score)
+  }
+}
diff --git a/lib/foomatic/types.ts b/lib/foomatic/types.ts
index 8c50991e..ead28ffd 100644
--- a/lib/foomatic/types.ts
+++ b/lib/foomatic/types.ts
@@ -45,11 +45,15 @@ export interface Printer {
   ppdPath?: string
   supportContacts?: SupportContact[]
   commandsets?: string[]
+  commandsetTokens?: string[]
   ppdOptions?: PpdOption[]
   color?: boolean | "unknown"
   duplex?: boolean | "unknown"
   recommended?: boolean
   hasOwnEntry?: boolean
+  psLevel?: number | null
+  pclLevel?: number | null
+  maxDpi?: number | null
 }
 
 export type PrinterStatus = 'Perfect' | 'Mostly' | 'Unsupported' | 'Unknown'
@@ -66,6 +70,15 @@ export interface PrinterSummary {
   status?: string
   driverCount?: number
   functionality?: string
+  color?: boolean | "unknown"
+  // Capability fields below are omitted when the source data does not
+  // establish them (never null/[]): an absent key means "not recorded in
+  // Foomatic", not "the printer lacks this". Built by lib/foomatic/catalog.ts.
+  maxDpi?: number
+  psLevel?: number
+  pclLevel?: number
+  cs?: string[] // commandsetTokens from the full Printer record
+  rd?: string // recommended driver family (normalizeDriverFamily)
 }
 
 export interface DriverPrinterRef {
diff --git a/package.json b/package.json
index aed9ddeb..a642d06a 100644
--- a/package.json
+++ b/package.json
@@ -8,7 +8,17 @@
     "generate": "tsx scripts/foomatic/data-generate.ts && tsx scripts/foomatic/generate-query-api.ts && tsx scripts/search/build-index.ts && tsx scripts/search/build-foomatic-index.ts && tsx scripts/generate-rss.ts",
     "build": "yarn generate && next build && tsx scripts/foomatic/generate-legacy-redirects.ts",
     "start": "next start",
-    "lint": "next lint"
+    "lint": "next lint",
+    "test": "vitest run",
+    "foomatic:pipeline": "tsx scripts/foomatic/data-generate.ts",
+    "foomatic:generate:xml": "tsx scripts/foomatic/generate-from-xml.ts",
+    "foomatic:generate:ppds": "bash scripts/foomatic/generate-ppds.sh",
+    "foomatic:data:combine": "tsx scripts/foomatic/combine-data.ts",
+    "foomatic:data:split": "tsx scripts/foomatic/split-printers.ts && tsx scripts/foomatic/split-drivers.ts",
+    "foomatic:data:vectorize": "tsx scripts/foomatic/vectorize.ts",
+    "foomatic:data:similarity": "tsx scripts/foomatic/compute-similarity.ts",
+    "foomatic:eval": "node tools/eval/metrics.mjs && node tools/eval/check-docs.mjs && node tools/eval/grade.mjs",
+    "assistant:eval": "tsx tools/assistant-eval/run.ts"
   },
   "dependencies": {
     "@giscus/react": "^3.1.0",
@@ -16,6 +26,7 @@
     "@tailwindcss/typography": "^0.5.16",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "dompurify": "^3.4.13",
     "fast-xml-parser": "^5.7.0",
     "framer-motion": "^12.5.0",
     "github-slugger": "^2.0.0",
@@ -51,6 +62,7 @@
     "postcss": "^8",
     "tailwindcss": "^3.4.1",
     "tsx": "^4.21.0",
-    "typescript": "^5"
+    "typescript": "^5",
+    "vitest": "^4.1.10"
   }
 }
diff --git a/scripts/foomatic/combine-data.ts b/scripts/foomatic/combine-data.ts
index e614baab..999abed3 100644
--- a/scripts/foomatic/combine-data.ts
+++ b/scripts/foomatic/combine-data.ts
@@ -2,6 +2,17 @@
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
+import {
+  getText,
+  getFunctionalityStatus,
+  getPrinterType,
+  getCommandsetTokens,
+  getColorCapability,
+  getDuplexCapability,
+  getMaxDpi,
+  getPSLevel,
+  getPCLLevel,
+} from "../../lib/foomatic/printer-attributes";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -20,90 +31,6 @@ function toArray(value) {
   return Array.isArray(value) ? value : [value];
 }
 
-function getText(value) {
-  if (value === undefined || value === null) {
-    return undefined;
-  }
-
-  if (typeof value === "string") {
-    return value.trim() || undefined;
-  }
-
-  if (typeof value === "number" || typeof value === "boolean") {
-    return String(value);
-  }
-
-  if (Array.isArray(value)) {
-    const text = value.map(getText).filter(Boolean).join(", ").trim();
-    return text || undefined;
-  }
-
-  if (typeof value === "object") {
-    if (typeof value.en === "string") {
-      return value.en.trim() || undefined;
-    }
-
-    if (typeof value["#text"] === "string") {
-      return value["#text"].trim() || undefined;
-    }
-
-    for (const key of Object.keys(value)) {
-      const nested = getText(value[key]);
-      if (nested) {
-        return nested;
-      }
-    }
-  }
-
-  return undefined;
-}
-
-function getFunctionalityStatus(func) {
-  if (!func || func === "?") {
-    return "Unknown";
-  }
-
-  switch (func) {
-    case "A":
-      return "Perfect";
-    case "B":
-    case "C":
-      return "Mostly";
-    default:
-      return "Unsupported";
-  }
-}
-
-function getPrinterType(printer) {
-  if (!printer.mechanism) {
-    return "unknown";
-  }
-
-  const mechanism = printer.mechanism;
-
-  if (mechanism.inkjet !== undefined) {
-    return "inkjet";
-  }
-
-  if (mechanism.laser !== undefined) {
-    return "laser";
-  }
-
-  if (mechanism.dotmatrix !== undefined) {
-    return "dot-matrix";
-  }
-
-  if (mechanism.transfer === "i") {
-    return "inkjet";
-  }
-
-  if (mechanism.transfer === "t") {
-    return "laser";
-  }
-
-  return "unknown";
-}
-
 function parseConnectivity(printer) {
   const connectivity = [];
   if (!printer.autodetect) {
@@ -199,6 +126,12 @@ function getCommandsets(printer) {
   return Array.from(new Set(sets));
 }
 
+/*
+ * Distinct from getCommandsets(), which produces human-readable labels for
+ * display (e.g. "PostScript 3"). This produces canonical short tokens
+ * (e.g. "POSTSCRIPT") from autodetect data, used as similarity features.
+ */
+
 function getPpdOptions(printer) {
   const ppdNode =
     printer.ppdOptions ||
@@ -267,48 +200,6 @@ function getSupportContacts(printer) {
     .filter(Boolean);
 }
 
-function getBooleanCapability(value) {
-  if (value === undefined || value === null) {
-    return "unknown";
-  }
-
-  if (typeof value === "boolean") {
-    return value;
-  }
-
-  const text = getText(value)?.toLowerCase();
-  if (!text) {
-    return "unknown";
-  }
-
-  if (["1", "true", "yes", "y", "color", "duplex"].includes(text)) {
-    return true;
-  }
-
-  if (["0", "false", "no", "n", "mono", "monochrome", "simplex"].includes(text)) {
-    return false;
-  }
-
-  return "unknown";
-}
-
-function getColorCapability(printer) {
-  return getBooleanCapability(
-    printer.color ??
-      printer.colors ??
-      printer.colorDevice ??
-      printer.capabilities?.color
-  );
-}
-
-function getDuplexCapability(printer) {
-  return getBooleanCapability(
-    printer.duplex ??
-      printer.duplexer ??
-      printer.capabilities?.duplex
-  );
-}
-
 function buildPpdFileName(printerId, driverId) {
   return `${normalizePrinterId(printerId)}-${driverId.replace(/^driver\//, "")}.ppd`;
 }
@@ -515,9 +406,13 @@ async function combineData() {
       ...(recommendedDriverWithPpd?.ppdPath ? { ppdPath: recommendedDriverWithPpd.ppdPath } : {}),
       supportContacts: getSupportContacts(printer),
       commandsets: getCommandsets(printer),
+      commandsetTokens: getCommandsetTokens(printer),
       ppdOptions: getPpdOptions(printer),
       color: getColorCapability(printer),
       duplex: getDuplexCapability(printer),
+      psLevel: getPSLevel(printer),
+      pclLevel: getPCLLevel(printer),
+      maxDpi: getMaxDpi(printer),
       recommended: Boolean(printer.driver || recommendedDriverId),
       hasOwnEntry: printersWithOwnEntry.has(printerId),
     });
diff --git a/scripts/foomatic/compute-similarity.ts b/scripts/foomatic/compute-similarity.ts
new file mode 100644
index 00000000..f83a8cd3
--- /dev/null
+++ b/scripts/foomatic/compute-similarity.ts
@@ -0,0 +1,474 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import type { Printer } from "../../lib/foomatic/types";
+import {
+  getRecommendedDriverFamily,
+  getSupportedDriverFamilies,
+} from "../../lib/foomatic/driver-family";
+import {
+  cosineSimilarity,
+  magnitude,
+  insertTopK,
+} from "../../lib/foomatic/similarity-math";
+import type { ScoredCandidate } from "../../lib/foomatic/similarity-math";
+import {
+  MIN_SIMILARITY_SCORE,
+  conflictPenalty,
+  evidenceWeight,
+  overlapCount,
+  resolutionTier,
+  scoreThenIdComparator,
+} from "../../lib/foomatic/scoring";
+
+const ROOT_DIR = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);
+
+const MATRIX_FILE = path.join(
+  ROOT_DIR,
+  "public",
+  "foomatic-db",
+  "feature-matrix.json",
+);
+
+const PRINTERS_FILE = path.join(
+  ROOT_DIR,
+  "public",
+  "foomatic-db",
+  "printers.json",
+);
+
+const OUTPUT_FILE = path.join(
+  ROOT_DIR,
+  "public",
+  "foomatic-db",
+  "recommendations.json",
+);
+
+const RECOMMENDATIONS_DIR = path.join(
+  ROOT_DIR,
+  "public",
+  "foomatic-db",
+  "recommendations",
+);
+
+const TOP_K = 10;
+
+interface FeatureMatrix {
+  printerCount: number;
+  featureCount: number;
+  featureNames: string[];
+  ids: string[];
+  matrix: number[][];
+}
+
+interface Recommendation {
+  id: string;
+  score: number;
+  sharedFeatures: string[];
+}
+
+interface RecommendationMap {
+  [printerId: string]: Recommendation[];
+}
+
+interface Output {
+  version: string;
+  printerCount: number;
+  topK: number;
+  recommendations: RecommendationMap;
+}
+
+function computeSharedFeatures(a: Printer, b: Printer): string[] {
+  const shared: string[] = [];
+
+  const aRecommended = getRecommendedDriverFamily(a);
+  const bRecommended = getRecommendedDriverFamily(b);
+
+  if (aRecommended && bRecommended && aRecommended === bRecommended) {
+    shared.push(`Preferred Linux driver: ${aRecommended}`);
+  }
+
+  const aSupported = new Set(getSupportedDriverFamilies(a));
+
+  const commonDrivers = getSupportedDriverFamilies(b)
+    .filter((driver) => aSupported.has(driver))
+    .slice(0, 3);
+
+  for (const driver of commonDrivers) {
+    if (driver !== aRecommended) {
+      shared.push(`Shared driver family: ${driver}`);
+    }
+  }
+
+  if (a.type && b.type && a.type !== "unknown" && a.type === b.type) {
+    const label: Record<string, string> = {
+      laser: "Laser printer",
+      inkjet: "Inkjet printer",
+      "dot-matrix": "Dot-matrix printer",
+    };
+
+    shared.push(label[a.type] ?? a.type);
+  }
+
+  if (a.color === true && b.color === true) {
+    shared.push("Color printing");
+  }
+
+  const aCommandsets = new Set(a.commandsetTokens ?? []);
+  const COMMANDSET_LABELS: Record<string, string> = {
+    POSTSCRIPT: "PostScript",
+    PCLXL: "PCL XL (PCL6)",
+    PCL5E: "PCL5e",
+    PCL: "PCL",
+    PDF: "PDF printing",
+    ESCPL2: "Epson ESC/P2",
+    ESCPR2: "Epson ESC/P-R",
+    BDC: "Epson BDC",
+    D4: "Epson D4",
+    D4PX: "Epson D4PX",
+    PJL: "PJL",
+    MLC: "MLC",
+  };
+  for (const cs of (b.commandsetTokens ?? [])) {
+    if (aCommandsets.has(cs)) {
+      const label = COMMANDSET_LABELS[cs] ?? cs;
+      shared.push(`Shared command set: ${label}`);
+    }
+  }
+
+  if (a.psLevel != null && b.psLevel != null && a.psLevel === b.psLevel) {
+    const psLabel: Record<number, string> = { 3: "PostScript 3", 2: "PostScript 2", 1: "PostScript 1" };
+    shared.push(psLabel[a.psLevel] ?? "PostScript");
+  }
+
+  if (a.pclLevel != null && b.pclLevel != null && a.pclLevel === b.pclLevel) {
+    const pclLabel: Record<number, string> = { 6: "PCL 6 / PCL XL", 5: "PCL 5e", 4: "PCL 4", 3: "PCL 3" };
+    shared.push(pclLabel[a.pclLevel] ?? "PCL");
+  }
+
+  const aTier = resolutionTier(a.maxDpi);
+  const bTier = resolutionTier(b.maxDpi);
+  if (aTier != null && aTier === bTier) {
+    shared.push(`Similar resolution (${aTier})`);
+  }
+
+  if (
+    a.functionality &&
+    b.functionality &&
+    a.functionality === b.functionality
+  ) {
+    const label: Record<string, string> = {
+      A: "Excellent Linux driver support",
+      B: "Good Linux driver support",
+      C: "Basic Linux driver support",
+    };
+
+    if (label[a.functionality]) {
+      shared.push(label[a.functionality]);
+    }
+  }
+
+  return [...new Set(shared)];
+}
+
+function buildRecommendation(
+  target: Printer,
+  candidate: Printer,
+  score: number,
+): Recommendation {
+  return {
+    id: candidate.id,
+    score: Number(score.toFixed(3)),
+    sharedFeatures: computeSharedFeatures(target, candidate),
+  };
+}
+
+function logScoreDistribution(recommendations: RecommendationMap): void {
+  const allScores = Object.values(recommendations)
+    .flat()
+    .map((r) => r.score)
+    .sort((a, b) => a - b);
+
+  const p = (pct: number): string =>
+    allScores[Math.floor(allScores.length * pct)].toFixed(3);
+
+  console.log("\nScore distribution across all recommendations:");
+  console.log(`  min : ${allScores[0].toFixed(3)}`);
+  console.log(`  p10 : ${p(0.1)}`);
+  console.log(`  p25 : ${p(0.25)}`);
+  console.log(`  p50 : ${p(0.5)}`);
+  console.log(`  p75 : ${p(0.75)}`);
+  console.log(`  p90 : ${p(0.9)}`);
+  console.log(`  max : ${allScores[allScores.length - 1].toFixed(3)}`);
+}
+
+function logSpotCheck(
+  recommendations: RecommendationMap,
+  printerMap: Map<string, Printer>,
+): void {
+  const targets = [
+    "HP-2000C",
+    "Canon-i560",
+    "Gestetner-DSc445",
+    "Epson-LQ-570",
+  ];
+
+  console.log("\nSpot-checks:");
+
+  for (const id of targets) {
+    const printer = printerMap.get(id);
+
+    if (!printer) {
+      continue;
+    }
+
+    console.log(`\n  ${printer.id} — ${printer.manufacturer} ${printer.type}`);
+
+    const recs = recommendations[id] ?? [];
+
+    for (const [index, rec] of recs.slice(0, 3).entries()) {
+      const candidate = printerMap.get(rec.id);
+
+      console.log(`    ${index + 1}. ${rec.id}`);
+
+      console.log(`       score  : ${rec.score}`);
+
+      console.log(
+        `       type   : ${candidate?.type ?? "unknown"} | manufacturer: ${candidate?.manufacturer ?? "unknown"}`,
+      );
+
+      console.log(
+        `       shared : ${rec.sharedFeatures.length > 0 ? rec.sharedFeatures.join(", ") : "none"}`,
+      );
+    }
+  }
+}
+
+// A handful of upstream printer ids differ only by letter case. On a
+// case-insensitive filesystem (Windows, and macOS by default) the later shard
+// overwrites the earlier one, so those printers would show the wrong
+// recommendations locally. CI builds on Linux, where every id gets its own
+// file, so this is a local-development caveat rather than a production bug.
+function warnOnCaseInsensitiveCollisions(printerIds: string[]): void {
+  const seen = new Map<string, string>();
+  const collisions: Array<[string, string]> = [];
+
+  for (const id of printerIds) {
+    const key = id.toLowerCase();
+    const previous = seen.get(key);
+
+    if (previous) {
+      collisions.push([previous, id]);
+    } else {
+      seen.set(key, id);
+    }
+  }
+
+  if (collisions.length === 0) {
+    return;
+  }
+
+  const written = fs.readdirSync(RECOMMENDATIONS_DIR).length;
+
+  if (written === printerIds.length) {
+    return;
+  }
+
+  console.warn(
+    `\n! ${collisions.length} printer id(s) differ only by case and collapsed on this filesystem:`,
+  );
+
+  for (const [a, b] of collisions) {
+    console.warn(`    ${a}  <->  ${b}`);
+  }
+
+  console.warn(
+    `  ${written}/${printerIds.length} shards written. Linux/CI builds are unaffected.`,
+  );
+}
+
+function loadFeatureMatrix(): FeatureMatrix {
+  if (!fs.existsSync(MATRIX_FILE)) {
+    throw new Error(
+      `Missing feature matrix: ${MATRIX_FILE}\n` +
+        `Run: yarn foomatic:data:vectorize`,
+    );
+  }
+
+  return JSON.parse(fs.readFileSync(MATRIX_FILE, "utf-8"));
+}
+
+function loadPrinters(): Printer[] {
+  if (!fs.existsSync(PRINTERS_FILE)) {
+    throw new Error(
+      `Missing printers.json: ${PRINTERS_FILE}\n` +
+        `Run: yarn foomatic:generate:xml && yarn foomatic:data:combine`,
+    );
+  }
+
+  const raw = JSON.parse(fs.readFileSync(PRINTERS_FILE, "utf-8"));
+
+  return raw.printers;
+}
+
+function main(): void {
+  const start = performance.now();
+
+  console.log("Loading feature matrix...");
+
+  const matrixData = loadFeatureMatrix();
+
+  console.log(`  Printers : ${matrixData.printerCount}`);
+
+  console.log(`  Features : ${matrixData.featureCount}`);
+
+  console.log("Loading printer metadata...");
+
+  const printers = loadPrinters();
+
+  const printerMap = new Map(printers.map((p) => [p.id, p]));
+
+  console.log("Pre-computing magnitudes...");
+
+  const magnitudes = matrixData.matrix.map(magnitude);
+
+  const recommendations: RecommendationMap = {};
+
+  console.log(`Computing top-${TOP_K} similarities...`);
+
+  for (let i = 0; i < matrixData.printerCount; i++) {
+    const vecA = matrixData.matrix[i];
+    const magA = magnitudes[i];
+
+    const topK: ScoredCandidate[] = [];
+
+    for (let j = 0; j < matrixData.printerCount; j++) {
+      if (i === j) {
+        continue;
+      }
+
+      const vecB = matrixData.matrix[j];
+      const magB = magnitudes[j];
+
+      const cosine = cosineSimilarity(vecA, vecB, magA, magB);
+
+      if (cosine < MIN_SIMILARITY_SCORE) {
+        continue;
+      }
+
+      const targetPrinter = printerMap.get(matrixData.ids[i]);
+      const candidatePrinter = printerMap.get(matrixData.ids[j]);
+
+      const penalty =
+        targetPrinter && candidatePrinter
+          ? conflictPenalty(targetPrinter, candidatePrinter)
+          : 1;
+
+      const score =
+        cosine * evidenceWeight(overlapCount(vecA, vecB)) * penalty;
+
+      if (score < MIN_SIMILARITY_SCORE) {
+        continue;
+      }
+
+      insertTopK(
+        topK,
+        {
+          index: j,
+          score,
+        },
+        TOP_K,
+      );
+    }
+
+    topK.sort(scoreThenIdComparator((index) => matrixData.ids[index]));
+
+    const printerId = matrixData.ids[i];
+
+    recommendations[printerId] = topK.map(({ index, score }) => {
+      const target = printerMap.get(printerId);
+
+      const candidate = printerMap.get(matrixData.ids[index]);
+
+      if (!target || !candidate) {
+        throw new Error(
+          "Printer lookup failed during recommendation generation",
+        );
+      }
+
+      return buildRecommendation(target, candidate, score);
+    });
+
+    if ((i + 1) % 1000 === 0) {
+      const elapsed = ((performance.now() - start) / 1000).toFixed(1);
+
+      console.log(
+        `  ${i + 1}/${matrixData.printerCount} — ${elapsed}s elapsed`,
+      );
+    }
+  }
+
+  const output: Output = {
+    version: "2.0.0",
+    printerCount: matrixData.printerCount,
+    topK: TOP_K,
+    recommendations,
+  };
+
+  fs.mkdirSync(path.dirname(OUTPUT_FILE), {
+    recursive: true,
+  });
+
+  fs.writeFileSync(OUTPUT_FILE, JSON.stringify(output, null, 2));
+
+  fs.mkdirSync(RECOMMENDATIONS_DIR, { recursive: true });
+
+  // Each per-printer shard embeds the handful of display fields the UI needs
+  // for its cards. Costs ~0.9 KB per shard, but lets the printer page render
+  // recommendations without also downloading the ~1.5 MB printersMap.json.
+  for (const [printerId, recs] of Object.entries(output.recommendations)) {
+    const enriched = recs.map((rec) => {
+      const candidate = printerMap.get(rec.id);
+
+      // Defaults mirror split-printers.ts's printersMap projection exactly, so
+      // the rendered cards are identical to the previous map-based lookup.
+      return {
+        ...rec,
+        manufacturer: candidate?.manufacturer,
+        model: candidate?.model,
+        status: candidate?.status || "Unknown",
+        type: candidate?.type || "unknown",
+        driverCount: candidate?.drivers ? candidate.drivers.length : 0,
+      };
+    });
+
+    fs.writeFileSync(
+      path.join(RECOMMENDATIONS_DIR, `${printerId}.json`),
+      JSON.stringify(enriched),
+    );
+  }
+
+  warnOnCaseInsensitiveCollisions(Object.keys(output.recommendations));
+
+  logScoreDistribution(recommendations);
+
+  logSpotCheck(recommendations, printerMap);
+
+  const runtime = ((performance.now() - start) / 1000).toFixed(1);
+
+  console.log(`\n✓ Recommendations written to ${OUTPUT_FILE}`);
+
+  console.log(
+    `  File size : ${(fs.statSync(OUTPUT_FILE).size / 1024 / 1024).toFixed(2)} MB`,
+  );
+
+  console.log(`  Runtime   : ${runtime}s`);
+  console.log(`  Printers  : ${matrixData.printerCount}`);
+  console.log(`  Top-K     : ${TOP_K}`);
+}
+
+main();
diff --git a/scripts/foomatic/data-generate.ts b/scripts/foomatic/data-generate.ts
index 41ad442d..637e9680 100644
--- a/scripts/foomatic/data-generate.ts
+++ b/scripts/foomatic/data-generate.ts
@@ -2,12 +2,30 @@ import { spawnSync } from "child_process";
 
 const forwardedArgs = process.argv.slice(2);
 const skipPpd = forwardedArgs.includes("--skip-ppd");
+const skipSimilarity =
+  forwardedArgs.includes("--skip-similarity") ||
+  process.env.FOOMATIC_SKIP_SIMILARITY === "1";
+
+// generate-ppds.sh is driven through /bin/bash, which does not resolve on
+// Windows, so the step is dropped there instead of failing the whole run.
+const canRunPpds = process.platform !== "win32";
+
 const steps: Array<[string, string[]]> = [
   ["scripts/foomatic/generate-from-xml.ts", []],
-  ["scripts/foomatic/generate-ppds.sh", skipPpd ? ["--skip-ppd"] : []],
+  ...(canRunPpds
+    ? ([
+        ["scripts/foomatic/generate-ppds.sh", skipPpd ? ["--skip-ppd"] : []],
+      ] as Array<[string, string[]]>)
+    : []),
   ["scripts/foomatic/combine-data.ts", forwardedArgs],
   ["scripts/foomatic/split-printers.ts", []],
   ["scripts/foomatic/split-drivers.ts", []],
+  ...(skipSimilarity
+    ? []
+    : ([
+        ["scripts/foomatic/vectorize.ts", []],
+        ["scripts/foomatic/compute-similarity.ts", []],
+      ] as Array<[string, string[]]>)),
 ];
 
 for (const [scriptPath, args] of steps) {
@@ -17,6 +35,7 @@ for (const [scriptPath, args] of steps) {
     : [scriptPath, ...args];
   const result = spawnSync(command, commandArgs, {
     stdio: "inherit",
+    shell: true,
   });
 
   if (result.status !== 0) {
diff --git a/scripts/foomatic/split-printers.ts b/scripts/foomatic/split-printers.ts
index e8f8f382..061df8f2 100644
--- a/scripts/foomatic/split-printers.ts
+++ b/scripts/foomatic/split-printers.ts
@@ -1,23 +1,15 @@
 import fs from 'fs/promises'
 import path from 'path'
 import { fileURLToPath } from 'url'
+import { toPrinterSummary } from '../../lib/foomatic/catalog.ts'
+import type { Printer } from '../../lib/foomatic/types.ts'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 const ROOT_DIR = path.join(__dirname, "..", "..")
 
-type PrinterRecord = {
-  id: string
-  manufacturer?: string
-  model?: string
-  type?: string
-  status?: string
-  functionality?: string
-  drivers?: unknown[]
-}
-
 type PrintersPayload = {
-  printers: PrinterRecord[]
+  printers: Printer[]
 }
 
 async function splitPrintersData() {
@@ -33,18 +25,13 @@ async function splitPrintersData() {
     await fs.mkdir(printersDir, { recursive: true })
     
     const printersMap = {
-      printers: data.printers.map(printer => ({
-        id: printer.id,
-        manufacturer: printer.manufacturer,
-        model: printer.model,
-        type: printer.type || 'unknown',
-        status: printer.status || 'Unknown',
-        functionality: printer.functionality || '?',
-        driverCount: printer.drivers ? printer.drivers.length : 0
-      }))
+      printers: data.printers.map(toPrinterSummary)
     }
     const mapPath = path.join(ROOT_DIR, 'public', 'foomatic-db', 'printersMap.json')
-    await fs.writeFile(mapPath, JSON.stringify(printersMap, null, 2))
+    // Minified on purpose: this artifact is fetched by the browser (directory
+    // page and, later, the assistant catalogue), and pretty-printing it costs
+    // ~490 KB of raw payload for zero consumer benefit.
+    await fs.writeFile(mapPath, JSON.stringify(printersMap))
     console.log(`Created lightweight index: ${mapPath}`)
     let processed = 0
     const batchSize = 100
@@ -52,7 +39,7 @@ async function splitPrintersData() {
     for (let i = 0; i < data.printers.length; i += batchSize) {
       const batch = data.printers.slice(i, i + batchSize)
       
-      await Promise.all(batch.map(async (printer: PrinterRecord) => {
+      await Promise.all(batch.map(async (printer: Printer) => {
         const printerPath = path.join(printersDir, `${printer.id}.json`)
         await fs.writeFile(printerPath, JSON.stringify(printer, null, 2))
         processed++
diff --git a/scripts/foomatic/vectorize.ts b/scripts/foomatic/vectorize.ts
new file mode 100644
index 00000000..098026d3
--- /dev/null
+++ b/scripts/foomatic/vectorize.ts
@@ -0,0 +1,280 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import type { Printer } from "../../lib/foomatic/types";
+import {
+  trim,
+  getRecommendedDriverFamily,
+  getSupportedDriverFamilies,
+} from "../../lib/foomatic/driver-family";
+import { encodeFunctionality } from "../../lib/foomatic/printer-attributes";
+
+const ROOT_DIR = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);
+
+const INPUT_FILE = path.join(
+  ROOT_DIR,
+  "public",
+  "foomatic-db",
+  "printers.json",
+);
+
+const OUTPUT_FILE = path.join(
+  ROOT_DIR,
+  "public",
+  "foomatic-db",
+  "feature-matrix.json",
+);
+
+interface Vocabulary {
+  recommendedDrivers: string[];
+  supportedDrivers: string[];
+  types: string[];
+  commandsets: string[];
+  // Inverse-document-frequency scale per vocabulary term, normalized to mean 1
+  // so overall feature-group balance is preserved while rare terms outweigh
+  // ubiquitous ones. Sharing "postscript" (1746 printers) is weak evidence;
+  // sharing "necp6" (8 printers) is strong evidence.
+  idf: {
+    recommendedDrivers: number[];
+    supportedDrivers: number[];
+    commandsets: number[];
+  };
+}
+
+// idf(t) = ln(1 + N / df(t)), rescaled so the mean across the vocabulary is 1.
+function idfScale(terms: string[], df: Map<string, number>, total: number): number[] {
+  const raw = terms.map((t) => Math.log(1 + total / Math.max(1, df.get(t) ?? 1)));
+  const mean = raw.reduce((a, b) => a + b, 0) / (raw.length || 1);
+  return mean > 0 ? raw.map((v) => v / mean) : raw.map(() => 1);
+}
+
+interface FeatureMatrix {
+  printerCount: number;
+  featureCount: number;
+  featureNames: string[];
+  vocab: Vocabulary;
+  ids: string[];
+  matrix: number[][];
+}
+
+const RECOMMENDED_DRIVER_WEIGHT = 3.0;
+const SUPPORTED_DRIVER_WEIGHT = 1.0;
+const TYPE_WEIGHT = 0.5;
+const FUNCTIONALITY_WEIGHT = 0.25;
+const COLOR_WEIGHT = 1.0;
+const COMMANDSET_WEIGHT = 1.5;
+const MIN_COMMANDSET_FREQUENCY = 20;
+const LANG_WEIGHT = 1.0;
+const LANG_LEVEL_WEIGHT = 0.5;
+const RESOLUTION_WEIGHT = 0.75;
+
+function buildVocabularies(printers: Printer[]): Vocabulary {
+  const recommendedDrivers = new Set<string>();
+
+  const supportedDrivers = new Set<string>();
+
+  const types = new Set<string>();
+
+  const commandsetFreq = new Map<string, number>();
+
+  const recommendedFreq = new Map<string, number>();
+
+  const supportedFreq = new Map<string, number>();
+
+  for (const printer of printers) {
+    const recommended = getRecommendedDriverFamily(printer);
+
+    if (recommended) {
+      recommendedDrivers.add(recommended);
+      recommendedFreq.set(recommended, (recommendedFreq.get(recommended) ?? 0) + 1);
+    }
+
+    for (const family of getSupportedDriverFamilies(printer)) {
+      supportedDrivers.add(family);
+      supportedFreq.set(family, (supportedFreq.get(family) ?? 0) + 1);
+    }
+
+    const type = trim(printer.type);
+
+    if (type && type !== "unknown") {
+      types.add(type);
+    }
+
+    for (const cs of printer.commandsetTokens ?? []) {
+      commandsetFreq.set(cs, (commandsetFreq.get(cs) ?? 0) + 1);
+    }
+  }
+
+  const commandsets = [...commandsetFreq.entries()]
+    .filter(([, count]) => count >= MIN_COMMANDSET_FREQUENCY)
+    .map(([cs]) => cs)
+    .sort();
+
+  const recommendedList = [...recommendedDrivers].sort();
+  const supportedList = [...supportedDrivers].sort();
+  const total = printers.length;
+
+  return {
+    recommendedDrivers: recommendedList,
+    supportedDrivers: supportedList,
+    types: [...types].sort(),
+    commandsets,
+    idf: {
+      recommendedDrivers: idfScale(recommendedList, recommendedFreq, total),
+      supportedDrivers: idfScale(supportedList, supportedFreq, total),
+      commandsets: idfScale(commandsets, commandsetFreq, total),
+    },
+  };
+}
+
+function buildFeatureNames(vocab: Vocabulary): string[] {
+  return [
+    ...vocab.recommendedDrivers.map((driver) => `recommended_driver:${driver}`),
+
+    ...vocab.supportedDrivers.map((driver) => `supported_driver:${driver}`),
+
+    ...vocab.types.map((type) => `type:${type}`),
+
+    "functionality",
+
+    "color",
+
+    ...vocab.commandsets.map((cs) => `commandset:${cs}`),
+
+    "lang:postscript",
+    "lang:postscript_3",
+    "lang:pcl",
+    "lang:pcl_6",
+
+    "res:300",
+    "res:600",
+    "res:1200",
+    "res:2400plus",
+  ];
+}
+
+function encodePrinter(printer: Printer, vocab: Vocabulary): number[] {
+  const recommended = getRecommendedDriverFamily(printer);
+
+  const supported = new Set(getSupportedDriverFamilies(printer));
+
+  const type = trim(printer.type);
+
+  return [
+    ...vocab.recommendedDrivers.map((driver, i) =>
+      driver === recommended
+        ? RECOMMENDED_DRIVER_WEIGHT * vocab.idf.recommendedDrivers[i]
+        : 0,
+    ),
+
+    ...vocab.supportedDrivers.map((driver, i) =>
+      supported.has(driver)
+        ? SUPPORTED_DRIVER_WEIGHT * vocab.idf.supportedDrivers[i]
+        : 0,
+    ),
+
+    ...vocab.types.map((t) => (t === type ? TYPE_WEIGHT : 0)),
+
+    encodeFunctionality(printer.functionality) * FUNCTIONALITY_WEIGHT,
+
+    printer.color === true ? COLOR_WEIGHT : 0,
+
+    ...vocab.commandsets.map((cs, i) =>
+      (printer.commandsetTokens ?? []).includes(cs)
+        ? COMMANDSET_WEIGHT * vocab.idf.commandsets[i]
+        : 0,
+    ),
+
+    printer.psLevel != null ? LANG_WEIGHT : 0,
+    printer.psLevel === 3 ? LANG_LEVEL_WEIGHT : 0,
+    printer.pclLevel != null ? LANG_WEIGHT : 0,
+    printer.pclLevel === 6 ? LANG_LEVEL_WEIGHT : 0,
+
+    printer.maxDpi != null && printer.maxDpi <= 300 ? RESOLUTION_WEIGHT : 0,
+    printer.maxDpi != null && printer.maxDpi > 300 && printer.maxDpi <= 600 ? RESOLUTION_WEIGHT : 0,
+    printer.maxDpi != null && printer.maxDpi > 600 && printer.maxDpi <= 1200 ? RESOLUTION_WEIGHT : 0,
+    printer.maxDpi != null && printer.maxDpi > 1200 ? RESOLUTION_WEIGHT : 0,
+  ];
+}
+
+function loadAndValidate(): Printer[] {
+  if (!fs.existsSync(INPUT_FILE)) {
+    throw new Error(
+      `Input not found: ${INPUT_FILE}\n` +
+        `Run: yarn foomatic:generate:xml && yarn foomatic:data:combine`,
+    );
+  }
+
+  const raw: unknown = JSON.parse(fs.readFileSync(INPUT_FILE, "utf-8"));
+
+  if (
+    typeof raw !== "object" ||
+    raw === null ||
+    !Array.isArray((raw as Record<string, unknown>).printers)
+  ) {
+    throw new Error("Invalid printers.json: expected { printers: Printer[] }");
+  }
+
+  const printers = (raw as { printers: Printer[] }).printers;
+
+  if (printers.length === 0) {
+    throw new Error("printers.json is empty. Re-run the pipeline.");
+  }
+
+  return printers;
+}
+
+function main(): void {
+  console.log("Loading printers.json...");
+
+  const printers = loadAndValidate();
+
+  console.log(`Loaded ${printers.length} printers`);
+
+  const vocab = buildVocabularies(printers);
+
+  const featureNames = buildFeatureNames(vocab);
+
+  const ids: string[] = [];
+
+  const matrix: number[][] = [];
+
+  for (const printer of printers) {
+    ids.push(printer.id);
+
+    matrix.push(encodePrinter(printer, vocab));
+  }
+
+  const output: FeatureMatrix = {
+    printerCount: printers.length,
+    featureCount: featureNames.length,
+    featureNames,
+    vocab,
+    ids,
+    matrix,
+  };
+
+  fs.mkdirSync(path.dirname(OUTPUT_FILE), {
+    recursive: true,
+  });
+
+  fs.writeFileSync(OUTPUT_FILE, JSON.stringify(output, null, 2));
+
+  console.log(`✓ Feature matrix generated: ${OUTPUT_FILE}`);
+
+  console.log(`Features: ${output.featureCount}`);
+
+  console.log(`Recommended drivers: ${vocab.recommendedDrivers.length}`);
+
+  console.log(`Supported drivers: ${vocab.supportedDrivers.length}`);
+
+  console.log(`Printer types: ${vocab.types.length}`);
+
+  console.log(`Commandset tokens: ${vocab.commandsets.length}`);
+}
+
+main();
diff --git a/tools/assistant-eval/node-data.ts b/tools/assistant-eval/node-data.ts
new file mode 100644
index 00000000..68f45eef
--- /dev/null
+++ b/tools/assistant-eval/node-data.ts
@@ -0,0 +1,63 @@
+// Filesystem-backed AssistantData for Node contexts (the eval harness and the
+// real-artifact test suite). Reads the same generated artifacts the browser
+// fetches, so evaluation exercises exactly the data that ships.
+
+import fs from "node:fs"
+import path from "node:path"
+import type { DriverRecord, DriverSummary, Printer, PrinterSummary } from "../../lib/foomatic/types"
+import type { AssistantData, RecommendationEntry } from "../../lib/assistant/types"
+
+const DB = (root: string) => path.join(root, "public", "foomatic-db")
+
+export function artifactsPresent(root: string = process.cwd()): boolean {
+  return (
+    fs.existsSync(path.join(DB(root), "printersMap.json")) &&
+    fs.existsSync(path.join(DB(root), "driversMap.json")) &&
+    fs.existsSync(path.join(DB(root), "printers")) &&
+    fs.existsSync(path.join(DB(root), "recommendations"))
+  )
+}
+
+function readJson<T>(file: string): T | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as T
+  } catch {
+    return null
+  }
+}
+
+export function nodeData(root: string = process.cwd()): AssistantData {
+  const db = DB(root)
+  const cache = new Map<string, unknown>()
+
+  const cached = <T>(key: string, load: () => T): T => {
+    if (!cache.has(key)) cache.set(key, load())
+    return cache.get(key) as T
+  }
+
+  return {
+    async getCatalog() {
+      return cached("catalog", () => {
+        const payload = readJson<{ printers: PrinterSummary[] }>(path.join(db, "printersMap.json"))
+        return payload?.printers ?? []
+      })
+    },
+    async getPrinter(id: string) {
+      return cached(`printer:${id}`, () => readJson<Printer>(path.join(db, "printers", `${id}.json`)))
+    },
+    async getRecommendations(id: string) {
+      return cached(`recs:${id}`, () => {
+        return readJson<RecommendationEntry[]>(path.join(db, "recommendations", `${id}.json`)) ?? []
+      })
+    },
+    async getDriversMap() {
+      return cached("drivers", () => {
+        const payload = readJson<{ drivers: DriverSummary[] }>(path.join(db, "driversMap.json"))
+        return payload?.drivers ?? []
+      })
+    },
+    async getDriver(id: string) {
+      return cached(`driver:${id}`, () => readJson<DriverRecord>(path.join(db, "drivers", `${id}.json`)))
+    },
+  }
+}
diff --git a/tools/assistant-eval/run.ts b/tools/assistant-eval/run.ts
new file mode 100644
index 00000000..f4e0c9dd
--- /dev/null
+++ b/tools/assistant-eval/run.ts
@@ -0,0 +1,261 @@
+// Assistant evaluation harness. Runs the natural-language corpus and the
+// approved end-to-end flows against the REAL generated artifacts, validates
+// grounding (every rendered claim traceable to local data), measures latency
+// and artifact sizes, and gates documentation drift for the assistant's
+// tunable constants (same conventions as tools/eval/*.mjs for the
+// recommendation pipeline).
+//
+// Run: yarn assistant:eval   (requires `yarn generate` output to exist)
+// Exits non-zero on any failure.
+
+import fs from "node:fs"
+import path from "node:path"
+import { performance } from "node:perf_hooks"
+import zlib from "node:zlib"
+import { CORPUS } from "../../lib/assistant/__tests__/corpus"
+import { parsePageContext } from "../../lib/assistant/context"
+import { buildDriverIndex, buildPrinterIndex } from "../../lib/assistant/entities"
+import { runAssistant } from "../../lib/assistant/engine"
+import { parseQuery } from "../../lib/assistant/parse"
+import type { AssistantPageContext, ResponsePlan } from "../../lib/assistant/types"
+import { printerHref } from "../../lib/foomatic/routes"
+import { artifactsPresent, nodeData } from "./node-data"
+
+const ROOT = process.cwd()
+const failures: string[] = []
+const fail = (message: string) => failures.push(message)
+
+const BANNED_PATTERNS = [
+  /exact match/i,
+  /% match\b/i,
+  /% compatible/i,
+  /compatibility (probability|percentage|score)/i,
+  /guaranteed to work/i,
+]
+
+function planText(plan: ResponsePlan): string {
+  return plan.blocks
+    .map(block => {
+      if (block.kind === "text") return block.text
+      if (block.kind === "list") return `${block.title} ${block.items.join(" ")}`
+      if (block.kind === "chips") return block.chips.map(chip => chip.label).join(" ")
+      if (block.kind === "comparison") return block.rows.map(row => `${row.label} ${row.a} ${row.b}`).join(" ")
+      return ""
+    })
+    .join(" ")
+}
+
+function gzipSize(file: string): { raw: number; gz: number } | null {
+  try {
+    const buffer = fs.readFileSync(file)
+    return { raw: buffer.length, gz: zlib.gzipSync(buffer).length }
+  } catch {
+    return null
+  }
+}
+
+async function main() {
+  if (!artifactsPresent(ROOT)) {
+    console.error(
+      "assistant-eval: generated artifacts not found under public/foomatic-db.\n" +
+        "Run `yarn generate` (or at least the combine/split stages) first."
+    )
+    process.exit(1)
+  }
+
+  const data = nodeData(ROOT)
+  const catalog = await data.getCatalog()
+  const byId = new Map(catalog.map(printer => [printer.id, printer]))
+  const indexes = {
+    printers: buildPrinterIndex(catalog),
+    drivers: buildDriverIndex(await data.getDriversMap()),
+  }
+
+  const printerContext = parsePageContext(printerHref("HP-LaserJet_4", "HP"))
+  const driverContext = parsePageContext("/foomatic/driver/hplip")
+  const homeContext = parsePageContext("/")
+  const contextFor = (ctx?: "home" | "printer" | "driver"): AssistantPageContext =>
+    ctx === "printer" ? printerContext : ctx === "driver" ? driverContext : homeContext
+
+  // ---- 1. corpus intent accuracy on real data -----------------------------
+  let intentPasses = 0
+  let checkPasses = 0
+  let checksRun = 0
+  for (const testCase of CORPUS) {
+    const query = parseQuery(testCase.q, contextFor(testCase.ctx), indexes)
+    if (query.intent === testCase.intent) {
+      intentPasses++
+    } else {
+      fail(`intent: "${testCase.q}" -> ${query.intent}, expected ${testCase.intent}`)
+    }
+    if (testCase.check && !testCase.fixtureOnly) {
+      checksRun++
+      const problem = testCase.check(query)
+      if (problem === null) checkPasses++
+      else fail(`check: "${testCase.q}": ${problem}`)
+    }
+  }
+
+  // ---- 2. grounding sweep: run every utterance end-to-end -----------------
+  let groundedResponses = 0
+  for (const testCase of CORPUS) {
+    const turn = await runAssistant(testCase.q, contextFor(testCase.ctx), data)
+    const text = planText(turn.plan)
+
+    for (const pattern of BANNED_PATTERNS) {
+      if (pattern.test(text)) fail(`banned wording for "${testCase.q}": ${pattern}`)
+    }
+
+    // Every similarity percentage must equal a score in the execution's own
+    // shard entries - the response layer cannot invent or reinterpret scores.
+    const allowedScores = new Set<number>()
+    if (turn.execution.kind === "similar") {
+      for (const entry of turn.execution.entries) allowedScores.add(Math.round(entry.score * 100))
+    }
+    if (turn.execution.kind === "explanation") {
+      allowedScores.add(Math.round(turn.execution.entry.score * 100))
+    }
+    if (turn.execution.kind === "clarify" && turn.execution.question.topic === "explanation-candidate") {
+      for (const entry of turn.execution.question.topRecommendations) {
+        allowedScores.add(Math.round(entry.score * 100))
+      }
+    }
+    for (const match of text.matchAll(/(\d+)% similarity/g)) {
+      if (!allowedScores.has(Number(match[1]))) {
+        fail(`ungrounded similarity % for "${testCase.q}": ${match[1]}`)
+      }
+    }
+
+    // Every printer card must reference a real catalogue record.
+    for (const block of turn.plan.blocks) {
+      if (block.kind === "printer-cards") {
+        for (const card of block.printers) {
+          if (!byId.has(card.id)) fail(`unknown printer id rendered for "${testCase.q}": ${card.id}`)
+        }
+      }
+    }
+    groundedResponses++
+  }
+
+  // ---- 3. approved end-to-end flows ---------------------------------------
+  const flows: { q: string; ctx?: "printer"; expectKind: string }[] = [
+    { q: "find a colour laser printer", expectKind: "search-results" },
+    { q: "find a colour laser printer with good linux support", expectKind: "search-results" },
+    { q: "what printers are similar to this?", ctx: "printer", expectKind: "similar" },
+    { q: "what is the best printer?", expectKind: "clarify" },
+    { q: "what are better alternatives?", ctx: "printer", expectKind: "clarify" },
+    { q: "find a printer with better linux support", ctx: "printer", expectKind: "similar" },
+    { q: "compare HP 2500C and HP DeskJet 560C", expectKind: "comparison" },
+    { q: "which printers use the same driver?", ctx: "printer", expectKind: "driver-search" },
+    { q: "duplex printer", expectKind: "insufficient" },
+    { q: "purple laser printer", expectKind: "search-results" },
+    { q: "Brother HL-2270DW", expectKind: "entity-miss" },
+  ]
+  for (const flow of flows) {
+    const turn = await runAssistant(flow.q, contextFor(flow.ctx), data)
+    if (turn.execution.kind !== flow.expectKind) {
+      fail(`flow "${flow.q}": execution ${turn.execution.kind}, expected ${flow.expectKind}`)
+    }
+  }
+  // "why was X recommended" needs the real top recommendation's name.
+  const shard = await data.getRecommendations("HP-LaserJet_4")
+  if (shard.length > 0) {
+    const top = shard[0]
+    const name = `${top.manufacturer ?? ""} ${top.model ?? top.id}`.trim()
+    const turn = await runAssistant(`why was ${name} recommended`, printerContext, data)
+    if (turn.execution.kind !== "explanation") {
+      fail(`flow "why was ${name} recommended": ${turn.execution.kind}`)
+    } else {
+      const text = planText(turn.plan)
+      for (const feature of top.sharedFeatures) {
+        if (!text.includes(feature)) fail(`explanation missing shard feature: ${feature}`)
+      }
+    }
+  } else {
+    fail("HP-LaserJet_4 recommendation shard is empty; cannot validate explanation flow")
+  }
+
+  // ---- 4. latency (warm data source) --------------------------------------
+  const durations: number[] = []
+  for (let round = 0; round < 3; round++) {
+    for (const testCase of CORPUS) {
+      const start = performance.now()
+      await runAssistant(testCase.q, contextFor(testCase.ctx), data)
+      durations.push(performance.now() - start)
+    }
+  }
+  durations.sort((a, b) => a - b)
+  const median = durations[Math.floor(durations.length / 2)]
+  const p95 = durations[Math.floor(durations.length * 0.95)]
+
+  // ---- 5. artifact sizes ---------------------------------------------------
+  const db = path.join(ROOT, "public", "foomatic-db")
+  const sizes = {
+    printersMap: gzipSize(path.join(db, "printersMap.json")),
+    driversMap: gzipSize(path.join(db, "driversMap.json")),
+    samplePrinterShard: gzipSize(path.join(db, "printers", "HP-LaserJet_4.json")),
+    sampleRecommendationShard: gzipSize(path.join(db, "recommendations", "HP-LaserJet_4.json")),
+  }
+
+  // ---- 6. tunables documentation drift ------------------------------------
+  const constantsSource = fs.readFileSync(path.join(ROOT, "lib", "assistant", "constants.ts"), "utf8")
+  const codeConstants = new Map<string, string>()
+  for (const match of constantsSource.matchAll(/export const (\w+) = ([\d.]+)/g)) {
+    codeConstants.set(match[1], match[2])
+  }
+  const docPath = path.join(ROOT, "docs", "foomatic-assistant.md")
+  if (!fs.existsSync(docPath)) {
+    fail("docs/foomatic-assistant.md is missing")
+  } else {
+    const doc = fs.readFileSync(docPath, "utf8")
+    const documented = new Map<string, string>()
+    for (const match of doc.matchAll(/\| `(\w+)` \| ([\d.]+) \|/g)) {
+      documented.set(match[1], match[2])
+    }
+    for (const [name, value] of codeConstants) {
+      if (!documented.has(name)) fail(`tunable ${name} is not documented in foomatic-assistant.md`)
+      else if (documented.get(name) !== value) {
+        fail(`tunable ${name}: code=${value}, documented=${documented.get(name)}`)
+      }
+    }
+    for (const name of documented.keys()) {
+      if (!codeConstants.has(name)) fail(`documented tunable ${name} no longer exists in constants.ts`)
+    }
+    for (const file of ["foomatic-assistant.md", "foomatic-assistant-queries.md"]) {
+      const full = path.join(ROOT, "docs", file)
+      if (fs.existsSync(full)) {
+        const content = fs.readFileSync(full, "utf8")
+        for (const pattern of BANNED_PATTERNS) {
+          if (pattern.test(content)) fail(`banned wording in docs/${file}: ${pattern}`)
+        }
+      }
+    }
+  }
+
+  // ---- summary -------------------------------------------------------------
+  console.log(
+    JSON.stringify(
+      {
+        corpus: { cases: CORPUS.length, intentPasses, checksRun, checkPasses },
+        grounding: { responsesSwept: groundedResponses },
+        latencyMs: { median: Number(median.toFixed(2)), p95: Number(p95.toFixed(2)), samples: durations.length },
+        artifactBytes: sizes,
+        catalogSize: catalog.length,
+        failures: failures.length,
+      },
+      null,
+      2
+    )
+  )
+  if (failures.length > 0) {
+    console.error(`\n${failures.length} failure(s):`)
+    for (const failure of failures) console.error(` - ${failure}`)
+    process.exit(1)
+  }
+  console.log("\nassistant-eval: all checks passed")
+}
+
+main().catch(error => {
+  console.error("assistant-eval crashed:", error)
+  process.exit(1)
+})
diff --git a/tools/eval/check-docs.mjs b/tools/eval/check-docs.mjs
new file mode 100644
index 00000000..77357e21
--- /dev/null
+++ b/tools/eval/check-docs.mjs
@@ -0,0 +1,63 @@
+// Guards against documentation drift: every tunable listed in
+// docs/foomatic-recommendation-quality.md must exist in the source with the
+// documented value, and every scoring constant in the source must be listed.
+// Exits non-zero on any mismatch so it can run as part of `yarn foomatic:eval`.
+import fs from "fs"
+
+const SOURCES = [
+  "scripts/foomatic/vectorize.ts",
+  "scripts/foomatic/compute-similarity.ts",
+  "lib/foomatic/scoring.ts",
+]
+const DOC = "docs/foomatic-recommendation-quality.md"
+
+// The constants that define pipeline behaviour. Add new tunables here so the
+// check fails loudly until they are documented.
+const TRACKED = [
+  "RECOMMENDED_DRIVER_WEIGHT", "COMMANDSET_WEIGHT", "SUPPORTED_DRIVER_WEIGHT",
+  "COLOR_WEIGHT", "LANG_WEIGHT", "RESOLUTION_WEIGHT", "TYPE_WEIGHT",
+  "LANG_LEVEL_WEIGHT", "FUNCTIONALITY_WEIGHT", "MIN_COMMANDSET_FREQUENCY",
+  "TOP_K", "MIN_SIMILARITY_SCORE", "EVIDENCE_TAU",
+  "TYPE_CONFLICT_PENALTY", "COLOR_CONFLICT_PENALTY",
+  "RESOLUTION_CONFLICT_PENALTY", "RESOLUTION_CONFLICT_RATIO",
+  "CONFIDENCE_HIGH_THRESHOLD", "CONFIDENCE_GOOD_THRESHOLD",
+  "CONFIDENCE_MODERATE_THRESHOLD",
+]
+
+const src = SOURCES.map((f) => fs.readFileSync(f, "utf8")).join("\n")
+const doc = fs.readFileSync(DOC, "utf8")
+
+let failures = 0
+for (const name of TRACKED) {
+  const inCode = new RegExp(`const ${name} = ([0-9.]+)`).exec(src)
+  const inDoc = new RegExp(`\\| \`${name}\`\\s*\\|\\s*([0-9.]+)`).exec(doc)
+
+  if (!inCode) {
+    console.error(`MISSING IN CODE : ${name} (tracked but not defined in any source file)`)
+    failures++
+  } else if (!inDoc) {
+    console.error(`UNDOCUMENTED    : ${name} = ${inCode[1]} (not in ${DOC})`)
+    failures++
+  } else if (Number(inCode[1]) !== Number(inDoc[1])) {
+    console.error(`VALUE MISMATCH  : ${name} code=${inCode[1]} doc=${inDoc[1]}`)
+    failures++
+  }
+}
+
+// Terminology that must not reappear anywhere in the docs.
+const BANNED = [/Exact match/, /% match\b/, /EXACT_MATCH_THRESHOLD/, /STRONG_MATCH_PERCENT/, /MODERATE_MATCH_PERCENT/]
+for (const file of fs.readdirSync("docs").filter((f) => f.startsWith("foomatic-"))) {
+  const text = fs.readFileSync(`docs/${file}`, "utf8")
+  for (const re of BANNED) {
+    if (re.test(text)) {
+      console.error(`STALE TERM      : ${re} in docs/${file}`)
+      failures++
+    }
+  }
+}
+
+if (failures > 0) {
+  console.error(`\ndoc-drift check FAILED: ${failures} problem(s)`)
+  process.exit(1)
+}
+console.log(`doc-drift check OK: ${TRACKED.length} tunables match ${DOC}; no stale terminology`)
diff --git a/tools/eval/grade.mjs b/tools/eval/grade.mjs
new file mode 100644
index 00000000..bcde5182
--- /dev/null
+++ b/tools/eval/grade.mjs
@@ -0,0 +1,68 @@
+// Applies a fixed rubric to every top-3 recommendation of the sampled printers.
+// Rubric (deterministic, applied uniformly — no per-case judgement):
+//   Incorrect : 0 reasons, OR type contradiction, OR colour contradiction, OR >=4x dpi gap
+//   Weak      : only 1 reason, OR the sole substantive reason is a generic/catch-all driver
+//   Acceptable: 2-3 reasons and no contradiction
+//   Good      : 4-6 reasons, or same product series
+//   Excellent : >=7 reasons, or a specific (non-generic) shared preferred driver + >=4 reasons
+import fs from "fs"
+
+const P = JSON.parse(fs.readFileSync(`${process.cwd()}/public/foomatic-db/printers.json`, "utf8")).printers
+const R = JSON.parse(fs.readFileSync(`${process.cwd()}/public/foomatic-db/recommendations.json`, "utf8")).recommendations
+const byId = new Map(P.map((p) => [p.id, p]))
+const sampleArg = process.argv.find((a) => a.endsWith(".json"))
+const sample = sampleArg
+  ? JSON.parse(fs.readFileSync(sampleArg, "utf8"))
+  : (await import("./sample.mjs")).sample
+
+const GENERIC = new Set(["postscript", "pdf", "omni", "gutenprint", "laserjet", "hpijs", "pxlmono", "pxlcolor", "gdi"])
+const NORM = [[/^Postscript/i, "postscript"], [/^PDF/i, "pdf"], [/^pxlmono/i, "pxlmono"], [/^pxlcolor/i, "pxlcolor"],
+  [/^foo2zjs/i, "foo2zjs"], [/^foo2hp/i, "foo2hp"], [/^foo2qpdl/i, "foo2qpdl"], [/^hpijs/i, "hpijs"],
+  [/^gutenprint/i, "gutenprint"], [/^gimp-print/i, "gutenprint"], [/^hplip/i, "hplip"], [/^ljet/i, "laserjet"], [/^lj/i, "laserjet"]]
+const fam = (n) => { const s = (n || "").trim().replace(/^driver\//i, ""); for (const [re, f] of NORM) if (re.test(s)) return f; return s.toLowerCase() }
+const recFam = (p) => { const d = (p.recommended_driver || "").trim(); return d ? fam(d) : null }
+const series = (p) => `${p.manufacturer}|${(p.model || "").replace(/[\d_\-].*$/, "")}`
+
+function grade(a, b, r) {
+  const n = r.sharedFeatures.length
+  if (n === 0) return ["Incorrect", "no stated reason at all"]
+  if (a.type && b.type && a.type !== "unknown" && b.type !== "unknown" && a.type !== b.type) return ["Incorrect", `type contradiction ${a.type} vs ${b.type}`]
+  if (a.color === true && b.color === false) return ["Incorrect", "colour contradiction: colour vs mono"]
+  if (a.color === false && b.color === true) return ["Incorrect", "colour contradiction: mono vs colour"]
+  if (a.maxDpi != null && b.maxDpi != null) {
+    const hi = Math.max(a.maxDpi, b.maxDpi), lo = Math.min(a.maxDpi, b.maxDpi)
+    if (hi / lo >= 4) return ["Incorrect", `dpi gap ${a.maxDpi} vs ${b.maxDpi}`]
+  }
+  const rf = recFam(a)
+  const specificDriver = rf && rf === recFam(b) && !GENERIC.has(rf)
+  if (n === 1) return ["Weak", `single reason: ${r.sharedFeatures[0]}`]
+  if (rf && GENERIC.has(rf) && n <= 3) return ["Weak", `generic driver (${rf}) + only ${n} reasons`]
+  if (n >= 7 || (specificDriver && n >= 4)) return ["Excellent", specificDriver ? `specific driver ${rf}, ${n} reasons` : `${n} corroborating reasons`]
+  if (n >= 4 || series(a) === series(b)) return ["Good", series(a) === series(b) ? "same product series" : `${n} reasons`]
+  return ["Acceptable", `${n} reasons`]
+}
+
+const tally = {}
+const rows = []
+for (const { id, strata } of sample) {
+  const a = byId.get(id)
+  for (const [i, r] of (R[id] || []).slice(0, 3).entries()) {
+    const b = byId.get(r.id)
+    const [g, why] = grade(a, b, r)
+    tally[g] = (tally[g] || 0) + 1
+    rows.push({ id, strata: strata.join(","), rank: i + 1, rec: r.id, score: r.score, n: r.sharedFeatures.length, grade: g, why,
+      sameMfr: a.manufacturer === b.manufacturer })
+  }
+}
+if (process.argv.includes("--rows")) {
+  for (const r of rows) console.log(`${r.id.padEnd(34)} #${r.rank} -> ${r.rec.padEnd(34)} s=${String(r.score).padEnd(5)} n=${String(r.n).padStart(2)} ${r.sameMfr ? "SAME" : "    "} ${r.grade.padEnd(10)} ${r.why}`)
+}
+const total = Object.values(tally).reduce((a, b) => a + b, 0)
+console.log("\nGRADE DISTRIBUTION over", total, "sampled recommendations")
+for (const g of ["Excellent", "Good", "Acceptable", "Weak", "Incorrect"]) {
+  const c = tally[g] || 0
+  console.log(`  ${g.padEnd(11)} ${String(c).padStart(4)}  ${(c / total * 100).toFixed(1)}%`)
+}
+const goodish = (tally.Excellent || 0) + (tally.Good || 0)
+console.log(`  => usable (Excellent+Good): ${(goodish / total * 100).toFixed(1)}%`)
+console.log(`  => problematic (Weak+Incorrect): ${(((tally.Weak || 0) + (tally.Incorrect || 0)) / total * 100).toFixed(1)}%`)
diff --git a/tools/eval/metrics.mjs b/tools/eval/metrics.mjs
new file mode 100644
index 00000000..f5e2b0b7
--- /dev/null
+++ b/tools/eval/metrics.mjs
@@ -0,0 +1,190 @@
+// Ranking-quality metrics for the Foomatic recommendation engine.
+// Pure measurement: reads generated artifacts, computes, prints JSON.
+import fs from "fs"
+
+const ROOT = process.cwd()
+const P = JSON.parse(fs.readFileSync(`${ROOT}/public/foomatic-db/printers.json`, "utf8")).printers
+const R = JSON.parse(fs.readFileSync(`${ROOT}/public/foomatic-db/recommendations.json`, "utf8")).recommendations
+const byId = new Map(P.map((p) => [p.id, p]))
+
+const NORM = [[/^Postscript/i, "postscript"], [/^PDF/i, "pdf"], [/^pxlmono/i, "pxlmono"], [/^pxlcolor/i, "pxlcolor"],
+  [/^foo2zjs/i, "foo2zjs"], [/^foo2hp/i, "foo2hp"], [/^foo2qpdl/i, "foo2qpdl"], [/^hpijs/i, "hpijs"],
+  [/^gutenprint/i, "gutenprint"], [/^gimp-print/i, "gutenprint"], [/^hplip/i, "hplip"], [/^ljet/i, "laserjet"], [/^lj/i, "laserjet"]]
+const fam = (n) => { const s = (n || "").trim().replace(/^driver\//i, ""); for (const [re, f] of NORM) if (re.test(s)) return f; return s.toLowerCase() }
+const recFam = (p) => { const d = (p.recommended_driver || "").trim(); return d ? fam(d) : null }
+const REBADGE = new Set(["Ricoh", "Lanier", "NRG", "Gestetner", "Savin", "Infotec", "Rex-Rotary", "Nashuatec"])
+
+const clusterOf = {}
+for (const p of P) { const f = recFam(p); if (f) clusterOf[f] = (clusterOf[f] || 0) + 1 }
+
+const top3 = []
+for (const [pid, recs] of Object.entries(R)) for (const r of recs.slice(0, 3)) top3.push([pid, r])
+
+const m = {}
+m.printers = P.length
+m.printersWithRecs = Object.values(R).filter((r) => r.length > 0).length
+m.printersWithZeroRecs = Object.values(R).filter((r) => r.length === 0).length
+m.top3Count = top3.length
+
+const avg = (a) => (a.length ? a.reduce((x, y) => x + y, 0) / a.length : 0)
+
+// --- score distribution ---
+const scores = top3.map(([, r]) => r.score).sort((a, b) => a - b)
+const q = (f) => scores[Math.min(scores.length - 1, Math.floor(scores.length * f))]
+m.scoreMean = +avg(scores).toFixed(4)
+m.scoreP10 = q(0.10); m.scoreP50 = q(0.50); m.scoreP90 = q(0.90)
+m.saturationPct = +(scores.filter((s) => s >= 0.9995).length / scores.length * 100).toFixed(2)
+m.perfectMatches = scores.filter((s) => s >= 0.9995).length
+const hist = {}
+for (const s of scores) { const b = (Math.floor(s * 10) / 10).toFixed(1); hist[b] = (hist[b] || 0) + 1 }
+m.scoreHistogram = hist
+
+// --- ties / arbitrariness ---
+let tieSum = 0, allTie = 0, nWith = 0
+for (const recs of Object.values(R)) {
+  if (!recs.length) continue
+  nWith++
+  const t = recs[0].score
+  const c = recs.filter((r) => r.score === t).length
+  tieSum += c
+  if (c === recs.length && recs.length >= 3) allTie++
+}
+m.avgTiedAtTopScore = +(tieSum / nWith).toFixed(2)
+m.pctAllRetainedTied = +(allTie / nWith * 100).toFixed(2)
+
+// --- evidence quality ---
+const featCounts = top3.map(([, r]) => r.sharedFeatures.length)
+m.avgSharedFeatures = +avg(featCounts).toFixed(2)
+m.pctZeroExplanation = +(featCounts.filter((c) => c === 0).length / featCounts.length * 100).toFixed(2)
+m.pctSingleFeature = +(featCounts.filter((c) => c === 1).length / featCounts.length * 100).toFixed(2)
+const GENERIC = new Set(["postscript", "pdf", "omni", "gutenprint", "laserjet", "hpijs", "pxlmono", "pxlcolor"])
+let genericOnly = 0
+for (const [, r] of top3) {
+  if (r.sharedFeatures.length !== 1) continue
+  const mm = /^Preferred Linux driver: (.+)$/.exec(r.sharedFeatures[0])
+  if (mm && GENERIC.has(mm[1])) genericOnly++
+}
+m.pctGenericDriverOnly = +(genericOnly / top3.length * 100).toFixed(2)
+m.pctFromLargeCluster = +(top3.filter(([pid]) => { const f = recFam(byId.get(pid)); return f && (clusterOf[f] || 0) >= 200 }).length / top3.length * 100).toFixed(2)
+
+// --- confidence/evidence correlation (the key defect) ---
+const weak = top3.filter(([, r]) => r.sharedFeatures.length <= 1).map(([, r]) => r.score)
+const strong = top3.filter(([, r]) => r.sharedFeatures.length >= 2).map(([, r]) => r.score)
+m.meanScoreWeakEvidence = +avg(weak).toFixed(4)
+m.meanScoreStrongEvidence = +avg(strong).toFixed(4)
+m.confidenceInversion = +(m.meanScoreWeakEvidence - m.meanScoreStrongEvidence).toFixed(4) // > 0 means broken
+{
+  const xs = featCounts, ys = top3.map(([, r]) => r.score)
+  const mx = avg(xs), my = avg(ys)
+  let num = 0, dx = 0, dy = 0
+  for (let i = 0; i < xs.length; i++) { const a = xs[i] - mx, b = ys[i] - my; num += a * b; dx += a * a; dy += b * b }
+  m.corrEvidenceScore = +(num / Math.sqrt(dx * dy)).toFixed(4) // want strongly positive
+}
+
+// --- diversity ---
+let sameMfr = 0, cross = 0, rebadge = 0, allSameMfr = 0, full = 0
+const recCounts = {}
+for (const [pid, recs] of Object.entries(R)) {
+  const t = recs.slice(0, 3)
+  if (t.length === 3) {
+    full++
+    const a = byId.get(pid)
+    const set = new Set(t.map((r) => byId.get(r.id).manufacturer))
+    if (set.size === 1 && set.has(a.manufacturer)) allSameMfr++
+  }
+  for (const r of t) {
+    const a = byId.get(pid), b = byId.get(r.id)
+    recCounts[r.id] = (recCounts[r.id] || 0) + 1
+    if (a.manufacturer === b.manufacturer) sameMfr++
+    else { cross++; if (REBADGE.has(a.manufacturer) && REBADGE.has(b.manufacturer)) rebadge++ }
+  }
+}
+m.pctSameManufacturer = +(sameMfr / top3.length * 100).toFixed(2)
+m.pctCrossVendor = +(cross / top3.length * 100).toFixed(2)
+m.pctRebadgeOfCross = +(rebadge / cross * 100).toFixed(2)
+m.pctGenuinelyNovelVendor = +((cross - rebadge) / top3.length * 100).toFixed(2)
+m.pctAll3SameManufacturer = +(allSameMfr / full * 100).toFixed(2)
+
+// catalogue coverage + exposure concentration
+const counts = Object.values(recCounts)
+m.distinctPrintersRecommended = counts.length
+m.catalogueCoveragePct = +(counts.length / P.length * 100).toFixed(2)
+{
+  const tot = counts.reduce((a, b) => a + b, 0)
+  let H = 0
+  for (const c of counts) { const p = c / tot; H -= p * Math.log2(p) }
+  m.recommendationEntropyBits = +H.toFixed(3)
+  m.maxEntropyBits = +Math.log2(P.length).toFixed(3)
+  m.entropyRatio = +(H / Math.log2(P.length)).toFixed(4)
+  const s = counts.slice().sort((a, b) => a - b)
+  let cum = 0, g = 0
+  const n = s.length, t = s.reduce((a, b) => a + b, 0)
+  for (let i = 0; i < n; i++) { cum += s[i]; g += cum / t }
+  m.giniConcentration = +(1 - 2 * g / n + 1 / n).toFixed(4)
+}
+let mixedDriver = 0
+for (const [, recs] of Object.entries(R)) {
+  const t = recs.slice(0, 3); if (t.length < 3) continue
+  const s = new Set(t.map((r) => recFam(byId.get(r.id))))
+  if (s.size > 1) mixedDriver++
+}
+m.pctTop3WithMixedDrivers = +(mixedDriver / full * 100).toFixed(2)
+
+// --- contradictions ---
+let typeBad = 0, typeBoth = 0, colorBad = 0, colorBoth = 0, dpiFar = 0, dpiBoth = 0
+for (const [pid, r] of top3) {
+  const a = byId.get(pid), b = byId.get(r.id)
+  if (a.type && b.type && a.type !== "unknown" && b.type !== "unknown") { typeBoth++; if (a.type !== b.type) typeBad++ }
+  if (a.color != null && b.color != null && a.color !== "unknown" && b.color !== "unknown") { colorBoth++; if (a.color !== b.color) colorBad++ }
+  if (a.maxDpi != null && b.maxDpi != null) { dpiBoth++; const hi = Math.max(a.maxDpi, b.maxDpi), lo = Math.min(a.maxDpi, b.maxDpi); if (hi / lo >= 4) dpiFar++ }
+}
+m.pctTypeContradiction = +(typeBad / typeBoth * 100).toFixed(2)
+m.pctColorContradiction = +(colorBad / colorBoth * 100).toFixed(2)
+m.pctDpiContradiction4x = +(dpiFar / dpiBoth * 100).toFixed(2)
+
+// --- explanation truthfulness: validate every user-visible claim ---
+let claims = 0, falseClaims = 0
+const falseBy = {}
+const bump = (k) => { falseBy[k] = (falseBy[k] || 0) + 1; falseClaims++ }
+for (const [pid, r] of top3) {
+  const a = byId.get(pid), b = byId.get(r.id)
+  const aFams = new Set((a.drivers || []).map((d) => fam(d.name)))
+  const bFams = new Set((b.drivers || []).map((d) => fam(d.name)))
+  const aCmd = new Set(a.commandsetTokens || []), bCmd = new Set(b.commandsetTokens || [])
+  for (const f of r.sharedFeatures) {
+    claims++
+    let mm
+    if ((mm = /^Preferred Linux driver: (.+)$/.exec(f))) {
+      if (!(recFam(a) === mm[1] && recFam(b) === mm[1])) bump("preferredDriver")
+    } else if ((mm = /^Shared driver family: (.+)$/.exec(f))) {
+      if (!(aFams.has(mm[1]) && bFams.has(mm[1]))) bump("sharedDriverFamily")
+    } else if (/^(Laser|Inkjet|Dot-matrix) printer$/.test(f)) {
+      const want = { "Laser printer": "laser", "Inkjet printer": "inkjet", "Dot-matrix printer": "dot-matrix" }[f]
+      if (!(a.type === want && b.type === want)) bump("printerType")
+    } else if (f === "Color printing") {
+      if (!(a.color === true && b.color === true)) bump("colorPrinting")
+    } else if ((mm = /^Shared command set: (.+)$/.exec(f))) {
+      const LAB = { "PostScript": "POSTSCRIPT", "PCL XL (PCL6)": "PCLXL", "PCL5e": "PCL5E", "PCL": "PCL", "PDF printing": "PDF",
+        "Epson ESC/P2": "ESCPL2", "Epson ESC/P-R": "ESCPR2", "Epson BDC": "BDC", "Epson D4": "D4", "Epson D4PX": "D4PX", "PJL": "PJL", "MLC": "MLC" }
+      const tok = LAB[mm[1]] ?? mm[1]
+      if (!(aCmd.has(tok) && bCmd.has(tok))) bump("commandSet")
+    } else if ((mm = /^PostScript (\d)$/.exec(f))) {
+      if (!(a.psLevel === +mm[1] && b.psLevel === +mm[1])) bump("postscriptLevel")
+    } else if (/^PCL (6 \/ PCL XL|5e|\d)$/.test(f)) {
+      const lv = f === "PCL 6 / PCL XL" ? 6 : f === "PCL 5e" ? 5 : +f.slice(4)
+      if (!(a.pclLevel === lv && b.pclLevel === lv)) bump("pclLevel")
+    } else if ((mm = /^(\d+)(\+?) dpi resolution$/.exec(f))) {
+      const stated = +mm[1], plus = mm[2] === "+"
+      const ok = plus ? (a.maxDpi > stated && b.maxDpi > stated) : (a.maxDpi === stated && b.maxDpi === stated)
+      if (!ok) bump(plus ? "dpiTierPlus" : "dpiExact")
+    } else if (/^(Similar resolution|Excellent|Good|Basic) /.test(f)) {
+      // range-style or support-grade labels: verified elsewhere
+    }
+  }
+}
+m.totalClaims = claims
+m.falseOrMisleadingClaims = falseClaims
+m.pctClaimsFalseOrMisleading = +(falseClaims / claims * 100).toFixed(2)
+m.falseClaimBreakdown = falseBy
+
+console.log(JSON.stringify(m, null, 1))
diff --git a/tools/eval/pairs.mjs b/tools/eval/pairs.mjs
new file mode 100644
index 00000000..b9f06f33
--- /dev/null
+++ b/tools/eval/pairs.mjs
@@ -0,0 +1,73 @@
+// Maintainer-facing inspection of real recommendation pairs.
+//
+// Usage: node tools/eval/pairs.mjs [sample.json]
+// With no argument the deterministic sample is generated in-process.
+//
+// For every recommendation of every sampled printer it prints the full source
+// and target attributes next to the user-visible explanation, then buckets the
+// pair into one of four defensibility categories:
+//
+//   good        multiple independent discriminative signals agree
+//   low-value   technically correct but a rebadge / same-series sibling,
+//               so it offers the user little new information
+//   weak        rests on a single signal or a generic catch-all driver
+//   problematic capability conflict or unexplained pairing survives
+//
+// The bucketing is deterministic so the same artifacts always produce the
+// same report. It is a lens for human review, not a ground-truth label.
+import fs from "fs"
+
+const P = JSON.parse(fs.readFileSync(`${process.cwd()}/public/foomatic-db/printers.json`, "utf8")).printers
+const R = JSON.parse(fs.readFileSync(`${process.cwd()}/public/foomatic-db/recommendations.json`, "utf8")).recommendations
+const byId = new Map(P.map((p) => [p.id, p]))
+const sampleArg = process.argv.find((a) => a.endsWith(".json"))
+const sample = sampleArg
+  ? JSON.parse(fs.readFileSync(sampleArg, "utf8"))
+  : (await import("./sample.mjs")).sample
+
+const REBADGE = new Set(["Ricoh", "Lanier", "NRG", "Gestetner", "Savin", "Infotec", "Rex-Rotary", "Nashuatec"])
+const GENERIC = new Set(["postscript", "pdf", "omni", "gutenprint", "laserjet", "hpijs", "pxlmono", "pxlcolor", "gdi"])
+const NORM = [[/^Postscript/i, "postscript"], [/^PDF/i, "pdf"], [/^pxlmono/i, "pxlmono"], [/^pxlcolor/i, "pxlcolor"],
+  [/^foo2zjs/i, "foo2zjs"], [/^foo2hp/i, "foo2hp"], [/^foo2qpdl/i, "foo2qpdl"], [/^hpijs/i, "hpijs"],
+  [/^gutenprint/i, "gutenprint"], [/^gimp-print/i, "gutenprint"], [/^hplip/i, "hplip"], [/^ljet/i, "laserjet"], [/^lj/i, "laserjet"]]
+const fam = (n) => { const s = (n || "").trim().replace(/^driver\//i, ""); for (const [re, f] of NORM) if (re.test(s)) return f; return s.toLowerCase() }
+const recFam = (p) => { const d = (p.recommended_driver || "").trim(); return d ? fam(d) : null }
+const series = (p) => `${p.manufacturer}|${(p.model || "").replace(/[\d_\-].*$/, "")}`
+
+const cap = (p) =>
+  `type=${p.type ?? "?"} color=${p.color} dpi=${p.maxDpi ?? "?"} ps=${p.psLevel ?? "-"} pcl=${p.pclLevel ?? "-"} ` +
+  `func=${p.functionality ?? "?"} drv=${recFam(p) ?? "none"} cmds=[${(p.commandsetTokens ?? []).join(",")}] drivers=${(p.drivers ?? []).length}`
+
+function bucket(a, b, r) {
+  const n = r.sharedFeatures.length
+  if (n === 0) return "problematic"
+  if (a.type && b.type && a.type !== "unknown" && b.type !== "unknown" && a.type !== b.type) return "problematic"
+  if ((a.color === true && b.color === false) || (a.color === false && b.color === true)) return "problematic"
+  if (a.maxDpi != null && b.maxDpi != null && Math.max(a.maxDpi, b.maxDpi) / Math.min(a.maxDpi, b.maxDpi) >= 4) return "problematic"
+  const rf = recFam(a)
+  if (n === 1 || (rf && GENERIC.has(rf) && n <= 3)) return "weak"
+  const rebadge = REBADGE.has(a.manufacturer) && REBADGE.has(b.manufacturer)
+  if (rebadge || series(a) === series(b)) return "low-value"
+  return "good"
+}
+
+const buckets = { good: [], "low-value": [], weak: [], problematic: [] }
+for (const { id } of sample) {
+  const a = byId.get(id)
+  for (const [i, r] of (R[id] || []).slice(0, 3).entries()) {
+    const b = byId.get(r.id)
+    buckets[bucket(a, b, r)].push({ a, b, r, rank: i + 1 })
+  }
+}
+
+const PER = Number(process.env.PAIRS_PER_BUCKET ?? 4)
+for (const [name, list] of Object.entries(buckets)) {
+  console.log(`\n===== ${name.toUpperCase()} (${list.length} in sample, showing first ${Math.min(PER, list.length)}) =====`)
+  for (const { a, b, r, rank } of list.slice(0, PER)) {
+    console.log(`\n${a.id}  ->  #${rank} ${b.id}   score=${r.score}`)
+    console.log(`  source : ${cap(a)}`)
+    console.log(`  target : ${cap(b)}`)
+    console.log(`  shown  : ${r.sharedFeatures.join("; ") || "(none)"}`)
+  }
+}
+console.log("\nBucket totals:", Object.fromEntries(Object.entries(buckets).map(([k, v]) => [k, v.length])))
diff --git a/tools/eval/sample.mjs b/tools/eval/sample.mjs
new file mode 100644
index 00000000..fe8d7ec0
--- /dev/null
+++ b/tools/eval/sample.mjs
@@ -0,0 +1,69 @@
+// Deterministic stratified sample for qualitative recommendation review.
+// Strategy: define disjoint-ish strata by technology / form-factor / rarity,
+// sort each stratum by id (stable), take evenly-spaced picks. No randomness,
+// no cherry-picking: the same input data always yields the same sample.
+import fs from "fs"
+
+const P = JSON.parse(fs.readFileSync(`${process.cwd()}/public/foomatic-db/printers.json`, "utf8")).printers
+const R = JSON.parse(fs.readFileSync(`${process.cwd()}/public/foomatic-db/recommendations.json`, "utf8")).recommendations
+
+const nameOf = (p) => `${p.manufacturer} ${p.model}`
+const drvNames = (p) => (p.drivers || []).map((d) => d.name).join(" ").toLowerCase()
+
+const STRATA = {
+  laser: (p) => p.type === "laser",
+  inkjet: (p) => p.type === "inkjet",
+  dotmatrix: (p) => p.type === "dot-matrix",
+  labelThermal: (p) => /label|dymo|costar|slp|zebra|brother.*ql|thermal/i.test(nameOf(p)) || /pbm2lwxl|slap|ptouch/.test(drvNames(p)),
+  dyeSub: (p) => /printiva|dye|md-\d|p-\d{3}|cp\d{2}|selphy|picturemate/i.test(nameOf(p)) || /ppmtomd|md2k/.test(drvNames(p)),
+  mfp: (p) => /mfp|mfc|bizhub|ir-adv|imagerunner|workcentre|laserjet.*m\d|aficio|im\d/i.test(nameOf(p)),
+  industrial: (p) => /digimaster|production|nuvera|docutech|varioprint|indigo|press/i.test(nameOf(p)),
+  color: (p) => p.color === true,
+  mono: (p) => p.color === false,
+  highRes: (p) => p.maxDpi != null && p.maxDpi >= 2400,
+  lowRes: (p) => p.maxDpi != null && p.maxDpi <= 300,
+  postscript: (p) => p.psLevel != null,
+  // rarity by how many printers share the same recommended driver
+}
+const NORM = [[/^Postscript/i, "postscript"], [/^PDF/i, "pdf"], [/^pxlmono/i, "pxlmono"], [/^pxlcolor/i, "pxlcolor"],
+  [/^foo2zjs/i, "foo2zjs"], [/^foo2hp/i, "foo2hp"], [/^foo2qpdl/i, "foo2qpdl"], [/^hpijs/i, "hpijs"],
+  [/^gutenprint/i, "gutenprint"], [/^gimp-print/i, "gutenprint"], [/^hplip/i, "hplip"], [/^ljet/i, "laserjet"], [/^lj/i, "laserjet"]]
+const fam = (n) => { const s = (n || "").trim().replace(/^driver\//i, ""); for (const [re, f] of NORM) if (re.test(s)) return f; return s.toLowerCase() }
+const recFam = (p) => { const d = (p.recommended_driver || "").trim(); return d ? fam(d) : null }
+const cluster = {}
+for (const p of P) { const f = recFam(p); if (f) cluster[f] = (cluster[f] || 0) + 1 }
+STRATA.commonDriver = (p) => (cluster[recFam(p)] || 0) >= 500
+STRATA.rareDriver = (p) => { const c = cluster[recFam(p)] || 0; return c > 0 && c <= 3 }
+
+const PER_STRATUM = 4
+const picked = new Map()
+for (const [name, pred] of Object.entries(STRATA)) {
+  const pool = P.filter((p) => pred(p) && (R[p.id] || []).length > 0).sort((a, b) => a.id.localeCompare(b.id))
+  if (!pool.length) continue
+  const step = Math.max(1, Math.floor(pool.length / PER_STRATUM))
+  for (let i = 0, taken = 0; i < pool.length && taken < PER_STRATUM; i += step, taken++) {
+    const p = pool[i]
+    if (!picked.has(p.id)) picked.set(p.id, [])
+    picked.get(p.id).push(name)
+  }
+}
+// manufacturer breadth: one printer from each of 20 evenly-spaced manufacturers
+const mfrs = [...new Set(P.map((p) => p.manufacturer))].sort()
+const mstep = Math.max(1, Math.floor(mfrs.length / 20))
+for (let i = 0, t = 0; i < mfrs.length && t < 20; i += mstep, t++) {
+  const pool = P.filter((p) => p.manufacturer === mfrs[i] && (R[p.id] || []).length > 0).sort((a, b) => a.id.localeCompare(b.id))
+  if (!pool.length) continue
+  const p = pool[Math.floor(pool.length / 2)]
+  if (!picked.has(p.id)) picked.set(p.id, [])
+  picked.get(p.id).push(`mfr:${mfrs[i]}`)
+}
+
+const out = [...picked.entries()].map(([id, strata]) => ({ id, strata })).sort((a, b) => a.id.localeCompare(b.id))
+
+// Importable for grade.mjs / pairs.mjs; prints JSON when run directly.
+export const sample = out
+
+import { pathToFileURL } from "url"
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  console.log(JSON.stringify(out, null, 1))
+}
diff --git a/tsconfig.json b/tsconfig.json
index 7a452cc2..64bfe3ac 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -32,6 +32,7 @@
   "include": [
     "next-env.d.ts",
     "**/*.ts",
+    "**/*.mts",
     "**/*.tsx",
     ".next/types/**/*.ts"
   ],
diff --git a/vitest.config.mts b/vitest.config.mts
new file mode 100644
index 00000000..aadf3674
--- /dev/null
+++ b/vitest.config.mts
@@ -0,0 +1,17 @@
+import { defineConfig } from "vitest/config"
+import path from "path"
+import { fileURLToPath } from "url"
+
+const rootDir = path.dirname(fileURLToPath(import.meta.url))
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["lib/**/*.test.ts", "scripts/**/*.test.ts"],
+  },
+  resolve: {
+    alias: {
+      "@": rootDir,
+    },
+  },
+})
diff --git a/yarn.lock b/yarn.lock
index c058ac9a..f911edda 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -615,7 +615,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@jridgewell/sourcemap-codec@npm:^1.4.14, @jridgewell/sourcemap-codec@npm:^1.5.0":
+"@jridgewell/sourcemap-codec@npm:^1.4.14, @jridgewell/sourcemap-codec@npm:^1.5.0, @jridgewell/sourcemap-codec@npm:^1.5.5":
   version: 1.5.5
   resolution: "@jridgewell/sourcemap-codec@npm:1.5.5"
   checksum: 10c0/f9e538f302b63c0ebc06eecb1dd9918dd4289ed36147a0ddce35d6ea4d7ebbda243cda7b2213b6a5e1d8087a298d5cf630fb2bd39329cdecb82017023f6081a0
@@ -772,6 +772,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@oxc-project/types@npm:=0.144.0":
+  version: 0.144.0
+  resolution: "@oxc-project/types@npm:0.144.0"
+  checksum: 10c0/997c6c33f09706af604ece0e99c698965757887aca4b42c5fb5ddcb11c39876c1e824b188b1e6582276355468a9b13f955d3b822d3b532cd6bedbeb64b603ff0
+  languageName: node
+  linkType: hard
+
 "@radix-ui/react-compose-refs@npm:1.1.2":
   version: 1.1.2
   resolution: "@radix-ui/react-compose-refs@npm:1.1.2"
@@ -800,6 +807,111 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@rolldown/binding-android-arm64@npm:1.2.4":
+  version: 1.2.4
+  resolution: "@rolldown/binding-android-arm64@npm:1.2.4"
+  conditions: os=android & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@rolldown/binding-darwin-arm64@npm:1.2.4":
+  version: 1.2.4
+  resolution: "@rolldown/binding-darwin-arm64@npm:1.2.4"
+  conditions: os=darwin & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@rolldown/binding-darwin-x64@npm:1.2.4":
+  version: 1.2.4
+  resolution: "@rolldown/binding-darwin-x64@npm:1.2.4"
+  conditions: os=darwin & cpu=x64
+  languageName: node
+  linkType: hard
+
+"@rolldown/binding-freebsd-x64@npm:1.2.4":
+  version: 1.2.4
+  resolution: "@rolldown/binding-freebsd-x64@npm:1.2.4"
+  conditions: os=freebsd & cpu=x64
+  languageName: node
+  linkType: hard
+
+"@rolldown/binding-linux-arm-gnueabihf@npm:1.2.4":
+  version: 1.2.4
+  resolution: "@rolldown/binding-linux-arm-gnueabihf@npm:1.2.4"
+  conditions: os=linux & cpu=arm
+  languageName: node
+  linkType: hard
+
+"@rolldown/binding-linux-arm64-gnu@npm:1.2.4":
+  version: 1.2.4
+  resolution: "@rolldown/binding-linux-arm64-gnu@npm:1.2.4"
+  conditions: os=linux & cpu=arm64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@rolldown/binding-linux-arm64-musl@npm:1.2.4":
+  version: 1.2.4
+  resolution: "@rolldown/binding-linux-arm64-musl@npm:1.2.4"
+  conditions: os=linux & cpu=arm64 & libc=musl
+  languageName: node
+  linkType: hard
+
+"@rolldown/binding-linux-ppc64-gnu@npm:1.2.4":
+  version: 1.2.4
+  resolution: "@rolldown/binding-linux-ppc64-gnu@npm:1.2.4"
+  conditions: os=linux & cpu=ppc64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@rolldown/binding-linux-s390x-gnu@npm:1.2.4":
+  version: 1.2.4
+  resolution: "@rolldown/binding-linux-s390x-gnu@npm:1.2.4"
+  conditions: os=linux & cpu=s390x & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@rolldown/binding-linux-x64-gnu@npm:1.2.4":
+  version: 1.2.4
+  resolution: "@rolldown/binding-linux-x64-gnu@npm:1.2.4"
+  conditions: os=linux & cpu=x64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@rolldown/binding-linux-x64-musl@npm:1.2.4":
+  version: 1.2.4
+  resolution: "@rolldown/binding-linux-x64-musl@npm:1.2.4"
+  conditions: os=linux & cpu=x64 & libc=musl
+  languageName: node
+  linkType: hard
+
+"@rolldown/binding-openharmony-arm64@npm:1.2.4":
+  version: 1.2.4
+  resolution: "@rolldown/binding-openharmony-arm64@npm:1.2.4"
+  conditions: os=openharmony & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@rolldown/binding-win32-arm64-msvc@npm:1.2.4":
+  version: 1.2.4
+  resolution: "@rolldown/binding-win32-arm64-msvc@npm:1.2.4"
+  conditions: os=win32 & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@rolldown/binding-win32-x64-msvc@npm:1.2.4":
+  version: 1.2.4
+  resolution: "@rolldown/binding-win32-x64-msvc@npm:1.2.4"
+  conditions: os=win32 & cpu=x64
+  languageName: node
+  linkType: hard
+
+"@rolldown/pluginutils@npm:^1.0.0":
+  version: 1.0.1
+  resolution: "@rolldown/pluginutils@npm:1.0.1"
+  checksum: 10c0/99d9b06d90196823e4d8c841f258db7a16e5dbba5824a2962b05d907b79f1ba929d56f22dd744fd530936e568c865ee56a719dc31e57e13bc0a8eb4764a8d8dd
+  languageName: node
+  linkType: hard
+
 "@rtsao/scc@npm:^1.1.0":
   version: 1.1.0
   resolution: "@rtsao/scc@npm:1.1.0"
@@ -814,6 +926,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@standard-schema/spec@npm:^1.1.0":
+  version: 1.1.0
+  resolution: "@standard-schema/spec@npm:1.1.0"
+  checksum: 10c0/d90f55acde4b2deb983529c87e8025fa693de1a5e8b49ecc6eb84d1fd96328add0e03d7d551442156c7432fd78165b2c26ff561b970a9a881f046abb78d6a526
+  languageName: node
+  linkType: hard
+
 "@swc/helpers@npm:0.5.15":
   version: 0.5.15
   resolution: "@swc/helpers@npm:0.5.15"
@@ -843,6 +962,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/chai@npm:^5.2.2":
+  version: 5.2.3
+  resolution: "@types/chai@npm:5.2.3"
+  dependencies:
+    "@types/deep-eql": "npm:*"
+    assertion-error: "npm:^2.0.1"
+  checksum: 10c0/e0ef1de3b6f8045a5e473e867c8565788c444271409d155588504840ad1a53611011f85072188c2833941189400228c1745d78323dac13fcede9c2b28bacfb2f
+  languageName: node
+  linkType: hard
+
 "@types/debug@npm:^4.0.0":
   version: 4.1.12
   resolution: "@types/debug@npm:4.1.12"
@@ -852,6 +981,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/deep-eql@npm:*":
+  version: 4.0.2
+  resolution: "@types/deep-eql@npm:4.0.2"
+  checksum: 10c0/bf3f811843117900d7084b9d0c852da9a044d12eb40e6de73b552598a6843c21291a8a381b0532644574beecd5e3491c5ff3a0365ab86b15d59862c025384844
+  languageName: node
+  linkType: hard
+
 "@types/estree-jsx@npm:^1.0.0":
   version: 1.0.5
   resolution: "@types/estree-jsx@npm:1.0.5"
@@ -943,7 +1079,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/trusted-types@npm:^2.0.2":
+"@types/trusted-types@npm:^2.0.2, @types/trusted-types@npm:^2.0.7":
   version: 2.0.7
   resolution: "@types/trusted-types@npm:2.0.7"
   checksum: 10c0/4c4855f10de7c6c135e0d32ce462419d8abbbc33713b31d294596c0cc34ae1fa6112a2f9da729c8f7a20707782b0d69da3b1f8df6645b0366d08825ca1522e0c
@@ -1241,6 +1377,88 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@vitest/expect@npm:4.1.10":
+  version: 4.1.10
+  resolution: "@vitest/expect@npm:4.1.10"
+  dependencies:
+    "@standard-schema/spec": "npm:^1.1.0"
+    "@types/chai": "npm:^5.2.2"
+    "@vitest/spy": "npm:4.1.10"
+    "@vitest/utils": "npm:4.1.10"
+    chai: "npm:^6.2.2"
+    tinyrainbow: "npm:^3.1.0"
+  checksum: 10c0/a817ad0d9bd6a039776a7228d54fb8319c17e4af15917407f5566ac61781a8511f591d302519d6999217399915bc3c0290028189fc73f5c38f80cb01b6f19c8d
+  languageName: node
+  linkType: hard
+
+"@vitest/mocker@npm:4.1.10":
+  version: 4.1.10
+  resolution: "@vitest/mocker@npm:4.1.10"
+  dependencies:
+    "@vitest/spy": "npm:4.1.10"
+    estree-walker: "npm:^3.0.3"
+    magic-string: "npm:^0.30.21"
+  peerDependencies:
+    msw: ^2.4.9
+    vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+  peerDependenciesMeta:
+    msw:
+      optional: true
+    vite:
+      optional: true
+  checksum: 10c0/4aa70b0df58681652e2e28093437fb2e8f4d02a6d03f5619abc266ac1c5ae5f43326148061d13ae6e071e0f6cfcf7634659af63644de8ce098a7c98949a3d1ad
+  languageName: node
+  linkType: hard
+
+"@vitest/pretty-format@npm:4.1.10":
+  version: 4.1.10
+  resolution: "@vitest/pretty-format@npm:4.1.10"
+  dependencies:
+    tinyrainbow: "npm:^3.1.0"
+  checksum: 10c0/1a5daba730ffe23f2000bff484b4b2842f3b178d93663cb487b215516b8d3b62caa3e2bb2a3c63307b61a9fe58fb9bfff38559bc0c5e49d8aa403d6803a1d918
+  languageName: node
+  linkType: hard
+
+"@vitest/runner@npm:4.1.10":
+  version: 4.1.10
+  resolution: "@vitest/runner@npm:4.1.10"
+  dependencies:
+    "@vitest/utils": "npm:4.1.10"
+    pathe: "npm:^2.0.3"
+  checksum: 10c0/554b72639de9694271b99be8ae273fe12ec793093ec91cce143816cd1187d40b7138a4d9d4de4f456cfca9567de986825bff97e107c05b9eb4abc130e854286d
+  languageName: node
+  linkType: hard
+
+"@vitest/snapshot@npm:4.1.10":
+  version: 4.1.10
+  resolution: "@vitest/snapshot@npm:4.1.10"
+  dependencies:
+    "@vitest/pretty-format": "npm:4.1.10"
+    "@vitest/utils": "npm:4.1.10"
+    magic-string: "npm:^0.30.21"
+    pathe: "npm:^2.0.3"
+  checksum: 10c0/e71398725f51af5fd0c07bb4b957d0f987daf9b4c564ac24cb2a4d1afde1a6939f535ac17761a32dcc41b0a1e6d4088af66dc44df89fdebebb92aabed1a92b5f
+  languageName: node
+  linkType: hard
+
+"@vitest/spy@npm:4.1.10":
+  version: 4.1.10
+  resolution: "@vitest/spy@npm:4.1.10"
+  checksum: 10c0/e5c08012560af6727fd66741c5cda25560d7c5442103d0c83e4276a9b0dd90b9da6cdf823a461195229a16c6ff87768ce788a68d0fa29dea73ee285618668178
+  languageName: node
+  linkType: hard
+
+"@vitest/utils@npm:4.1.10":
+  version: 4.1.10
+  resolution: "@vitest/utils@npm:4.1.10"
+  dependencies:
+    "@vitest/pretty-format": "npm:4.1.10"
+    convert-source-map: "npm:^2.0.0"
+    tinyrainbow: "npm:^3.1.0"
+  checksum: 10c0/05b0ecec6997ec22fc08377e57dbd8fa37992e05961f3a7a916d98b1ab56d15c2a87dbd83d392b628242bdc156b1705e7fa60a3bf0c54bdb51158c153e05fc5d
+  languageName: node
+  linkType: hard
+
 "abbrev@npm:^4.0.0":
   version: 4.0.0
   resolution: "abbrev@npm:4.0.0"
@@ -1448,6 +1666,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"assertion-error@npm:^2.0.1":
+  version: 2.0.1
+  resolution: "assertion-error@npm:2.0.1"
+  checksum: 10c0/bbbcb117ac6480138f8c93cf7f535614282dea9dc828f540cdece85e3c665e8f78958b96afac52f29ff883c72638e6a87d469ecc9fe5bc902df03ed24a55dba8
+  languageName: node
+  linkType: hard
+
 "ast-types-flow@npm:^0.0.8":
   version: 0.0.8
   resolution: "ast-types-flow@npm:0.0.8"
@@ -1601,6 +1826,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"chai@npm:^6.2.2":
+  version: 6.2.2
+  resolution: "chai@npm:6.2.2"
+  checksum: 10c0/e6c69e5f0c11dffe6ea13d0290936ebb68fcc1ad688b8e952e131df6a6d5797d5e860bc55cef1aca2e950c3e1f96daf79e9d5a70fb7dbaab4e46355e2635ed53
+  languageName: node
+  linkType: hard
+
 "chalk@npm:^4.0.0":
   version: 4.1.2
   resolution: "chalk@npm:4.1.2"
@@ -1725,6 +1957,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"convert-source-map@npm:^2.0.0":
+  version: 2.0.0
+  resolution: "convert-source-map@npm:2.0.0"
+  checksum: 10c0/8f2f7a27a1a011cc6cc88cc4da2d7d0cfa5ee0369508baae3d98c260bb3ac520691464e5bbe4ae7cdf09860c1d69ecc6f70c63c6e7c7f7e3f18ec08484dc7d9b
+  languageName: node
+  linkType: hard
+
 "cross-spawn@npm:^7.0.6":
   version: 7.0.6
   resolution: "cross-spawn@npm:7.0.6"
@@ -1858,7 +2097,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"detect-libc@npm:^2.1.2":
+"detect-libc@npm:^2.0.3, detect-libc@npm:^2.1.2":
   version: 2.1.2
   resolution: "detect-libc@npm:2.1.2"
   checksum: 10c0/acc675c29a5649fa1fb6e255f993b8ee829e510b6b56b0910666949c80c364738833417d0edb5f90e4e46be17228b0f2b66a010513984e18b15deeeac49369c4
@@ -1904,6 +2143,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"dompurify@npm:^3.4.13":
+  version: 3.4.13
+  resolution: "dompurify@npm:3.4.13"
+  dependencies:
+    "@types/trusted-types": "npm:^2.0.7"
+  dependenciesMeta:
+    "@types/trusted-types":
+      optional: true
+  checksum: 10c0/9c2a1a71e1a1d8b77953db7a39ffc935ef4ed4f10fe40770232128c2cbfd4c3dc677d3d7bae51eb24cc52d9ff3548612dc540ecb4343e89b26e809d2be2e0cfe
+  languageName: node
+  linkType: hard
+
 "dunder-proto@npm:^1.0.0, dunder-proto@npm:^1.0.1":
   version: 1.0.1
   resolution: "dunder-proto@npm:1.0.1"
@@ -2036,6 +2287,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"es-module-lexer@npm:^2.0.0":
+  version: 2.3.1
+  resolution: "es-module-lexer@npm:2.3.1"
+  checksum: 10c0/ada8b222772b5b8ea92eb6054c383233207418621855a07b480fdd36979b658a41414be09e793fcdd8a67a182741475f47830a01ff2ebd4353d7f6965c7c45f9
+  languageName: node
+  linkType: hard
+
 "es-object-atoms@npm:^1.0.0, es-object-atoms@npm:^1.1.1":
   version: 1.1.1
   resolution: "es-object-atoms@npm:1.1.1"
@@ -2475,6 +2733,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"estree-walker@npm:^3.0.3":
+  version: 3.0.3
+  resolution: "estree-walker@npm:3.0.3"
+  dependencies:
+    "@types/estree": "npm:^1.0.0"
+  checksum: 10c0/c12e3c2b2642d2bcae7d5aa495c60fa2f299160946535763969a1c83fc74518ffa9c2cd3a8b69ac56aea547df6a8aac25f729a342992ef0bbac5f1c73e78995d
+  languageName: node
+  linkType: hard
+
 "esutils@npm:^2.0.2":
   version: 2.0.3
   resolution: "esutils@npm:2.0.3"
@@ -2482,6 +2749,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"expect-type@npm:^1.3.0":
+  version: 1.4.0
+  resolution: "expect-type@npm:1.4.0"
+  checksum: 10c0/d40d76b8570695d36587beb3cc28494da2ca3ec8f04e67f5622ed2d372d850e401a9adef19c6835e1a8173903f157c79540b34c7b3fbd7cd8ce726cc903c57b7
+  languageName: node
+  linkType: hard
+
 "exponential-backoff@npm:^3.1.1":
   version: 3.1.3
   resolution: "exponential-backoff@npm:3.1.3"
@@ -3594,6 +3868,126 @@ __metadata:
   languageName: node
   linkType: hard
 
+"lightningcss-android-arm64@npm:1.33.0":
+  version: 1.33.0
+  resolution: "lightningcss-android-arm64@npm:1.33.0"
+  conditions: os=android & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"lightningcss-darwin-arm64@npm:1.33.0":
+  version: 1.33.0
+  resolution: "lightningcss-darwin-arm64@npm:1.33.0"
+  conditions: os=darwin & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"lightningcss-darwin-x64@npm:1.33.0":
+  version: 1.33.0
+  resolution: "lightningcss-darwin-x64@npm:1.33.0"
+  conditions: os=darwin & cpu=x64
+  languageName: node
+  linkType: hard
+
+"lightningcss-freebsd-x64@npm:1.33.0":
+  version: 1.33.0
+  resolution: "lightningcss-freebsd-x64@npm:1.33.0"
+  conditions: os=freebsd & cpu=x64
+  languageName: node
+  linkType: hard
+
+"lightningcss-linux-arm-gnueabihf@npm:1.33.0":
+  version: 1.33.0
+  resolution: "lightningcss-linux-arm-gnueabihf@npm:1.33.0"
+  conditions: os=linux & cpu=arm
+  languageName: node
+  linkType: hard
+
+"lightningcss-linux-arm64-gnu@npm:1.33.0":
+  version: 1.33.0
+  resolution: "lightningcss-linux-arm64-gnu@npm:1.33.0"
+  conditions: os=linux & cpu=arm64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"lightningcss-linux-arm64-musl@npm:1.33.0":
+  version: 1.33.0
+  resolution: "lightningcss-linux-arm64-musl@npm:1.33.0"
+  conditions: os=linux & cpu=arm64 & libc=musl
+  languageName: node
+  linkType: hard
+
+"lightningcss-linux-x64-gnu@npm:1.33.0":
+  version: 1.33.0
+  resolution: "lightningcss-linux-x64-gnu@npm:1.33.0"
+  conditions: os=linux & cpu=x64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"lightningcss-linux-x64-musl@npm:1.33.0":
+  version: 1.33.0
+  resolution: "lightningcss-linux-x64-musl@npm:1.33.0"
+  conditions: os=linux & cpu=x64 & libc=musl
+  languageName: node
+  linkType: hard
+
+"lightningcss-win32-arm64-msvc@npm:1.33.0":
+  version: 1.33.0
+  resolution: "lightningcss-win32-arm64-msvc@npm:1.33.0"
+  conditions: os=win32 & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"lightningcss-win32-x64-msvc@npm:1.33.0":
+  version: 1.33.0
+  resolution: "lightningcss-win32-x64-msvc@npm:1.33.0"
+  conditions: os=win32 & cpu=x64
+  languageName: node
+  linkType: hard
+
+"lightningcss@npm:^1.33.0":
+  version: 1.33.0
+  resolution: "lightningcss@npm:1.33.0"
+  dependencies:
+    detect-libc: "npm:^2.0.3"
+    lightningcss-android-arm64: "npm:1.33.0"
+    lightningcss-darwin-arm64: "npm:1.33.0"
+    lightningcss-darwin-x64: "npm:1.33.0"
+    lightningcss-freebsd-x64: "npm:1.33.0"
+    lightningcss-linux-arm-gnueabihf: "npm:1.33.0"
+    lightningcss-linux-arm64-gnu: "npm:1.33.0"
+    lightningcss-linux-arm64-musl: "npm:1.33.0"
+    lightningcss-linux-x64-gnu: "npm:1.33.0"
+    lightningcss-linux-x64-musl: "npm:1.33.0"
+    lightningcss-win32-arm64-msvc: "npm:1.33.0"
+    lightningcss-win32-x64-msvc: "npm:1.33.0"
+  dependenciesMeta:
+    lightningcss-android-arm64:
+      optional: true
+    lightningcss-darwin-arm64:
+      optional: true
+    lightningcss-darwin-x64:
+      optional: true
+    lightningcss-freebsd-x64:
+      optional: true
+    lightningcss-linux-arm-gnueabihf:
+      optional: true
+    lightningcss-linux-arm64-gnu:
+      optional: true
+    lightningcss-linux-arm64-musl:
+      optional: true
+    lightningcss-linux-x64-gnu:
+      optional: true
+    lightningcss-linux-x64-musl:
+      optional: true
+    lightningcss-win32-arm64-msvc:
+      optional: true
+    lightningcss-win32-x64-msvc:
+      optional: true
+  checksum: 10c0/ce1f8279fbae636dbf37fa6e7385d5f98ed881d72af3362f24afbd4685e19c1fcdfecf17e5dd77f2ebee3d0c23ade276230d85842d07292229a2cffba8ff20a3
+  languageName: node
+  linkType: hard
+
 "lilconfig@npm:^3.1.1, lilconfig@npm:^3.1.3":
   version: 3.1.3
   resolution: "lilconfig@npm:3.1.3"
@@ -3693,6 +4087,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"magic-string@npm:^0.30.21":
+  version: 0.30.21
+  resolution: "magic-string@npm:0.30.21"
+  dependencies:
+    "@jridgewell/sourcemap-codec": "npm:^1.5.5"
+  checksum: 10c0/299378e38f9a270069fc62358522ddfb44e94244baa0d6a8980ab2a9b2490a1d03b236b447eee309e17eb3bddfa482c61259d47960eb018a904f0ded52780c4a
+  languageName: node
+  linkType: hard
+
 "markdown-table@npm:^3.0.0":
   version: 3.0.4
   resolution: "markdown-table@npm:3.0.4"
@@ -4850,6 +5253,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"obug@npm:^2.1.1":
+  version: 2.1.4
+  resolution: "obug@npm:2.1.4"
+  checksum: 10c0/34a0ee97cd88573cfd97d384c2a79f07118ae5680d7e45d1de6e99c74eddefe145e8ca27a2db02195a1ee5fded5aa22b924869c842728c201b9f109a27d0ef19
+  languageName: node
+  linkType: hard
+
 "openprinting.github.io@workspace:.":
   version: 0.0.0-use.local
   resolution: "openprinting.github.io@workspace:."
@@ -4863,6 +5273,7 @@ __metadata:
     "@types/react-dom": "npm:^19"
     class-variance-authority: "npm:^0.7.1"
     clsx: "npm:^2.1.1"
+    dompurify: "npm:^3.4.13"
     eslint: "npm:^9"
     eslint-config-next: "npm:15.1.6"
     fast-xml-parser: "npm:^5.7.0"
@@ -4893,6 +5304,7 @@ __metadata:
     typescript: "npm:^5"
     unified: "npm:^10.1.0"
     unist-util-visit: "npm:^4.1.0"
+    vitest: "npm:^4.1.10"
   languageName: unknown
   linkType: soft
 
@@ -5000,6 +5412,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"pathe@npm:^2.0.3":
+  version: 2.0.3
+  resolution: "pathe@npm:2.0.3"
+  checksum: 10c0/c118dc5a8b5c4166011b2b70608762e260085180bb9e33e80a50dcdb1e78c010b1624f4280c492c92b05fc276715a4c357d1f9edc570f8f1b3d90b6839ebaca1
+  languageName: node
+  linkType: hard
+
 "picocolors@npm:^1.0.0, picocolors@npm:^1.1.1":
   version: 1.1.1
   resolution: "picocolors@npm:1.1.1"
@@ -5021,6 +5440,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"picomatch@npm:^4.0.5":
+  version: 4.0.5
+  resolution: "picomatch@npm:4.0.5"
+  checksum: 10c0/947bc6b6e1ff1e6c5aaf95b107a0839d12802f4f7b867663f67d47accba939ca1cb582cf99dfc30438efa1c4648ac5990967e783e8929c36b03e8440704ef1bd
+  languageName: node
+  linkType: hard
+
 "pify@npm:^2.3.0":
   version: 2.3.0
   resolution: "pify@npm:2.3.0"
@@ -5138,7 +5564,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"postcss@npm:^8":
+"postcss@npm:^8, postcss@npm:^8.5.25":
   version: 8.5.26
   resolution: "postcss@npm:8.5.26"
   dependencies:
@@ -5499,6 +5925,61 @@ __metadata:
   languageName: node
   linkType: hard
 
+"rolldown@npm:~1.2.1":
+  version: 1.2.4
+  resolution: "rolldown@npm:1.2.4"
+  dependencies:
+    "@oxc-project/types": "npm:=0.144.0"
+    "@rolldown/binding-android-arm64": "npm:1.2.4"
+    "@rolldown/binding-darwin-arm64": "npm:1.2.4"
+    "@rolldown/binding-darwin-x64": "npm:1.2.4"
+    "@rolldown/binding-freebsd-x64": "npm:1.2.4"
+    "@rolldown/binding-linux-arm-gnueabihf": "npm:1.2.4"
+    "@rolldown/binding-linux-arm64-gnu": "npm:1.2.4"
+    "@rolldown/binding-linux-arm64-musl": "npm:1.2.4"
+    "@rolldown/binding-linux-ppc64-gnu": "npm:1.2.4"
+    "@rolldown/binding-linux-s390x-gnu": "npm:1.2.4"
+    "@rolldown/binding-linux-x64-gnu": "npm:1.2.4"
+    "@rolldown/binding-linux-x64-musl": "npm:1.2.4"
+    "@rolldown/binding-openharmony-arm64": "npm:1.2.4"
+    "@rolldown/binding-win32-arm64-msvc": "npm:1.2.4"
+    "@rolldown/binding-win32-x64-msvc": "npm:1.2.4"
+    "@rolldown/pluginutils": "npm:^1.0.0"
+  dependenciesMeta:
+    "@rolldown/binding-android-arm64":
+      optional: true
+    "@rolldown/binding-darwin-arm64":
+      optional: true
+    "@rolldown/binding-darwin-x64":
+      optional: true
+    "@rolldown/binding-freebsd-x64":
+      optional: true
+    "@rolldown/binding-linux-arm-gnueabihf":
+      optional: true
+    "@rolldown/binding-linux-arm64-gnu":
+      optional: true
+    "@rolldown/binding-linux-arm64-musl":
+      optional: true
+    "@rolldown/binding-linux-ppc64-gnu":
+      optional: true
+    "@rolldown/binding-linux-s390x-gnu":
+      optional: true
+    "@rolldown/binding-linux-x64-gnu":
+      optional: true
+    "@rolldown/binding-linux-x64-musl":
+      optional: true
+    "@rolldown/binding-openharmony-arm64":
+      optional: true
+    "@rolldown/binding-win32-arm64-msvc":
+      optional: true
+    "@rolldown/binding-win32-x64-msvc":
+      optional: true
+  bin:
+    rolldown: ./bin/cli.mjs
+  checksum: 10c0/438c2222db940fab6e2db1f1cf84ab27c83310959e056fa389d7e2208bcbf58929f970f4dca5bd9c255f319bf657ef1a4a7ea6725213491d28764d867e5407a4
+  languageName: node
+  linkType: hard
+
 "run-parallel@npm:^1.1.9":
   version: 1.2.0
   resolution: "run-parallel@npm:1.2.0"
@@ -5780,6 +6261,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"siginfo@npm:^2.0.0":
+  version: 2.0.0
+  resolution: "siginfo@npm:2.0.0"
+  checksum: 10c0/3def8f8e516fbb34cb6ae415b07ccc5d9c018d85b4b8611e3dc6f8be6d1899f693a4382913c9ed51a06babb5201639d76453ab297d1c54a456544acf5c892e34
+  languageName: node
+  linkType: hard
+
 "source-map-js@npm:^1.0.2, source-map-js@npm:^1.2.1":
   version: 1.2.1
   resolution: "source-map-js@npm:1.2.1"
@@ -5808,6 +6296,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"stackback@npm:0.0.2":
+  version: 0.0.2
+  resolution: "stackback@npm:0.0.2"
+  checksum: 10c0/89a1416668f950236dd5ac9f9a6b2588e1b9b62b1b6ad8dff1bfc5d1a15dbf0aafc9b52d2226d00c28dffff212da464eaeebfc6b7578b9d180cef3e3782c5983
+  languageName: node
+  linkType: hard
+
+"std-env@npm:^4.0.0-rc.1":
+  version: 4.2.0
+  resolution: "std-env@npm:4.2.0"
+  checksum: 10c0/40ac525ce7b7c556abc332a7376f14356eeb1a7f17f6ff9a003eb9f52326ff1f3745d3e1b43452675b1ec6fcc319f1b1d6f3b0d386cf3f91058479ad883cff69
+  languageName: node
+  linkType: hard
+
 "stop-iteration-iterator@npm:^1.1.0":
   version: 1.1.0
   resolution: "stop-iteration-iterator@npm:1.1.0"
@@ -6086,6 +6588,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"tinybench@npm:^2.9.0":
+  version: 2.9.0
+  resolution: "tinybench@npm:2.9.0"
+  checksum: 10c0/c3500b0f60d2eb8db65250afe750b66d51623057ee88720b7f064894a6cb7eb93360ca824a60a31ab16dab30c7b1f06efe0795b352e37914a9d4bad86386a20c
+  languageName: node
+  linkType: hard
+
+"tinyexec@npm:^1.0.2":
+  version: 1.3.0
+  resolution: "tinyexec@npm:1.3.0"
+  checksum: 10c0/e9b89f97489d2aab2cef408da279e6b32547e738d1275032ccb8fd0028a006d93eb70fc51c6cffd9fc2f5aca6c2a273d8b6f73b52d46ee5116da6b94969ef958
+  languageName: node
+  linkType: hard
+
 "tinyglobby@npm:^0.2.11, tinyglobby@npm:^0.2.13, tinyglobby@npm:^0.2.15":
   version: 0.2.15
   resolution: "tinyglobby@npm:0.2.15"
@@ -6096,7 +6612,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"tinyglobby@npm:^0.2.12":
+"tinyglobby@npm:^0.2.12, tinyglobby@npm:^0.2.17":
   version: 0.2.17
   resolution: "tinyglobby@npm:0.2.17"
   dependencies:
@@ -6106,6 +6622,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"tinyrainbow@npm:^3.1.0":
+  version: 3.1.1
+  resolution: "tinyrainbow@npm:3.1.1"
+  checksum: 10c0/f9d2743832c6191f753408f36224fe817620b8abcef572b2e570204c673a901d753ff84ca8e7b88f9c79e934295b3ffc6fcbc56a06f126e24e1ec6186dcad40d
+  languageName: node
+  linkType: hard
+
 "to-regex-range@npm:^5.0.1":
   version: 5.0.1
   resolution: "to-regex-range@npm:5.0.1"
@@ -6254,11 +6777,11 @@ __metadata:
 
 "typescript@patch:typescript@npm%3A^5#optional!builtin<compat/typescript>":
   version: 5.9.3
-  resolution: "typescript@patch:typescript@npm%3A5.9.3#optional!builtin<compat/typescript>::version=5.9.3&hash=d69c25"
+  resolution: "typescript@patch:typescript@npm%3A5.9.3#optional!builtin<compat/typescript>::version=5.9.3&hash=5786d5"
   bin:
     tsc: bin/tsc
     tsserver: bin/tsserver
-  checksum: 10c0/6f7e53bf0d9702350deeb6f35e08b69cbc8b958c33e0ec77bdc0ad6a6c8e280f3959dcbfde6f5b0848bece57810696489deaaa53d75de3578ff255d168c1efbd
+  checksum: 10c0/ad09fdf7a756814dce65bc60c1657b40d44451346858eea230e10f2e95a289d9183b6e32e5c11e95acc0ccc214b4f36289dcad4bf1886b0adb84d711d336a430
   languageName: node
   linkType: hard
 
@@ -6564,6 +7087,131 @@ __metadata:
   languageName: node
   linkType: hard
 
+"vite@npm:^6.0.0 || ^7.0.0 || ^8.0.0":
+  version: 8.2.1
+  resolution: "vite@npm:8.2.1"
+  dependencies:
+    fsevents: "npm:~2.3.3"
+    lightningcss: "npm:^1.33.0"
+    picomatch: "npm:^4.0.5"
+    postcss: "npm:^8.5.25"
+    rolldown: "npm:~1.2.1"
+    tinyglobby: "npm:^0.2.17"
+  peerDependencies:
+    "@types/node": ^20.19.0 || >=22.12.0
+    "@vitejs/devtools": ^0.4.0
+    esbuild: ^0.27.0 || ^0.28.0
+    jiti: ">=1.21.0"
+    less: ^4.0.0
+    sass: ^1.70.0
+    sass-embedded: ^1.70.0
+    stylus: ">=0.54.8"
+    sugarss: ^5.0.0
+    terser: ^5.16.0
+    tsx: ^4.8.1
+    yaml: ^2.4.2
+  dependenciesMeta:
+    fsevents:
+      optional: true
+  peerDependenciesMeta:
+    "@types/node":
+      optional: true
+    "@vitejs/devtools":
+      optional: true
+    esbuild:
+      optional: true
+    jiti:
+      optional: true
+    less:
+      optional: true
+    sass:
+      optional: true
+    sass-embedded:
+      optional: true
+    stylus:
+      optional: true
+    sugarss:
+      optional: true
+    terser:
+      optional: true
+    tsx:
+      optional: true
+    yaml:
+      optional: true
+  bin:
+    vite: bin/vite.js
+  checksum: 10c0/e958dd07502deeb552f04dba59418ff1eb63183add416fd7a3e3badabf5d36edc6834b94c916f9f9233f976bb1671e3e9989d90e869059af07b0d43f7fc078c2
+  languageName: node
+  linkType: hard
+
+"vitest@npm:^4.1.10":
+  version: 4.1.10
+  resolution: "vitest@npm:4.1.10"
+  dependencies:
+    "@vitest/expect": "npm:4.1.10"
+    "@vitest/mocker": "npm:4.1.10"
+    "@vitest/pretty-format": "npm:4.1.10"
+    "@vitest/runner": "npm:4.1.10"
+    "@vitest/snapshot": "npm:4.1.10"
+    "@vitest/spy": "npm:4.1.10"
+    "@vitest/utils": "npm:4.1.10"
+    es-module-lexer: "npm:^2.0.0"
+    expect-type: "npm:^1.3.0"
+    magic-string: "npm:^0.30.21"
+    obug: "npm:^2.1.1"
+    pathe: "npm:^2.0.3"
+    picomatch: "npm:^4.0.3"
+    std-env: "npm:^4.0.0-rc.1"
+    tinybench: "npm:^2.9.0"
+    tinyexec: "npm:^1.0.2"
+    tinyglobby: "npm:^0.2.15"
+    tinyrainbow: "npm:^3.1.0"
+    vite: "npm:^6.0.0 || ^7.0.0 || ^8.0.0"
+    why-is-node-running: "npm:^2.3.0"
+  peerDependencies:
+    "@edge-runtime/vm": "*"
+    "@opentelemetry/api": ^1.9.0
+    "@types/node": ^20.0.0 || ^22.0.0 || >=24.0.0
+    "@vitest/browser-playwright": 4.1.10
+    "@vitest/browser-preview": 4.1.10
+    "@vitest/browser-webdriverio": 4.1.10
+    "@vitest/coverage-istanbul": 4.1.10
+    "@vitest/coverage-v8": 4.1.10
+    "@vitest/ui": 4.1.10
+    happy-dom: "*"
+    jsdom: "*"
+    vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+  peerDependenciesMeta:
+    "@edge-runtime/vm":
+      optional: true
+    "@opentelemetry/api":
+      optional: true
+    "@types/node":
+      optional: true
+    "@vitest/browser-playwright":
+      optional: true
+    "@vitest/browser-preview":
+      optional: true
+    "@vitest/browser-webdriverio":
+      optional: true
+    "@vitest/coverage-istanbul":
+      optional: true
+    "@vitest/coverage-v8":
+      optional: true
+    "@vitest/ui":
+      optional: true
+    happy-dom:
+      optional: true
+    jsdom:
+      optional: true
+    vite:
+      optional: false
+  bin:
+    vitest: ./vitest.mjs
+  checksum: 10c0/ff07294a57f9c62f3b503f7cf88a52ee0753ed26389a49cda430387a3898f39d80af47180b0af19e27acab5bd11ae95706bd4b44ce8befc97d3ae49af6ca4fc1
+  languageName: node
+  linkType: hard
+
 "web-namespaces@npm:^2.0.0":
   version: 2.0.1
   resolution: "web-namespaces@npm:2.0.1"
@@ -6654,6 +7302,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"why-is-node-running@npm:^2.3.0":
+  version: 2.3.0
+  resolution: "why-is-node-running@npm:2.3.0"
+  dependencies:
+    siginfo: "npm:^2.0.0"
+    stackback: "npm:0.0.2"
+  bin:
+    why-is-node-running: cli.js
+  checksum: 10c0/1cde0b01b827d2cf4cb11db962f3958b9175d5d9e7ac7361d1a7b0e2dc6069a263e69118bd974c4f6d0a890ef4eedfe34cf3d5167ec14203dbc9a18620537054
+  languageName: node
+  linkType: hard
+
 "word-wrap@npm:^1.2.5":
   version: 1.2.5
   resolution: "word-wrap@npm:1.2.5"