From a66e08fe16c2ce7f04eae36dc1b2177fba0ddec9 Mon Sep 17 00:00:00 2001
From: Alaeddin <15094821+BSalaeddin@users.noreply.github.com>
Date: Sat, 12 Sep 2026 08:38:38 +0100
Subject: [PATCH] feat(seo): A-Z store directory and neighbour links so no
 store page is orphaned

---
 apps/caramel-app/e2e/seo-a11y.spec.ts         |  88 +++++
 .../app/(marketing)/coupons/[store]/page.tsx  |   5 +
 .../src/app/(marketing)/coupons/page.tsx      |   4 +
 .../coupons/stores/[letter]/page.tsx          | 222 +++++++++++++
 .../app/(marketing)/coupons/stores/page.tsx   | 123 +++++++
 .../app/(marketing)/supported-stores/page.tsx |   7 +
 apps/caramel-app/src/app/llms.txt/route.ts    |   1 +
 apps/caramel-app/src/app/sitemap.ts           |  38 ++-
 .../components/coupons/store-letter-strip.tsx |  51 +++
 .../components/coupons/store-neighbours.tsx   |  83 +++++
 .../caramel-app/src/layouts/Footer/Footer.tsx |   1 +
 apps/caramel-app/src/lib/couponsRepo.ts       |  68 ++++
 apps/caramel-app/src/lib/seo/sitemapStores.ts |   9 +
 .../caramel-app/src/lib/seo/storeDirectory.ts | 204 ++++++++++++
 .../src/lib/seo/storeDirectoryCache.ts        |  79 +++++
 .../tests/integration/coupons-read.itest.ts   |  36 +++
 .../unit/coupons-store-directory.test.ts      | 304 ++++++++++++++++++
 .../tests/unit/couponsRepo.test.ts            |  64 ++++
 apps/caramel-app/tests/unit/sitemap.test.ts   |  86 ++++-
 .../tests/unit/storeDirectory.test.ts         | 272 ++++++++++++++++
 .../tests/unit/storeDirectoryCache.test.ts    |  86 +++++
 21 files changed, 1818 insertions(+), 13 deletions(-)
 create mode 100644 apps/caramel-app/src/app/(marketing)/coupons/stores/[letter]/page.tsx
 create mode 100644 apps/caramel-app/src/app/(marketing)/coupons/stores/page.tsx
 create mode 100644 apps/caramel-app/src/components/coupons/store-letter-strip.tsx
 create mode 100644 apps/caramel-app/src/components/coupons/store-neighbours.tsx
 create mode 100644 apps/caramel-app/src/lib/seo/storeDirectory.ts
 create mode 100644 apps/caramel-app/src/lib/seo/storeDirectoryCache.ts
 create mode 100644 apps/caramel-app/tests/unit/coupons-store-directory.test.ts
 create mode 100644 apps/caramel-app/tests/unit/storeDirectory.test.ts
 create mode 100644 apps/caramel-app/tests/unit/storeDirectoryCache.test.ts

diff --git a/apps/caramel-app/e2e/seo-a11y.spec.ts b/apps/caramel-app/e2e/seo-a11y.spec.ts
index 8470f171..dc5bc395 100644
--- a/apps/caramel-app/e2e/seo-a11y.spec.ts
+++ b/apps/caramel-app/e2e/seo-a11y.spec.ts
@@ -58,6 +58,11 @@ test.describe('SEO & Accessibility Basics', () => {
 // seeded app (e2e-pr/local) and the deployed dev site (e2e-push). Only the
 // codecademy.com assertion depends on a specific catalog row, so only it is
 // DATABASE_URL-gated; everything else holds on any non-empty catalog.
+// Distinct hrefs matching `re` (group 1) in raw HTML, in document order.
+function hrefsOf(html: string, re: RegExp): string[] {
+    return Array.from(new Set(Array.from(html.matchAll(re)).map(m => m[1]!)))
+}
+
 function extractJsonLd(html: string): Array<Record<string, unknown>> {
     const scriptRe =
         /<script type="application\/ld\+json"[^>]*>([\s\S]*?)<\/script>/g
@@ -183,6 +188,8 @@ test.describe('Coupon pages — crawler-visible SEO', () => {
             .map(loc => /\/coupons\/([^/?#]+)$/.exec(loc)?.[1])
             .filter((slug): slug is string => Boolean(slug))
             .map(slug => decodeURIComponent(slug))
+            // /coupons/stores is the A–Z directory index, not a store page.
+            .filter(slug => slug !== 'stores')
         // The catalog is never legitimately empty in either context.
         expect(storeSlugs.length).toBeGreaterThan(0)
 
@@ -203,6 +210,87 @@ test.describe('Coupon pages — crawler-visible SEO', () => {
         const origin = (baseURL ?? '').replace(/\/+$/, '')
         expect(await res.text()).toContain(`<loc>${origin}/support</loc>`)
     })
+
+    // A–Z store directory (2026-09-12): before it, 8 of ~4,262 store pages
+    // had any internal inbound link — the rest were sitemap-only orphans.
+    // These walk the crawl chain the way a crawler does, from the RAW HTML:
+    // directory index → a letter page → a store page → its neighbours. URLs
+    // are discovered from the served HTML, never assumed, so the tests hold
+    // against the 5-store hermetic seed and the real catalog alike.
+    const letterHrefRe = /href="(\/coupons\/stores\/(?:[a-z]|0-9))"/g
+    const storeHrefRe = /href="(\/coupons\/(?!stores(?:\/|"|$))[^"/?#]+)"/g
+
+    test('/coupons/stores is served with a self canonical, index+follow, and at least one letter link', async ({
+        page,
+    }) => {
+        const res = await page.request.get('/coupons/stores')
+        expect(res.status()).toBe(200)
+        const html = await res.text()
+
+        expect(html).toMatch(
+            /<link rel="canonical" href="[^"]*\/coupons\/stores"\/?>/,
+        )
+        expect(html).not.toMatch(/name="robots"[^>]*noindex/)
+        expect((html.match(/<h1/g) ?? []).length).toBe(1)
+        expect(hrefsOf(html, letterHrefRe).length).toBeGreaterThan(0)
+    })
+
+    test('a letter page found from the directory index is served with a self canonical and lists store links', async ({
+        page,
+    }) => {
+        const index = await page.request.get('/coupons/stores')
+        const letterPath = hrefsOf(await index.text(), letterHrefRe)[0]
+        expect(letterPath).toBeTruthy()
+
+        const res = await page.request.get(letterPath!)
+        expect(res.status()).toBe(200)
+        const html = await res.text()
+
+        expect(html).toMatch(
+            new RegExp(
+                `<link rel="canonical" href="[^"]*${letterPath!.replace(/[/-]/g, '\\$&')}"/?>`,
+            ),
+        )
+        expect(html).not.toMatch(/name="robots"[^>]*noindex/)
+        const storeHrefs = hrefsOf(html, storeHrefRe)
+        expect(storeHrefs.length).toBeGreaterThan(0)
+        // Every listed store is a canonical base (the same rule the sitemap
+        // obeys) and shows a real code count.
+        for (const href of storeHrefs) {
+            const slug = decodeURIComponent(href.slice('/coupons/'.length))
+            expect(resolveStoreDomain(slug), href).toBe(slug)
+        }
+        expect(html).toMatch(/ · \d[\d,]* codes?</)
+    })
+
+    test('a store page reached from a letter page carries a "More stores" section with at least one neighbour link', async ({
+        page,
+    }) => {
+        const index = await page.request.get('/coupons/stores')
+        const letterPath = hrefsOf(await index.text(), letterHrefRe)[0]!
+        const letter = await page.request.get(letterPath)
+        const storePath = hrefsOf(await letter.text(), storeHrefRe)[0]
+        expect(storePath).toBeTruthy()
+
+        const res = await page.request.get(storePath!)
+        expect(res.status()).toBe(200)
+        const html = await res.text()
+
+        expect(html).toContain('More stores')
+        // At least one OTHER store linked from this page (the neighbour chain),
+        // and the way back into the directory letter this store lives on.
+        const others = hrefsOf(html, storeHrefRe).filter(h => h !== storePath)
+        expect(others.length).toBeGreaterThan(0)
+        expect(hrefsOf(html, letterHrefRe)).toContain(letterPath)
+    })
+
+    test('a letter with no stores is a 404, not an empty page', async ({
+        page,
+    }) => {
+        // Not a directory letter at all — always 404 regardless of catalog.
+        const res = await page.request.get('/coupons/stores/zz')
+        expect(res.status()).toBe(404)
+    })
 })
 
 test.describe('Responsive - Mobile Viewport', () => {
diff --git a/apps/caramel-app/src/app/(marketing)/coupons/[store]/page.tsx b/apps/caramel-app/src/app/(marketing)/coupons/[store]/page.tsx
index ac720945..5057e4a2 100644
--- a/apps/caramel-app/src/app/(marketing)/coupons/[store]/page.tsx
+++ b/apps/caramel-app/src/app/(marketing)/coupons/[store]/page.tsx
@@ -1,6 +1,7 @@
 import CouponsSection from '@/components/coupons/coupons-section'
 import PopularStores from '@/components/coupons/popular-stores'
 import StoreFavoriteStar from '@/components/coupons/store-favorite-star'
+import StoreNeighbours from '@/components/coupons/store-neighbours'
 import { attachSignals } from '@/lib/couponSignals'
 import { listStoreCoupons } from '@/lib/couponsRepo'
 import { BASE_URL } from '@/lib/env.client'
@@ -259,6 +260,10 @@ export default async function StoreCouponsPage({
                 </p>
             </section>
             <PopularStores currentSite={base} />
+            {/* Alphabetical neighbours + this store's directory letter page:
+                the crawl chain that reaches every store page (PopularStores
+                links the same 4 stores site-wide; this links the nearest). */}
+            <StoreNeighbours base={base} />
             <script
                 type="application/ld+json"
                 suppressHydrationWarning
diff --git a/apps/caramel-app/src/app/(marketing)/coupons/page.tsx b/apps/caramel-app/src/app/(marketing)/coupons/page.tsx
index 53f1557d..c2e725af 100644
--- a/apps/caramel-app/src/app/(marketing)/coupons/page.tsx
+++ b/apps/caramel-app/src/app/(marketing)/coupons/page.tsx
@@ -1,5 +1,6 @@
 import CouponsSection from '@/components/coupons/coupons-section'
 import PopularStores from '@/components/coupons/popular-stores'
+import StoreLetterStrip from '@/components/coupons/store-letter-strip'
 import { attachSignals } from '@/lib/couponSignals'
 import { listCoupons } from '@/lib/couponsRepo'
 import { BASE_URL } from '@/lib/env.client'
@@ -86,6 +87,9 @@ export default async function CouponsPage() {
                 heroSubtitle="Browse verified coupon codes, promo codes, and offers for your favorite stores."
             />
             <PopularStores />
+            {/* Server-rendered letter strip into the A–Z directory — the hub's
+                crawl path to every store page, not just the 4 popular ones. */}
+            <StoreLetterStrip />
             <script
                 type="application/ld+json"
                 suppressHydrationWarning
diff --git a/apps/caramel-app/src/app/(marketing)/coupons/stores/[letter]/page.tsx b/apps/caramel-app/src/app/(marketing)/coupons/stores/[letter]/page.tsx
new file mode 100644
index 00000000..eb6a2098
--- /dev/null
+++ b/apps/caramel-app/src/app/(marketing)/coupons/stores/[letter]/page.tsx
@@ -0,0 +1,222 @@
+import StoreLetterStrip from '@/components/coupons/store-letter-strip'
+import { BASE_URL } from '@/lib/env.client'
+import { jsonLdString } from '@/lib/jsonLd'
+import type { DirectoryLetter, DirectoryPage } from '@/lib/seo/storeDirectory'
+import {
+    bucketStoresByLetter,
+    directoryLetterLabel,
+    directoryPath,
+    paginateDirectoryBucket,
+    parseDirectoryLetter,
+    parseDirectoryPage,
+} from '@/lib/seo/storeDirectory'
+import { getStoreDirectoryEntries } from '@/lib/seo/storeDirectoryCache'
+import type { Metadata } from 'next'
+import { notFound } from 'next/navigation'
+import { cache } from 'react'
+
+// One letter of the A–Z store directory: a server-rendered list of
+// `<a href="/coupons/<base>">` for every indexable store whose canonical base
+// starts with that letter, with its live coupon count. This is the crawl path
+// into the store pages (see src/lib/seo/storeDirectory.ts for why).
+//
+// Reads the catalog → per-request, never prerendered (same constraint as
+// /coupons and sitemap.ts: the production image builds against an
+// unreachable placeholder DATABASE_URL).
+export const dynamic = 'force-dynamic'
+
+const baseUrl = BASE_URL.replace(/\/+$/, '')
+
+type LetterParams = { letter: string }
+type LetterSearchParams = Record<string, string | string[] | undefined>
+
+type ResolvedLetterPage = {
+    letter: DirectoryLetter
+    page: DirectoryPage
+}
+
+// cache(): generateMetadata and the body both need the resolved page, and
+// React request-level caching makes that ONE lookup (the underlying catalog
+// read is itself cached in storeDirectoryCache). Any invalid input — a param
+// that is not a directory letter, a `?page=` that is not a positive integer,
+// a page past the end, or a letter with no stores — is `notFound()`: a letter
+// with zero stores must be a 404, never an empty page.
+const resolveLetterPage = cache(
+    async (
+        rawLetter: string,
+        rawPage: string | string[] | undefined,
+    ): Promise<ResolvedLetterPage> => {
+        const letter = parseDirectoryLetter(rawLetter)
+        const pageNumber = parseDirectoryPage(rawPage)
+        if (!letter || pageNumber === null) notFound()
+
+        const buckets = bucketStoresByLetter(await getStoreDirectoryEntries())
+        const bucket = buckets.find(b => b.letter === letter)
+        const page = bucket
+            ? paginateDirectoryBucket(bucket.stores, pageNumber)
+            : null
+        if (!page) notFound()
+
+        return { letter, page }
+    },
+)
+
+async function resolveInput(input: {
+    params: Promise<LetterParams> | LetterParams
+    searchParams?: Promise<LetterSearchParams> | LetterSearchParams
+}): Promise<ResolvedLetterPage> {
+    const { letter } = await Promise.resolve(input.params)
+    const search = (await Promise.resolve(input.searchParams)) ?? {}
+    return resolveLetterPage(
+        typeof letter === 'string' ? letter : '',
+        search.page,
+    )
+}
+
+export async function generateMetadata(input: {
+    params: Promise<LetterParams> | LetterParams
+    searchParams?: Promise<LetterSearchParams> | LetterSearchParams
+}): Promise<Metadata> {
+    const { letter, page } = await resolveInput(input)
+    const label = directoryLetterLabel(letter)
+    const title = `Stores starting with ${label} — coupon codes | Caramel`
+    const description = `Browse every store starting with ${label} that Caramel has live coupon codes for, with the number of codes available at each one right now.`
+    // Canonical is ALWAYS the un-paged letter URL: a split letter's later
+    // pages are continuation, not distinct answers, so they point at page 1
+    // and stay out of the index (still followed — their store links are the
+    // whole point). Page 1 is index, follow.
+    const canonical = `${baseUrl}${directoryPath(letter)}`
+    const banner = `${baseUrl}/caramel_banner.png`
+
+    return {
+        title,
+        description,
+        alternates: { canonical },
+        robots:
+            page.page > 1
+                ? { index: false, follow: true }
+                : { index: true, follow: true },
+        openGraph: {
+            type: 'website',
+            url: canonical,
+            title,
+            description,
+            locale: 'en_US',
+            siteName: 'Caramel',
+            images: [{ url: banner, width: 1200, height: 630 }],
+        },
+        twitter: {
+            card: 'summary_large_image',
+            site: '@CaramelOfficial',
+            title,
+            description,
+            images: [banner],
+        },
+    }
+}
+
+export default async function StoreDirectoryLetterPage(input: {
+    params: Promise<LetterParams> | LetterParams
+    searchParams?: Promise<LetterSearchParams> | LetterSearchParams
+}) {
+    const { letter, page } = await resolveInput(input)
+    const label = directoryLetterLabel(letter)
+    const total = page.stores.length
+    const breadcrumbData = {
+        '@context': 'https://schema.org',
+        '@type': 'BreadcrumbList',
+        itemListElement: [
+            { '@type': 'ListItem', position: 1, name: 'Home', item: baseUrl },
+            {
+                '@type': 'ListItem',
+                position: 2,
+                name: 'Coupons',
+                item: `${baseUrl}/coupons`,
+            },
+            {
+                '@type': 'ListItem',
+                position: 3,
+                name: 'All stores A–Z',
+                item: `${baseUrl}${directoryPath()}`,
+            },
+            { '@type': 'ListItem', position: 4, name: `Stores: ${label}` },
+        ],
+    }
+
+    return (
+        <main className="relative min-h-screen px-6 pt-32 dark:bg-darkBg lg:px-8">
+            <header className="mx-auto max-w-4xl pb-10">
+                <h1 className="mb-4 text-4xl font-extrabold tracking-tight text-gray-900 dark:text-white md:text-3xl">
+                    Stores starting with {label}
+                </h1>
+                <p className="leading-relaxed text-gray-600 dark:text-gray-400">
+                    {page.pageCount > 1
+                        ? `Page ${page.page} of ${page.pageCount}. `
+                        : ''}
+                    {`${total.toLocaleString('en-US')} ${total === 1 ? 'store' : 'stores'} with live coupon codes${page.pageCount > 1 ? ' on this page' : ''}. Each link opens that store's current codes.`}
+                </p>
+            </header>
+            <StoreLetterStrip current={letter} />
+            {/* Deliberately lean markup: this list can hold up to
+                DIRECTORY_PAGE_SIZE stores and every byte here ships twice (HTML
+                + the RSC payload), so styling lives on the <ul> via child
+                selectors and each item is a bare <li><a>base</a> · N codes</li>.
+                Plain <a>, not next/link — see store-letter-strip.tsx. */}
+            <section
+                aria-labelledby="stores-heading"
+                className="mx-auto max-w-4xl pb-24"
+            >
+                <h2
+                    id="stores-heading"
+                    className="mb-4 text-2xl font-bold tracking-tight text-gray-900 dark:text-white"
+                >
+                    {label} stores with coupon codes
+                </h2>
+                <ul className="grid grid-cols-2 gap-x-6 gap-y-2 text-sm text-gray-600 dark:text-gray-400 sm:grid-cols-1 [&>li>a]:font-semibold [&>li>a]:text-gray-900 [&>li>a]:underline-offset-2 hover:[&>li>a]:text-caramel hover:[&>li>a]:underline dark:[&>li>a]:text-white">
+                    {page.stores.map(store => (
+                        <li key={store.base}>
+                            <a
+                                href={`/coupons/${encodeURIComponent(store.base)}`}
+                            >
+                                {store.base}
+                            </a>
+                            {` · ${store.couponCount.toLocaleString('en-US')} ${store.couponCount === 1 ? 'code' : 'codes'}`}
+                        </li>
+                    ))}
+                </ul>
+                {page.pageCount > 1 ? (
+                    <nav
+                        aria-label="Pagination"
+                        className="mt-8 flex items-center gap-4 text-sm font-semibold text-caramel"
+                    >
+                        {page.page > 1 ? (
+                            <a
+                                href={directoryPath(letter, page.page - 1)}
+                                rel="prev"
+                                className="underline-offset-2 hover:underline"
+                            >
+                                ← Previous page
+                            </a>
+                        ) : null}
+                        {page.page < page.pageCount ? (
+                            <a
+                                href={directoryPath(letter, page.page + 1)}
+                                rel="next"
+                                className="underline-offset-2 hover:underline"
+                            >
+                                Next page →
+                            </a>
+                        ) : null}
+                    </nav>
+                ) : null}
+            </section>
+            <script
+                type="application/ld+json"
+                suppressHydrationWarning
+                dangerouslySetInnerHTML={{
+                    __html: jsonLdString(breadcrumbData),
+                }}
+            />
+        </main>
+    )
+}
diff --git a/apps/caramel-app/src/app/(marketing)/coupons/stores/page.tsx b/apps/caramel-app/src/app/(marketing)/coupons/stores/page.tsx
new file mode 100644
index 00000000..79d6011b
--- /dev/null
+++ b/apps/caramel-app/src/app/(marketing)/coupons/stores/page.tsx
@@ -0,0 +1,123 @@
+import StoreLetterStrip from '@/components/coupons/store-letter-strip'
+import { BASE_URL } from '@/lib/env.client'
+import { jsonLdString } from '@/lib/jsonLd'
+import {
+    bucketStoresByLetter,
+    directoryLetterLabel,
+    directoryPath,
+} from '@/lib/seo/storeDirectory'
+import { getStoreDirectoryEntries } from '@/lib/seo/storeDirectoryCache'
+import type { Metadata } from 'next'
+
+// The A–Z store directory index: one link per letter that has indexable
+// stores, with real counts. Reads the coupon catalog, and the production
+// image builds against an unreachable placeholder DATABASE_URL (Dockerfile
+// `.invalid` builder env) — so per-request, never prerendered, like
+// /coupons and sitemap.ts.
+export const dynamic = 'force-dynamic'
+
+const baseUrl = BASE_URL.replace(/\/+$/, '')
+const title = 'All stores with coupon codes A–Z | Caramel'
+const description =
+    'Every store Caramel has live coupon codes for, listed A to Z. Pick a letter to browse stores and their current promo codes.'
+const canonical = `${baseUrl}${directoryPath()}`
+const banner = `${baseUrl}/caramel_banner.png`
+
+export const metadata: Metadata = {
+    title,
+    description,
+    alternates: { canonical },
+    robots: { index: true, follow: true },
+    openGraph: {
+        type: 'website',
+        url: canonical,
+        title,
+        description,
+        locale: 'en_US',
+        siteName: 'Caramel',
+        images: [{ url: banner, width: 1200, height: 630 }],
+    },
+    twitter: {
+        card: 'summary_large_image',
+        site: '@CaramelOfficial',
+        title,
+        description,
+        images: [banner],
+    },
+}
+
+export default async function StoreDirectoryIndexPage() {
+    const entries = await getStoreDirectoryEntries()
+    const buckets = bucketStoresByLetter(entries)
+    const storeCount = entries.length
+
+    const breadcrumbData = {
+        '@context': 'https://schema.org',
+        '@type': 'BreadcrumbList',
+        itemListElement: [
+            { '@type': 'ListItem', position: 1, name: 'Home', item: baseUrl },
+            {
+                '@type': 'ListItem',
+                position: 2,
+                name: 'Coupons',
+                item: `${baseUrl}/coupons`,
+            },
+            { '@type': 'ListItem', position: 3, name: 'All stores A–Z' },
+        ],
+    }
+
+    return (
+        <main className="relative min-h-screen px-6 pt-32 dark:bg-darkBg lg:px-8">
+            <header className="mx-auto max-w-4xl pb-10">
+                <h1 className="mb-4 text-4xl font-extrabold tracking-tight text-gray-900 dark:text-white md:text-3xl">
+                    All stores with coupon codes, A–Z
+                </h1>
+                <p className="leading-relaxed text-gray-600 dark:text-gray-400">
+                    {storeCount > 0
+                        ? `Caramel currently lists live coupon codes for ${storeCount.toLocaleString('en-US')} ${storeCount === 1 ? 'store' : 'stores'}. Pick a letter to see every store that starts with it and how many codes each one has right now.`
+                        : 'Caramel has no stores with live coupon codes right now — new codes are added automatically as they are found.'}
+                </p>
+            </header>
+            <StoreLetterStrip />
+            {buckets.length > 0 ? (
+                <section
+                    aria-labelledby="letters-heading"
+                    className="mx-auto max-w-4xl pb-24"
+                >
+                    <h2
+                        id="letters-heading"
+                        className="mb-4 text-2xl font-bold tracking-tight text-gray-900 dark:text-white"
+                    >
+                        Stores by first letter
+                    </h2>
+                    <ul className="grid grid-cols-3 gap-3 sm:grid-cols-2 [&>li>a]:flex [&>li>a]:items-baseline [&>li>a]:justify-between [&>li>a]:rounded-2xl [&>li>a]:border [&>li>a]:border-gray-100 [&>li>a]:bg-white [&>li>a]:px-4 [&>li>a]:py-3 [&>li>a]:shadow-sm [&>li>a]:transition hover:[&>li>a]:border-orange-200 hover:[&>li>a]:shadow-md dark:[&>li>a]:border-white/10 dark:[&>li>a]:bg-darkSurface">
+                        {buckets.map(bucket => (
+                            <li key={bucket.letter}>
+                                <a href={directoryPath(bucket.letter)}>
+                                    <span className="text-lg font-bold text-gray-900 dark:text-white">
+                                        {directoryLetterLabel(bucket.letter)}
+                                    </span>
+                                    <span className="text-sm text-gray-600 dark:text-gray-400">
+                                        {bucket.stores.length.toLocaleString(
+                                            'en-US',
+                                        )}{' '}
+                                        {bucket.stores.length === 1
+                                            ? 'store'
+                                            : 'stores'}
+                                    </span>
+                                </a>
+                            </li>
+                        ))}
+                    </ul>
+                </section>
+            ) : null}
+            <script
+                type="application/ld+json"
+                suppressHydrationWarning
+                dangerouslySetInnerHTML={{
+                    __html: jsonLdString(breadcrumbData),
+                }}
+            />
+        </main>
+    )
+}
diff --git a/apps/caramel-app/src/app/(marketing)/supported-stores/page.tsx b/apps/caramel-app/src/app/(marketing)/supported-stores/page.tsx
index 832684f5..c9fd09be 100644
--- a/apps/caramel-app/src/app/(marketing)/supported-stores/page.tsx
+++ b/apps/caramel-app/src/app/(marketing)/supported-stores/page.tsx
@@ -1,3 +1,4 @@
+import StoreLetterStrip from '@/components/coupons/store-letter-strip'
 import SearchSection from '@/components/supported-site/search-section'
 import { listRecentlyAddedStores, listTopSites } from '@/lib/couponsRepo'
 import { BASE_URL } from '@/lib/env.client'
@@ -83,6 +84,12 @@ export default async function SupportedSitesPage() {
                 initialTopSites={initialTopSites}
                 recentlyAddedStores={recentlyAddedStores}
             />
+            {/* Server-rendered (outside the client search component) so the
+                letter links exist in the crawler-visible HTML — the grid above
+                is a client-side search and links only 8 stores. */}
+            <div className="w-full px-6 lg:px-8">
+                <StoreLetterStrip />
+            </div>
         </main>
     )
 }
diff --git a/apps/caramel-app/src/app/llms.txt/route.ts b/apps/caramel-app/src/app/llms.txt/route.ts
index f0cb48b0..72b59e58 100644
--- a/apps/caramel-app/src/app/llms.txt/route.ts
+++ b/apps/caramel-app/src/app/llms.txt/route.ts
@@ -41,6 +41,7 @@ const LLMS_TXT = `# Caramel
 - [Coupons](${origin}/coupons): browse the full coupon catalog.
 - [Store coupon pages](${origin}/coupons/amazon.com): per-store codes, one page
   per store domain, e.g. /coupons/amazon.com or /coupons/nike.com.
+- [Store directory A–Z](${origin}/coupons/stores): every store with live codes, by first letter.
 - [Supported stores](${origin}/supported-stores): which stores Caramel can
   auto-apply codes on.
 - [Sources](${origin}/sources): the transparency page listing where Caramel's
diff --git a/apps/caramel-app/src/app/sitemap.ts b/apps/caramel-app/src/app/sitemap.ts
index e316b2c3..6cec0b3f 100644
--- a/apps/caramel-app/src/app/sitemap.ts
+++ b/apps/caramel-app/src/app/sitemap.ts
@@ -1,6 +1,10 @@
 import { listActiveSources, listStoreSitemapEntries } from '@/lib/couponsRepo'
 import { BASE_URL } from '@/lib/env.client'
-import { collapseStoreRows } from '@/lib/seo/sitemapStores'
+import {
+    STORE_SITEMAP_ROW_LIMIT,
+    collapseStoreRows,
+} from '@/lib/seo/sitemapStores'
+import { bucketStoresByLetter, directoryPath } from '@/lib/seo/storeDirectory'
 import type { MetadataRoute } from 'next'
 
 // The store half of this sitemap reads the coupon catalog from Postgres, and
@@ -12,12 +16,6 @@ export const dynamic = 'force-dynamic'
 
 const origin = BASE_URL.replace(/\/+$/, '')
 
-// Upper bound on grouped `coupons.site` rows feeding `/coupons/[store]`
-// entries. The sitemap spec caps a single file at 50,000 URLs; this stays well
-// under it and bounds the query. If the catalog ever outgrows it, the fix is a
-// sitemap index, not a bigger number.
-const STORE_URL_LIMIT = 5000
-
 type StaticRoute = {
     path: string
     changeFrequency: MetadataRoute.Sitemap[number]['changeFrequency']
@@ -56,7 +54,7 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
     // newest `coupons.updated_at` folded into that base: a real catalog
     // timestamp, the freshness signal Google needs to re-read a sitemap.
     const [storeRows, activeSources] = await Promise.all([
-        listStoreSitemapEntries(STORE_URL_LIMIT),
+        listStoreSitemapEntries(STORE_SITEMAP_ROW_LIMIT),
         listActiveSources(),
     ])
     const stores = collapseStoreRows(storeRows)
@@ -66,8 +64,30 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
             ? [...STATIC_ROUTES, SOURCES_ROUTE]
             : [...STATIC_ROUTES]
 
+    // The A–Z directory: its index plus ONLY the letter pages that have
+    // stores, bucketed from the SAME collapsed entries as the store URLs
+    // below (a letter with no stores is a 404, never an empty page). The
+    // directory is the crawl path into the store pages — 8 of ~4,262 had any
+    // internal inbound link before it — so it is listed with the hubs'
+    // weight. Page 2+ of a split letter is noindex and deliberately absent.
+    const letterPages: StaticRoute[] =
+        stores.length > 0
+            ? [
+                  {
+                      path: directoryPath(),
+                      changeFrequency: 'weekly',
+                      priority: 0.8,
+                  },
+                  ...bucketStoresByLetter(stores).map(bucket => ({
+                      path: directoryPath(bucket.letter),
+                      changeFrequency: 'weekly' as const,
+                      priority: 0.6,
+                  })),
+              ]
+            : []
+
     return [
-        ...staticRoutes.map(route => ({
+        ...[...staticRoutes, ...letterPages].map(route => ({
             url: `${origin}${route.path}`,
             changeFrequency: route.changeFrequency,
             priority: route.priority,
diff --git a/apps/caramel-app/src/components/coupons/store-letter-strip.tsx b/apps/caramel-app/src/components/coupons/store-letter-strip.tsx
new file mode 100644
index 00000000..8ec3708a
--- /dev/null
+++ b/apps/caramel-app/src/components/coupons/store-letter-strip.tsx
@@ -0,0 +1,51 @@
+import type { DirectoryLetter } from '@/lib/seo/storeDirectory'
+import {
+    bucketStoresByLetter,
+    directoryLetterLabel,
+    directoryPath,
+} from '@/lib/seo/storeDirectory'
+import { getStoreDirectoryEntries } from '@/lib/seo/storeDirectoryCache'
+
+// Server component — the "Browse stores A–Z" strip on /coupons,
+// /supported-stores and the directory pages. It links ONLY the letters that
+// currently have indexable stores (a letter with none is a 404), read from the
+// same cached, sitemap-identical list the directory pages render.
+//
+// Plain <a>, not next/link: this strip sits on the busiest marketing pages and
+// next/link would prefetch up to 27 force-dynamic routes per view for links a
+// crawler cares about far more than a shopper does.
+export default async function StoreLetterStrip({
+    current,
+}: {
+    /** The letter page being rendered, if any — marked aria-current, not linked. */
+    current?: DirectoryLetter
+}) {
+    const buckets = bucketStoresByLetter(await getStoreDirectoryEntries())
+    if (buckets.length === 0) return null
+
+    return (
+        <nav aria-label="Browse stores A–Z" className="mx-auto max-w-4xl pb-16">
+            <h2 className="mb-4 text-2xl font-bold tracking-tight text-gray-900 dark:text-white">
+                Browse stores A–Z
+            </h2>
+            <ul className="flex flex-wrap gap-2 [&>li>a[aria-current]]:bg-caramel [&>li>a[aria-current]]:text-white [&>li>a]:inline-flex [&>li>a]:min-w-10 [&>li>a]:justify-center [&>li>a]:rounded-full [&>li>a]:border [&>li>a]:border-gray-100 [&>li>a]:bg-white [&>li>a]:px-3 [&>li>a]:py-1.5 [&>li>a]:text-sm [&>li>a]:font-semibold [&>li>a]:text-gray-800 [&>li>a]:shadow-sm [&>li>a]:transition hover:[&>li>a]:border-orange-200 hover:[&>li>a]:shadow-md focus-visible:[&>li>a]:outline-none focus-visible:[&>li>a]:ring-2 focus-visible:[&>li>a]:ring-caramel dark:[&>li>a]:border-white/10 dark:[&>li>a]:bg-darkSurface dark:[&>li>a]:text-gray-100">
+                {buckets.map(bucket => (
+                    <li key={bucket.letter}>
+                        <a
+                            href={directoryPath(bucket.letter)}
+                            aria-current={
+                                bucket.letter === current ? 'page' : undefined
+                            }
+                            title={`${bucket.stores.length.toLocaleString('en-US')} stores`}
+                        >
+                            {directoryLetterLabel(bucket.letter)}
+                        </a>
+                    </li>
+                ))}
+                <li>
+                    <a href={directoryPath()}>All stores</a>
+                </li>
+            </ul>
+        </nav>
+    )
+}
diff --git a/apps/caramel-app/src/components/coupons/store-neighbours.tsx b/apps/caramel-app/src/components/coupons/store-neighbours.tsx
new file mode 100644
index 00000000..f0547586
--- /dev/null
+++ b/apps/caramel-app/src/components/coupons/store-neighbours.tsx
@@ -0,0 +1,83 @@
+import { listNeighbourStoreRows } from '@/lib/couponsRepo'
+import type { StoreSitemapEntry } from '@/lib/seo/sitemapStores'
+import {
+    NEIGHBOUR_FETCH_LIMIT,
+    NEIGHBOUR_STORE_COUNT,
+    directoryLetterLabel,
+    directoryLetterOf,
+    directoryPath,
+    pickNeighbourStores,
+} from '@/lib/seo/storeDirectory'
+
+// Server component — the "More stores" section on every /coupons/[store]
+// page: the 5 indexable stores alphabetically before and after this one, plus
+// the directory letter page this store lives on. Together with the directory
+// this turns the catalog into one crawl chain (every store page reaches its
+// neighbours, every neighbour reaches the next) instead of ~4,262 sitemap-only
+// orphans linked from nowhere (audit 2026-09-11). PopularStores stays beside
+// it: that block links the 4 biggest stores, this one links the nearest.
+//
+// Real data only: the coupon count on each chip is the live visible count the
+// sitemap uses. Plain <a> rather than next/link — see store-letter-strip.tsx.
+export default async function StoreNeighbours({ base }: { base: string }) {
+    // No base = the slug names no registrable store (the page's noindexed
+    // empty state); there is no alphabetical position to link around.
+    if (!base) return null
+
+    const rows = await listNeighbourStoreRows(base, NEIGHBOUR_FETCH_LIMIT)
+    const { previous, next } = pickNeighbourStores(
+        rows,
+        base,
+        NEIGHBOUR_STORE_COUNT,
+    )
+    const letter = directoryLetterOf(base)
+    // previous… ‹this store› …next — one alphabetical run.
+    const neighbours: StoreSitemapEntry[] = [...previous, ...next]
+
+    return (
+        <section
+            aria-labelledby="more-stores-heading"
+            className="mx-auto max-w-4xl pb-16"
+        >
+            <h2
+                id="more-stores-heading"
+                className="mb-4 text-2xl font-bold tracking-tight text-gray-900 dark:text-white"
+            >
+                More stores
+            </h2>
+            {neighbours.length > 0 ? (
+                <ul className="flex flex-wrap gap-3">
+                    {neighbours.map(store => (
+                        <li key={store.base}>
+                            <a
+                                href={`/coupons/${encodeURIComponent(store.base)}`}
+                                className="inline-flex items-center gap-2 rounded-full border border-gray-100 bg-white px-4 py-2 text-sm font-medium text-gray-800 shadow-sm transition hover:border-orange-200 hover:shadow-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-caramel focus-visible:ring-offset-2 dark:border-white/10 dark:bg-darkSurface dark:text-gray-100 dark:hover:border-orange-800/70 dark:focus-visible:ring-offset-darkSurface"
+                            >
+                                {store.base}
+                                <span className="rounded-full bg-caramel/10 px-2 py-0.5 text-xs font-semibold text-caramel dark:bg-caramel/20">
+                                    {store.couponCount.toLocaleString('en-US')}{' '}
+                                    {store.couponCount === 1 ? 'code' : 'codes'}
+                                </span>
+                            </a>
+                        </li>
+                    ))}
+                </ul>
+            ) : null}
+            <p className="mt-4 text-sm text-gray-600 dark:text-gray-400">
+                <a
+                    href={directoryPath(letter)}
+                    className="font-semibold text-caramel underline-offset-2 hover:underline"
+                >
+                    All stores starting with {directoryLetterLabel(letter)}
+                </a>
+                {' · '}
+                <a
+                    href={directoryPath()}
+                    className="font-semibold text-caramel underline-offset-2 hover:underline"
+                >
+                    Store directory A–Z
+                </a>
+            </p>
+        </section>
+    )
+}
diff --git a/apps/caramel-app/src/layouts/Footer/Footer.tsx b/apps/caramel-app/src/layouts/Footer/Footer.tsx
index f476198a..9aa5b4b8 100644
--- a/apps/caramel-app/src/layouts/Footer/Footer.tsx
+++ b/apps/caramel-app/src/layouts/Footer/Footer.tsx
@@ -21,6 +21,7 @@ const productLinks = [
     { name: 'Pricing', url: '/pricing' },
     { name: 'Coupons', url: '/coupons' },
     { name: 'Supported Stores', url: '/supported-stores' },
+    { name: 'Store directory', url: '/coupons/stores' },
     { name: 'Sources', url: '/sources' },
 ]
 
diff --git a/apps/caramel-app/src/lib/couponsRepo.ts b/apps/caramel-app/src/lib/couponsRepo.ts
index 9be417e7..61a450b9 100644
--- a/apps/caramel-app/src/lib/couponsRepo.ts
+++ b/apps/caramel-app/src/lib/couponsRepo.ts
@@ -356,6 +356,74 @@ export async function listStoreSitemapEntries(
     return parseCouponRows(SiteAggregateRowSchema, rawRows, 'sitemap.stores')
 }
 
+/** The two raw-slug windows around a store, for the store page's "More stores" links. */
+export type NeighbourStoreRowsResult = {
+    /** `site < base`, nearest first (ORDER BY site DESC). */
+    before: SiteAggregateRow[]
+    /** `site > base`, nearest first (ORDER BY site ASC). */
+    after: SiteAggregateRow[]
+}
+
+/**
+ * (marketing)/coupons/[store]/page.tsx's "More stores" section — the `limit`
+ * visible sites alphabetically just before and just after `base`, as the same
+ * per-site aggregate rows the sitemap reads (count + newest updated_at), so
+ * src/lib/seo/storeDirectory.ts's pickNeighbourStores can collapse them with
+ * the sitemap's own collapseStoreRows and show real coupon counts.
+ *
+ * Why this exists: every store page linking to its alphabetical neighbours
+ * turns ~4,262 sitemap-only orphans into one crawl chain across the whole
+ * catalog (audit 2026-09-11: 8 store pages had any internal inbound link).
+ *
+ * Two range scans, not one: `site < base ORDER BY site DESC LIMIT n` and
+ * `site > base ORDER BY site ASC LIMIT n` each walk `coupons_site_idx` from
+ * the boundary and stop after n groups — a single query would need a window
+ * function over every site. Comparison is on the RAW slug (the index's
+ * collation order); the caller collapses subdomain/mixed-case slugs to their
+ * base afterwards, which is why it over-fetches (NEIGHBOUR_FETCH_LIMIT).
+ * `visibleCouponsWhere()` keeps every row here a store with ≥1 visible coupon,
+ * i.e. an indexable page worth linking to.
+ */
+export async function listNeighbourStoreRows(
+    base: string,
+    limit: number,
+): Promise<NeighbourStoreRowsResult> {
+    const [beforeRaw, afterRaw] = await Promise.all([
+        prisma.$queryRaw(Prisma.sql`
+            SELECT site,
+                   COUNT(*)::int AS coupon_count,
+                   MAX(updated_at) AS last_updated
+            FROM coupons
+            WHERE ${visibleCouponsWhere()} AND site IS NOT NULL AND site < ${base}
+            GROUP BY site
+            ORDER BY site DESC
+            LIMIT ${limit}
+        `),
+        prisma.$queryRaw(Prisma.sql`
+            SELECT site,
+                   COUNT(*)::int AS coupon_count,
+                   MAX(updated_at) AS last_updated
+            FROM coupons
+            WHERE ${visibleCouponsWhere()} AND site IS NOT NULL AND site > ${base}
+            GROUP BY site
+            ORDER BY site ASC
+            LIMIT ${limit}
+        `),
+    ])
+    return {
+        before: parseCouponRows(
+            SiteAggregateRowSchema,
+            beforeRaw,
+            'store.neighbours.before',
+        ),
+        after: parseCouponRows(
+            SiteAggregateRowSchema,
+            afterRaw,
+            'store.neighbours.after',
+        ),
+    }
+}
+
 /** api/coupons/filters/route.ts GET — sites half. The route's `includeSites` gate stays there (calls this only when true); this fn only owns its own `sitesLimit<=0` short-circuit. */
 export async function listFilterSites(sitesLimit: number): Promise<SiteRow[]> {
     if (sitesLimit <= 0) return []
diff --git a/apps/caramel-app/src/lib/seo/sitemapStores.ts b/apps/caramel-app/src/lib/seo/sitemapStores.ts
index b750d018..33f94568 100644
--- a/apps/caramel-app/src/lib/seo/sitemapStores.ts
+++ b/apps/caramel-app/src/lib/seo/sitemapStores.ts
@@ -15,6 +15,15 @@
 import { evaluateStorePageIndexability } from '@/lib/seo/storeIndexability'
 import { resolveStoreDomain } from '@/lib/storeDomain'
 
+/**
+ * Upper bound on grouped `coupons.site` rows feeding `/coupons/[store]`
+ * entries — shared by the sitemap and the A–Z directory so both read the same
+ * window of the catalog. The sitemap spec caps a single file at 50,000 URLs;
+ * this stays well under it and bounds the query. If the catalog ever outgrows
+ * it, the fix is a sitemap index, not a bigger number.
+ */
+export const STORE_SITEMAP_ROW_LIMIT = 5000
+
 /** One `GROUP BY site` row from couponsRepo.listStoreSitemapEntries. */
 export type StoreSitemapRow = {
     site: string | null
diff --git a/apps/caramel-app/src/lib/seo/storeDirectory.ts b/apps/caramel-app/src/lib/seo/storeDirectory.ts
new file mode 100644
index 00000000..71f185b7
--- /dev/null
+++ b/apps/caramel-app/src/lib/seo/storeDirectory.ts
@@ -0,0 +1,204 @@
+// src/lib/seo/storeDirectory.ts
+//
+// The A–Z store directory (/coupons/stores, /coupons/stores/[letter]) and the
+// per-store "More stores" neighbour links exist for ONE reason: crawl
+// discovery. On 2026-09-11 grabcaramel.com had ~4,262 canonical
+// /coupons/<store> pages and only 8 of them had any internal inbound link (the
+// 4-item "Popular coupon stores" block, identical on every page, plus 8 tiles
+// on /supported-stores). GSC knew 4,289 of 4,317 sitemap URLs as "unknown" —
+// orphan pages are neither crawled nor ranked, and a sitemap alone is not a
+// discovery mechanism Google trusts here. See
+// caramel-artifact/seo-2026-09-11/audit-findings.md §Interlinking.
+//
+// Everything in this module is pure (no DB, no env, no I/O) and operates on
+// the SAME collapsed entries the sitemap emits (sitemapStores.collapseStoreRows
+// over couponsRepo.listStoreSitemapEntries), so the directory and the sitemap
+// can never disagree about which stores exist or which are indexable.
+import type {
+    StoreSitemapEntry,
+    StoreSitemapRow,
+} from '@/lib/seo/sitemapStores'
+import { collapseStoreRows } from '@/lib/seo/sitemapStores'
+
+/** Every directory bucket, in display order. `0-9` covers bases whose first character is not a–z. */
+export const DIRECTORY_LETTERS = [
+    '0-9',
+    'a',
+    'b',
+    'c',
+    'd',
+    'e',
+    'f',
+    'g',
+    'h',
+    'i',
+    'j',
+    'k',
+    'l',
+    'm',
+    'n',
+    'o',
+    'p',
+    'q',
+    'r',
+    's',
+    't',
+    'u',
+    'v',
+    'w',
+    'x',
+    'y',
+    'z',
+] as const
+export type DirectoryLetter = (typeof DIRECTORY_LETTERS)[number]
+
+/**
+ * Stores per letter page before `?page=N` splitting kicks in. Measured on the
+ * dev catalog 2026-09-12 (4,124 store slugs): b 425, c 400, s 367, a 313 —
+ * every letter fits on one page today, but `b` sits at 85% of this cap and the
+ * catalog grows, so the split is wired rather than deferred. 500 keeps the
+ * biggest possible page's HTML (list + its RSC payload twin) near 150 KB.
+ */
+export const DIRECTORY_PAGE_SIZE = 500
+
+/** Neighbour links per direction on a store page ("More stores"). */
+export const NEIGHBOUR_STORE_COUNT = 5
+
+/**
+ * Raw rows to fetch per direction for NEIGHBOUR_STORE_COUNT neighbours. The
+ * neighbour queries walk RAW `coupons.site` order, and a raw slug can fold into
+ * a base already listed (athleta.gap.com → gap.com) or into the current base
+ * itself — so over-fetch, collapse, then trim. 84 of 4,311 prod slugs were
+ * subdomains (2%); 3× is generous.
+ */
+export const NEIGHBOUR_FETCH_LIMIT = NEIGHBOUR_STORE_COUNT * 3
+
+const DIRECTORY_PATH = '/coupons/stores'
+
+/** The bucket a canonical base lands in: its first character, digits (and anything else non a–z) → '0-9'. */
+export function directoryLetterOf(base: string): DirectoryLetter {
+    const first = base.trim().charAt(0).toLowerCase()
+    return first >= 'a' && first <= 'z' ? (first as DirectoryLetter) : '0-9'
+}
+
+/** `/coupons/stores/[letter]` param → bucket, or null for anything that is not exactly one of DIRECTORY_LETTERS (case-insensitive). */
+export function parseDirectoryLetter(raw: string): DirectoryLetter | null {
+    const letter = raw.trim().toLowerCase()
+    return (DIRECTORY_LETTERS as ReadonlyArray<string>).includes(letter)
+        ? (letter as DirectoryLetter)
+        : null
+}
+
+/** Human label: 'B', or '0–9' for the digit bucket. */
+export function directoryLetterLabel(letter: DirectoryLetter): string {
+    return letter === '0-9' ? '0–9' : letter.toUpperCase()
+}
+
+/**
+ * `?page=` → 1-based page number. Absent → 1. Anything that is not a positive
+ * integer literal (`0`, `-1`, `1.5`, `abc`, a repeated param) → null, which the
+ * route turns into a 404 rather than guessing.
+ */
+export function parseDirectoryPage(
+    raw: string | string[] | undefined,
+): number | null {
+    if (raw === undefined) return 1
+    if (typeof raw !== 'string') return null
+    if (!/^[1-9][0-9]*$/.test(raw)) return null
+    const page = Number(raw)
+    return Number.isSafeInteger(page) ? page : null
+}
+
+/** Directory URL paths — one place, so links, canonicals and the sitemap agree. */
+export function directoryPath(letter?: DirectoryLetter, page = 1): string {
+    if (!letter) return DIRECTORY_PATH
+    const path = `${DIRECTORY_PATH}/${letter}`
+    return page > 1 ? `${path}?page=${page}` : path
+}
+
+export type DirectoryBucket = {
+    letter: DirectoryLetter
+    /** Sorted by base — collapseStoreRows' order, preserved. */
+    stores: StoreSitemapEntry[]
+}
+
+/**
+ * Group collapsed entries by directory letter. Only NON-EMPTY buckets are
+ * returned, in DIRECTORY_LETTERS order — a letter with no stores must be a
+ * 404, never an empty page, and must not be linked or sitemapped.
+ */
+export function bucketStoresByLetter(
+    entries: ReadonlyArray<StoreSitemapEntry>,
+): DirectoryBucket[] {
+    const byLetter = new Map<DirectoryLetter, StoreSitemapEntry[]>()
+    for (const entry of entries) {
+        const letter = directoryLetterOf(entry.base)
+        const bucket = byLetter.get(letter)
+        if (bucket) bucket.push(entry)
+        else byLetter.set(letter, [entry])
+    }
+    return DIRECTORY_LETTERS.flatMap(letter => {
+        const stores = byLetter.get(letter)
+        return stores && stores.length > 0 ? [{ letter, stores }] : []
+    })
+}
+
+export type DirectoryPage = {
+    page: number
+    pageCount: number
+    stores: StoreSitemapEntry[]
+}
+
+/**
+ * The slice of a bucket shown on page N (1-based). Returns null when the page
+ * is out of range — including page 1 of an empty bucket — so the route can
+ * 404. Page 1 is the un-paged URL; pages > 1 carry `?page=N`, canonicalize to
+ * page 1 and are `noindex, follow` (the route owns those rules).
+ */
+export function paginateDirectoryBucket(
+    stores: ReadonlyArray<StoreSitemapEntry>,
+    page: number,
+    pageSize: number = DIRECTORY_PAGE_SIZE,
+): DirectoryPage | null {
+    if (stores.length === 0) return null
+    const pageCount = Math.ceil(stores.length / pageSize)
+    if (!Number.isInteger(page) || page < 1 || page > pageCount) return null
+    const start = (page - 1) * pageSize
+    return { page, pageCount, stores: stores.slice(start, start + pageSize) }
+}
+
+export type NeighbourStoreRows = {
+    /** Raw aggregate rows with `site < base`, nearest first (ORDER BY site DESC). */
+    before: ReadonlyArray<StoreSitemapRow>
+    /** Raw aggregate rows with `site > base`, nearest first (ORDER BY site ASC). */
+    after: ReadonlyArray<StoreSitemapRow>
+}
+
+export type NeighbourStores = {
+    /** Up to `count` indexable bases alphabetically before `base`, ascending. */
+    previous: StoreSitemapEntry[]
+    /** Up to `count` indexable bases alphabetically after `base`, ascending. */
+    next: StoreSitemapEntry[]
+}
+
+/**
+ * Collapse the two raw neighbour windows to canonical bases (same collapse +
+ * indexability policy as the sitemap), drop the current base (its own
+ * subdomain rows fold into it) and any base already taken by the other side,
+ * then keep the `count` nearest per side. Both lists come back ascending so
+ * the page reads as one alphabetical run: previous… ‹current› …next.
+ */
+export function pickNeighbourStores(
+    rows: NeighbourStoreRows,
+    base: string,
+    count: number = NEIGHBOUR_STORE_COUNT,
+): NeighbourStores {
+    const previous = collapseStoreRows(rows.before)
+        .filter(entry => entry.base !== base)
+        .slice(-count)
+    const taken = new Set(previous.map(entry => entry.base))
+    const next = collapseStoreRows(rows.after)
+        .filter(entry => entry.base !== base && !taken.has(entry.base))
+        .slice(0, count)
+    return { previous, next }
+}
diff --git a/apps/caramel-app/src/lib/seo/storeDirectoryCache.ts b/apps/caramel-app/src/lib/seo/storeDirectoryCache.ts
new file mode 100644
index 00000000..346f8954
--- /dev/null
+++ b/apps/caramel-app/src/lib/seo/storeDirectoryCache.ts
@@ -0,0 +1,79 @@
+// In-process cache of the collapsed, indexable store list that feeds the A–Z
+// directory (/coupons/stores, /coupons/stores/[letter]) and the "Browse stores
+// A–Z" letter strips on /coupons and /supported-stores.
+//
+// The read is the SAME one the sitemap performs — couponsRepo's
+// listStoreSitemapEntries (one GROUP BY over visible coupons, ~4.3k rows)
+// collapsed by sitemapStores.collapseStoreRows — so the directory can never
+// list a store the sitemap omits or vice-versa. It is deliberately NOT a
+// second, per-letter SQL query: a raw `site` first-character filter would
+// split athleta.gap.com away from gap.com, i.e. re-implement the Public Suffix
+// List collapse in SQL and drift from it.
+//
+// Why cache at all: that GROUP BY costs ~150 ms on prod (the same order as
+// listTopSites, measured in #223's healthcheck-flap work), and the letter strip
+// now sits on /coupons, the busiest marketing page. One build per 5 minutes per
+// process keeps the strip free; 5 min of staleness is invisible for a list
+// that changes on ingest pushes minutes-to-hours apart. Same shape as
+// supportedStoresCache.ts: in-flight builds are de-duplicated (a stampede after
+// expiry runs ONE query), and a rebuild that throws keeps serving the previous
+// entry rather than 500ing a hub page. Single-instance by design (NF-13).
+//
+// The sitemap itself stays uncached (sitemap.ts reads the repo directly): its
+// `lastmod` freshness is the whole point of #236, and crawlers hit it rarely.
+import { listStoreSitemapEntries } from '@/lib/couponsRepo'
+import type { StoreSitemapEntry } from '@/lib/seo/sitemapStores'
+import {
+    STORE_SITEMAP_ROW_LIMIT,
+    collapseStoreRows,
+} from '@/lib/seo/sitemapStores'
+
+export const STORE_DIRECTORY_TTL_MS = 5 * 60 * 1000
+
+type CachedDirectory = {
+    entries: StoreSitemapEntry[]
+    builtAt: number
+}
+
+let cached: CachedDirectory | null = null
+let inFlight: Promise<CachedDirectory> | null = null
+
+async function build(): Promise<CachedDirectory> {
+    const rows = await listStoreSitemapEntries(STORE_SITEMAP_ROW_LIMIT)
+    return { entries: collapseStoreRows(rows), builtAt: Date.now() }
+}
+
+/**
+ * Every indexable store as a canonical, base-sorted entry — from memory while
+ * younger than STORE_DIRECTORY_TTL_MS, rebuilt once (shared across concurrent
+ * callers) otherwise. Callers must treat the array as read-only.
+ */
+export async function getStoreDirectoryEntries(
+    now: number = Date.now(),
+): Promise<ReadonlyArray<StoreSitemapEntry>> {
+    if (cached && now - cached.builtAt < STORE_DIRECTORY_TTL_MS) {
+        return cached.entries
+    }
+    if (!inFlight) {
+        inFlight = build()
+            .then(fresh => {
+                cached = fresh
+                return fresh
+            })
+            .finally(() => {
+                inFlight = null
+            })
+    }
+    try {
+        return (await inFlight).entries
+    } catch (err) {
+        if (cached) return cached.entries
+        throw err
+    }
+}
+
+/** Drop the cached list (tests). */
+export function resetStoreDirectoryCache(): void {
+    cached = null
+    inFlight = null
+}
diff --git a/apps/caramel-app/tests/integration/coupons-read.itest.ts b/apps/caramel-app/tests/integration/coupons-read.itest.ts
index b70b3ac6..028fea89 100644
--- a/apps/caramel-app/tests/integration/coupons-read.itest.ts
+++ b/apps/caramel-app/tests/integration/coupons-read.itest.ts
@@ -3,6 +3,7 @@ import {
     getCouponStats,
     listActiveSources,
     listCoupons,
+    listNeighbourStoreRows,
     listStoreSitemapEntries,
     listSupportedStoreConfigs,
 } from '@/lib/couponsRepo'
@@ -239,3 +240,38 @@ describe('listStoreSitemapEntries — per-site visible aggregates for the sitema
         expect(await listStoreSitemapEntries(2)).toHaveLength(2)
     })
 })
+
+describe('listNeighbourStoreRows — alphabetical windows around a store (real pg :58005)', () => {
+    it('returns the visible sites strictly before (nearest first) and after (nearest first) the base, each bounded by limit, as parsed aggregate rows', async () => {
+        // The seed's visible sites, in order: amazon.com, codecademy.com,
+        // ebay.com, target.com, walmart.com. Around ebay.com with limit 2 the
+        // windows are exact — no other suite writes a site between them
+        // (ingest-catalog only touches ebay.com itself, and files run serially).
+        const { before, after } = await listNeighbourStoreRows('ebay.com', 2)
+
+        expect(before.map(r => r.site)).toEqual([
+            'codecademy.com',
+            'amazon.com',
+        ])
+        expect(after.map(r => r.site)).toEqual(['target.com', 'walmart.com'])
+
+        for (const row of [...before, ...after]) {
+            // ::int count as a JS number ≥ 1 (a neighbour is always a store
+            // with visible coupons), and a real Date for the newest updated_at.
+            expect(Number.isInteger(row.coupon_count)).toBe(true)
+            expect(row.coupon_count).toBeGreaterThan(0)
+            expect(row.last_updated).toBeInstanceOf(Date)
+        }
+
+        // The window counts agree with the sitemap aggregate for the same site.
+        const sitemapRows = await listStoreSitemapEntries(5000)
+        const codecademy = sitemapRows.find(r => r.site === 'codecademy.com')
+        expect(before[0]!.coupon_count).toBe(codecademy!.coupon_count)
+
+        // The catalog's first site has an empty `before` window; the limit is
+        // a real bound.
+        const edge = await listNeighbourStoreRows('amazon.com', 1)
+        expect(edge.before).toEqual([])
+        expect(edge.after.map(r => r.site)).toEqual(['codecademy.com'])
+    })
+})
diff --git a/apps/caramel-app/tests/unit/coupons-store-directory.test.ts b/apps/caramel-app/tests/unit/coupons-store-directory.test.ts
new file mode 100644
index 00000000..3e06998d
--- /dev/null
+++ b/apps/caramel-app/tests/unit/coupons-store-directory.test.ts
@@ -0,0 +1,304 @@
+import StoreDirectoryLetterPage, {
+    generateMetadata,
+} from '@/app/(marketing)/coupons/stores/[letter]/page'
+import StoreDirectoryIndexPage, {
+    metadata as indexMetadata,
+} from '@/app/(marketing)/coupons/stores/page'
+import StoreLetterStrip from '@/components/coupons/store-letter-strip'
+import StoreNeighbours from '@/components/coupons/store-neighbours'
+import { BASE_URL } from '@/lib/env.client'
+import { DIRECTORY_PAGE_SIZE } from '@/lib/seo/storeDirectory'
+import { resetStoreDirectoryCache } from '@/lib/seo/storeDirectoryCache'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+// The A–Z store directory routes + the two server components that link into
+// it, exercised the way coupons-store-page.test.ts exercises the store page:
+// `@/lib/prisma` mocked with a rule-based `$queryRaw` keyed on the composed
+// `.sql`, the default exports called directly, the returned (unrendered)
+// element tree inspected. The directory read goes through the in-process
+// cache, so it is reset before every case.
+//
+// Rule order matters: the neighbour windows also contain `GROUP BY site`, so
+// they are matched on their `site < ?` / `site > ?` predicates FIRST.
+
+type MockRule = { match: (sql: string) => boolean; rows: unknown[] }
+let rules: MockRule[] = []
+function mockRows(match: (sql: string) => boolean, rows: unknown[]) {
+    rules.push({ match, rows })
+}
+
+vi.mock('@/lib/prisma', () => ({
+    default: {
+        $queryRaw: (arg: { sql: string }) => {
+            const rows = rules.find(r => r.match(arg.sql))?.rows ?? []
+            return Promise.resolve(rows)
+        },
+    },
+}))
+
+const origin = BASE_URL.replace(/\/+$/, '')
+const isDirectoryRead = (sql: string) =>
+    sql.includes('GROUP BY site') &&
+    !sql.includes('site < ?') &&
+    !sql.includes('site > ?')
+
+const aggregateRow = (site: string, coupon_count = 3) => ({
+    site,
+    coupon_count,
+    last_updated: '2026-09-01T00:00:00.000Z',
+})
+
+// Real prod shapes: a subdomain slug that folds into gap.com, a mixed-case
+// twin, a digit-leading store, a non-store and a zero-count row (both dropped).
+const CATALOG = [
+    aggregateRow('123ink.ca', 25),
+    aggregateRow('athleta.gap.com', 7),
+    aggregateRow('Brooklinen.com', 2),
+    aggregateRow('brooklinen.com', 9),
+    aggregateRow('co.uk', 50),
+    aggregateRow('gap.com', 30),
+    aggregateRow('michaels.com', 12),
+    aggregateRow('zero.com', 0),
+]
+
+function tree(el: unknown): string {
+    return JSON.stringify(el)
+}
+
+beforeEach(() => {
+    rules = []
+    resetStoreDirectoryCache()
+})
+
+describe('/coupons/stores — directory index', () => {
+    it('metadata: the A–Z title, a self canonical, index+follow', () => {
+        expect(indexMetadata.title).toBe(
+            'All stores with coupon codes A–Z | Caramel',
+        )
+        expect(indexMetadata.alternates?.canonical).toBe(
+            `${origin}/coupons/stores`,
+        )
+        expect(indexMetadata.robots).toEqual({ index: true, follow: true })
+    })
+
+    it('links every letter that has stores with its real store count, and no letter without', async () => {
+        mockRows(isDirectoryRead, CATALOG)
+        const html = tree(await StoreDirectoryIndexPage())
+
+        // 123ink.ca → 0-9; brooklinen.com → b; gap.com (athleta folded) → g;
+        // michaels.com → m. co.uk and zero.com are not stores.
+        for (const letter of ['0-9', 'b', 'g', 'm']) {
+            expect(html).toContain(`"href":"/coupons/stores/${letter}"`)
+        }
+        for (const letter of ['a', 'c', 'z']) {
+            expect(html).not.toContain(`"href":"/coupons/stores/${letter}"`)
+        }
+        // Counts are the collapsed catalog's, stated on the page.
+        expect(html).toContain('4 stores')
+        expect(html).not.toContain('co.uk')
+        expect(html).not.toContain('zero.com')
+    })
+})
+
+describe('/coupons/stores/[letter] — generateMetadata', () => {
+    it('a letter with stores: "Stores starting with X" title, un-paged self canonical, index+follow', async () => {
+        mockRows(isDirectoryRead, CATALOG)
+        const metadata = await generateMetadata({ params: { letter: 'b' } })
+        expect(metadata.title).toBe(
+            'Stores starting with B — coupon codes | Caramel',
+        )
+        expect(metadata.alternates?.canonical).toBe(
+            `${origin}/coupons/stores/b`,
+        )
+        expect(metadata.robots).toEqual({ index: true, follow: true })
+        expect(metadata.openGraph?.url).toBe(`${origin}/coupons/stores/b`)
+    })
+
+    it('the digit bucket is labelled 0–9 and canonicalizes to /coupons/stores/0-9', async () => {
+        mockRows(isDirectoryRead, CATALOG)
+        const metadata = await generateMetadata({ params: { letter: '0-9' } })
+        expect(metadata.title).toBe(
+            'Stores starting with 0–9 — coupon codes | Caramel',
+        )
+        expect(metadata.alternates?.canonical).toBe(
+            `${origin}/coupons/stores/0-9`,
+        )
+    })
+
+    it('an uppercase param resolves to the lowercase letter and canonicalizes there', async () => {
+        mockRows(isDirectoryRead, CATALOG)
+        const metadata = await generateMetadata({ params: { letter: 'M' } })
+        expect(metadata.alternates?.canonical).toBe(
+            `${origin}/coupons/stores/m`,
+        )
+    })
+
+    it('a letter with NO stores is notFound() — never an empty indexable page', async () => {
+        mockRows(isDirectoryRead, CATALOG)
+        await expect(
+            generateMetadata({ params: { letter: 'q' } }),
+        ).rejects.toMatchObject({ digest: expect.stringContaining('404') })
+        await expect(
+            StoreDirectoryLetterPage({ params: { letter: 'q' } }),
+        ).rejects.toMatchObject({ digest: expect.stringContaining('404') })
+    })
+
+    it('a param that is not a directory letter is notFound()', async () => {
+        mockRows(isDirectoryRead, CATALOG)
+        for (const bad of ['zz', 'stores', 'gap.com', '']) {
+            await expect(
+                generateMetadata({ params: { letter: bad } }),
+                bad,
+            ).rejects.toMatchObject({ digest: expect.stringContaining('404') })
+        }
+    })
+
+    it('an empty catalog makes every letter notFound()', async () => {
+        mockRows(isDirectoryRead, [])
+        await expect(
+            generateMetadata({ params: { letter: 'b' } }),
+        ).rejects.toMatchObject({ digest: expect.stringContaining('404') })
+    })
+})
+
+describe('/coupons/stores/[letter] — body', () => {
+    it("lists ONLY that letter's canonical stores as /coupons/<base> links with their live counts, and marks the letter in the strip", async () => {
+        mockRows(isDirectoryRead, CATALOG)
+        const html = tree(
+            await StoreDirectoryLetterPage({ params: { letter: 'b' } }),
+        )
+
+        // JSX keeps interpolated text as separate children.
+        expect(html).toContain('"children":["Stores starting with ","B"]')
+        expect(html).toContain('"href":"/coupons/brooklinen.com"')
+        // Mixed-case twin folded: one link, summed count.
+        expect(html).not.toContain('Brooklinen.com')
+        expect(html).toContain('· 11 codes')
+        // Other letters' stores are not on this page.
+        expect(html).not.toContain('"href":"/coupons/gap.com"')
+        expect(html).not.toContain('"href":"/coupons/michaels.com"')
+        expect(html).not.toContain('"href":"/coupons/123ink.ca"')
+        // The strip is told which letter it is on.
+        expect(html).toContain('"current":"b"')
+        // No pagination nav for a single page.
+        expect(html).not.toContain('Next page')
+        // Breadcrumbs point back at the directory index.
+        expect(html).toContain(`${origin}/coupons/stores`)
+    })
+
+    it('a letter whose store count exceeds DIRECTORY_PAGE_SIZE splits: page 2 is noindex+follow, canonicalizes to page 1, and links back', async () => {
+        const many = Array.from({ length: DIRECTORY_PAGE_SIZE + 1 }, (_, i) =>
+            aggregateRow(`b${String(i).padStart(4, '0')}.com`),
+        )
+        mockRows(isDirectoryRead, many)
+
+        const page1 = await generateMetadata({
+            params: { letter: 'b' },
+            searchParams: {},
+        })
+        expect(page1.robots).toEqual({ index: true, follow: true })
+
+        const page2 = await generateMetadata({
+            params: { letter: 'b' },
+            searchParams: Promise.resolve({ page: '2' }),
+        })
+        expect(page2.robots).toEqual({ index: false, follow: true })
+        expect(page2.alternates?.canonical).toBe(`${origin}/coupons/stores/b`)
+
+        const html = tree(
+            await StoreDirectoryLetterPage({
+                params: { letter: 'b' },
+                searchParams: { page: '2' },
+            }),
+        )
+        expect(html).toContain('Page 2 of 2')
+        expect(html).toContain('"href":"/coupons/b0500.com"')
+        expect(html).not.toContain('"href":"/coupons/b0499.com"')
+        expect(html).toContain('"href":"/coupons/stores/b"')
+        expect(html).toContain('"rel":"prev"')
+        expect(html).not.toContain('"rel":"next"')
+
+        const first = tree(
+            await StoreDirectoryLetterPage({ params: { letter: 'b' } }),
+        )
+        expect(first).toContain('"href":"/coupons/stores/b?page=2"')
+        expect(first).toContain('"rel":"next"')
+    })
+
+    it('a page past the end or a malformed ?page= is notFound()', async () => {
+        mockRows(isDirectoryRead, CATALOG)
+        for (const page of ['2', '0', 'abc', '1.5']) {
+            await expect(
+                generateMetadata({
+                    params: { letter: 'b' },
+                    searchParams: { page },
+                }),
+                page,
+            ).rejects.toMatchObject({ digest: expect.stringContaining('404') })
+        }
+    })
+})
+
+describe('StoreLetterStrip — "Browse stores A–Z"', () => {
+    it('renders a link per letter that has stores, aria-current on the current one, plus the index link; null on an empty catalog', async () => {
+        mockRows(isDirectoryRead, CATALOG)
+        const html = tree(await StoreLetterStrip({ current: 'g' }))
+        expect(html).toContain('Browse stores A–Z')
+        expect(html).toContain('"href":"/coupons/stores/0-9"')
+        expect(html).toContain('"href":"/coupons/stores/b"')
+        expect(html).toContain(
+            '"href":"/coupons/stores/g","aria-current":"page"',
+        )
+        expect(html).toContain('"href":"/coupons/stores/m"')
+        expect(html).not.toContain('"href":"/coupons/stores/a"')
+        expect(html).toContain('"href":"/coupons/stores"')
+
+        resetStoreDirectoryCache()
+        rules = []
+        mockRows(isDirectoryRead, [])
+        expect(await StoreLetterStrip({})).toBeNull()
+    })
+})
+
+describe('StoreNeighbours — "More stores" on a store page', () => {
+    it('links the nearest indexable stores on both sides (never itself), with live counts, plus its letter page and the index', async () => {
+        mockRows(
+            sql => sql.includes('site < ?'),
+            [
+                aggregateRow('gaomon.com', 4),
+                aggregateRow('gamestop.com', 8),
+                aggregateRow('athleta.gap.com', 7),
+            ],
+        )
+        mockRows(
+            sql => sql.includes('site > ?'),
+            [aggregateRow('gapfactory.com', 1), aggregateRow('garmin.com', 5)],
+        )
+
+        const html = tree(await StoreNeighbours({ base: 'gap.com' }))
+        expect(html).toContain('More stores')
+        expect(html).toContain('"href":"/coupons/gamestop.com"')
+        expect(html).toContain('"href":"/coupons/gaomon.com"')
+        expect(html).toContain('"href":"/coupons/gapfactory.com"')
+        expect(html).toContain('"href":"/coupons/garmin.com"')
+        expect(html).not.toContain('"href":"/coupons/gap.com"')
+        expect(html).not.toContain('athleta.gap.com')
+        expect(html).toContain('"1"," ","code"')
+        expect(html).toContain('"href":"/coupons/stores/g"')
+        expect(html).toContain('"children":["All stores starting with ","G"]')
+        expect(html).toContain('"href":"/coupons/stores"')
+    })
+
+    it('renders nothing for a slug that names no store (no alphabetical position to link around)', async () => {
+        expect(await StoreNeighbours({ base: '' })).toBeNull()
+    })
+
+    it('with no neighbours at all it still links the letter page (the directory is the fallback path)', async () => {
+        const html = tree(await StoreNeighbours({ base: '123ink.ca' }))
+        expect(html).toContain('"href":"/coupons/stores/0-9"')
+        expect(html).toContain('"children":["All stores starting with ","0–9"]')
+        // No neighbour list at all — not an empty <ul>.
+        expect(html).not.toContain('"type":"ul"')
+        expect(html).not.toContain('"href":"/coupons/123ink.ca"')
+    })
+})
diff --git a/apps/caramel-app/tests/unit/couponsRepo.test.ts b/apps/caramel-app/tests/unit/couponsRepo.test.ts
index 5caaf718..599f95ab 100644
--- a/apps/caramel-app/tests/unit/couponsRepo.test.ts
+++ b/apps/caramel-app/tests/unit/couponsRepo.test.ts
@@ -2,6 +2,7 @@ import {
     expireCoupons,
     getCouponStats,
     listCoupons,
+    listNeighbourStoreRows,
     listStoreCoupons,
     listStoreSitemapEntries,
     requestSource,
@@ -328,3 +329,66 @@ describe('store-matching reads bind the LOWERCASE base (site column is stored lo
         }
     })
 })
+
+// A production-shaped `GROUP BY site` aggregate row (listNeighbourStoreRows).
+const aggregateRow = (site: string) => ({
+    site,
+    coupon_count: 3,
+    last_updated: '2026-09-01T00:00:00.000Z',
+})
+
+describe('listNeighbourStoreRows — the two raw-slug windows behind "More stores"', () => {
+    it('issues one DESC window below and one ASC window above the base, both under the shared visibility predicate, GROUP BY site, bound LIMIT', async () => {
+        mockRows(
+            sql => sql.includes('site < ?'),
+            [aggregateRow('gaomon.com'), aggregateRow('gamestop.com')],
+        )
+        mockRows(
+            sql => sql.includes('site > ?'),
+            [aggregateRow('gapfactory.com')],
+        )
+
+        const result = await listNeighbourStoreRows('gap.com', 15)
+
+        expect(capturedQueries).toHaveLength(2)
+        const [before, after] = capturedQueries as [string, string]
+        // Same predicate every listing read uses — a neighbour is always a
+        // store with ≥1 visible coupon (i.e. an indexable page).
+        for (const q of [before, after]) {
+            expect(q).toMatch(/status IN \(\?,\?(,\?)*\) AND expired = FALSE/)
+            expect(q).toContain('site IS NOT NULL')
+            expect(q).toContain('COUNT(*)::int AS coupon_count')
+            expect(q).toContain('MAX(updated_at) AS last_updated')
+            expect(q).toContain('GROUP BY site')
+            expect(q).toMatch(/LIMIT \?/)
+            // Raw-slug comparison on the indexed column — never LOWER(site).
+            expect(q).not.toMatch(/lower\(site\)/i)
+        }
+        expect(before).toContain('site < ?')
+        expect(before).toContain('ORDER BY site DESC')
+        expect(after).toContain('site > ?')
+        expect(after).toContain('ORDER BY site ASC')
+
+        // The base and the limit are bound parameters of BOTH queries.
+        for (const values of capturedValues) {
+            expect(values).toContain('gap.com')
+            expect(values).toContain(15)
+        }
+
+        // Rows parse through SiteAggregateRowSchema (Date coercion, ::int).
+        expect(result.before.map(r => r.site)).toEqual([
+            'gaomon.com',
+            'gamestop.com',
+        ])
+        expect(result.after.map(r => r.site)).toEqual(['gapfactory.com'])
+        expect(result.before[0]!.last_updated).toBeInstanceOf(Date)
+        expect(result.before[0]!.coupon_count).toBe(3)
+    })
+
+    it('a base at either end of the catalog yields an empty window on that side, not an error', async () => {
+        mockRows(sql => sql.includes('site > ?'), [aggregateRow('b.com')])
+        const result = await listNeighbourStoreRows('a.com', 15)
+        expect(result.before).toEqual([])
+        expect(result.after.map(r => r.site)).toEqual(['b.com'])
+    })
+})
diff --git a/apps/caramel-app/tests/unit/sitemap.test.ts b/apps/caramel-app/tests/unit/sitemap.test.ts
index 22a84281..e343eb3f 100644
--- a/apps/caramel-app/tests/unit/sitemap.test.ts
+++ b/apps/caramel-app/tests/unit/sitemap.test.ts
@@ -52,6 +52,17 @@ function urlsOf(entries: MetadataRoute.Sitemap): string[] {
     return entries.map(e => e.url)
 }
 
+// `/coupons/<store>` entries only — the A–Z directory also lives under
+// /coupons/ (/coupons/stores, /coupons/stores/<letter>) and is pinned
+// separately below.
+function storeUrlsOf(entries: MetadataRoute.Sitemap): string[] {
+    return urlsOf(entries).filter(
+        u =>
+            u.startsWith(`${ORIGIN}/coupons/`) &&
+            !u.startsWith(`${ORIGIN}/coupons/stores`),
+    )
+}
+
 describe('sitemap.ts — static routes', () => {
     it('lists the public marketing routes including /support (monthly, 0.5) and never the auth/profile pages', async () => {
         const entries = await renderSitemap()
@@ -138,9 +149,7 @@ describe('sitemap.ts — store entries are canonical, lowercase, deduped, policy
         ])
 
         const entries = await renderSitemap()
-        const storeUrls = urlsOf(entries).filter(u =>
-            u.startsWith(`${ORIGIN}/coupons/`),
-        )
+        const storeUrls = storeUrlsOf(entries)
 
         expect(storeUrls).toEqual([
             `${ORIGIN}/coupons/brooklinen.com`,
@@ -211,7 +220,7 @@ describe('sitemap.ts — store entries are canonical, lowercase, deduped, policy
         expect(urlsOf(entries)).toContain(`${ORIGIN}/coupons/mymemory.co.uk`)
     })
 
-    it('with an empty catalog emits only the static routes', async () => {
+    it('with an empty catalog emits only the static routes — no store URLs and no directory pages', async () => {
         const entries = await renderSitemap()
         expect(
             urlsOf(entries).some(u => u.startsWith(`${ORIGIN}/coupons/`)),
@@ -219,3 +228,72 @@ describe('sitemap.ts — store entries are canonical, lowercase, deduped, policy
         expect(entries.length).toBe(6)
     })
 })
+
+describe('sitemap.ts — A–Z store directory pages', () => {
+    it('lists the directory index (weekly, 0.8) and ONLY the letter pages that have stores (weekly, 0.6), bucketed from the same collapsed entries', async () => {
+        repoMock.listStoreSitemapEntries.mockResolvedValue([
+            {
+                site: 'athleta.gap.com',
+                coupon_count: 7,
+                last_updated: d('2026-09-01T00:00:00Z'),
+            },
+            {
+                site: 'brooklinen.com',
+                coupon_count: 9,
+                last_updated: d('2026-09-05T00:00:00Z'),
+            },
+            {
+                site: '123ink.ca',
+                coupon_count: 25,
+                last_updated: d('2026-09-05T00:00:00Z'),
+            },
+            // Not stores / not indexable — must not create a letter page.
+            {
+                site: 'co.uk',
+                coupon_count: 50,
+                last_updated: d('2026-09-01T00:00:00Z'),
+            },
+            {
+                site: 'zero-codes.com',
+                coupon_count: 0,
+                last_updated: d('2026-09-01T00:00:00Z'),
+            },
+        ])
+
+        const entries = await renderSitemap()
+        const urls = urlsOf(entries)
+
+        const index = entries.find(e => e.url === `${ORIGIN}/coupons/stores`)
+        expect(index).toBeDefined()
+        expect(index?.changeFrequency).toBe('weekly')
+        expect(index?.priority).toBe(0.8)
+
+        // athleta.gap.com folds to gap.com → g; brooklinen.com → b; 123ink.ca → 0-9.
+        for (const letter of ['0-9', 'b', 'g']) {
+            const page = entries.find(
+                e => e.url === `${ORIGIN}/coupons/stores/${letter}`,
+            )
+            expect(page, `missing letter page ${letter}`).toBeDefined()
+            expect(page?.changeFrequency).toBe('weekly')
+            expect(page?.priority).toBe(0.6)
+        }
+        // co.uk is not a store and zero-codes.com is not indexable: no c / z.
+        expect(urls).not.toContain(`${ORIGIN}/coupons/stores/c`)
+        expect(urls).not.toContain(`${ORIGIN}/coupons/stores/z`)
+        // Exactly index + 3 letters.
+        expect(
+            urls.filter(u => u.startsWith(`${ORIGIN}/coupons/stores`)),
+        ).toHaveLength(4)
+        // Never a paged URL — page 2+ is noindex.
+        expect(urls.some(u => u.includes('?page='))).toBe(false)
+        // Directory pages never invent a lastModified.
+        expect(index?.lastModified).toBeUndefined()
+
+        // The store entries themselves are unchanged by the addition.
+        expect(storeUrlsOf(entries)).toEqual([
+            `${ORIGIN}/coupons/123ink.ca`,
+            `${ORIGIN}/coupons/brooklinen.com`,
+            `${ORIGIN}/coupons/gap.com`,
+        ])
+    })
+})
diff --git a/apps/caramel-app/tests/unit/storeDirectory.test.ts b/apps/caramel-app/tests/unit/storeDirectory.test.ts
new file mode 100644
index 00000000..3a850653
--- /dev/null
+++ b/apps/caramel-app/tests/unit/storeDirectory.test.ts
@@ -0,0 +1,272 @@
+import type { StoreSitemapEntry } from '@/lib/seo/sitemapStores'
+import {
+    DIRECTORY_LETTERS,
+    DIRECTORY_PAGE_SIZE,
+    NEIGHBOUR_FETCH_LIMIT,
+    NEIGHBOUR_STORE_COUNT,
+    bucketStoresByLetter,
+    directoryLetterLabel,
+    directoryLetterOf,
+    directoryPath,
+    paginateDirectoryBucket,
+    parseDirectoryLetter,
+    parseDirectoryPage,
+    pickNeighbourStores,
+} from '@/lib/seo/storeDirectory'
+import { describe, expect, it } from 'vitest'
+
+// Pins the pure half of the A–Z store directory + neighbour links
+// (src/lib/seo/storeDirectory.ts): letter bucketing, param parsing, page
+// splitting and the neighbour window collapse. No DB, no env — the fixtures
+// are the real prod slug shapes from the 2026-09-11 audit.
+
+const d = (iso: string) => new Date(iso)
+const entry = (base: string, couponCount = 1): StoreSitemapEntry => ({
+    base,
+    couponCount,
+    lastModified: d('2026-09-01T00:00:00Z'),
+})
+
+describe('directoryLetterOf / parseDirectoryLetter / directoryLetterLabel', () => {
+    it('buckets a base by its first character, digits and anything non a–z into 0-9', () => {
+        expect(directoryLetterOf('michaels.com')).toBe('m')
+        expect(directoryLetterOf('123ink.ca')).toBe('0-9')
+        expect(directoryLetterOf('1-800-flowers.com')).toBe('0-9')
+        // Defensive: resolveStoreDomain lowercases, but the bucket must not
+        // depend on it.
+        expect(directoryLetterOf('Brooklinen.com')).toBe('b')
+        expect(directoryLetterOf('xn--bcher-kva.example')).toBe('x')
+        expect(directoryLetterOf('-odd.com')).toBe('0-9')
+    })
+
+    it('accepts exactly the 27 directory letters (case-insensitively) and refuses everything else', () => {
+        expect(DIRECTORY_LETTERS).toHaveLength(27)
+        expect(DIRECTORY_LETTERS[0]).toBe('0-9')
+        for (const letter of DIRECTORY_LETTERS) {
+            expect(parseDirectoryLetter(letter)).toBe(letter)
+        }
+        expect(parseDirectoryLetter('M')).toBe('m')
+        expect(parseDirectoryLetter(' m ')).toBe('m')
+        for (const bad of [
+            '',
+            'zz',
+            '0',
+            '9',
+            '0-9x',
+            'é',
+            'stores',
+            'a.com',
+        ]) {
+            expect(parseDirectoryLetter(bad), bad).toBeNull()
+        }
+    })
+
+    it('labels letters uppercase and the digit bucket as 0–9', () => {
+        expect(directoryLetterLabel('m')).toBe('M')
+        expect(directoryLetterLabel('0-9')).toBe('0–9')
+    })
+})
+
+describe('parseDirectoryPage', () => {
+    it('absent → page 1; a positive integer literal → that page', () => {
+        expect(parseDirectoryPage(undefined)).toBe(1)
+        expect(parseDirectoryPage('1')).toBe(1)
+        expect(parseDirectoryPage('12')).toBe(12)
+    })
+
+    it('anything that is not a positive integer literal → null (the route 404s rather than guessing)', () => {
+        for (const bad of ['0', '-1', '1.5', 'abc', '', ' 2', '02', '1e3']) {
+            expect(parseDirectoryPage(bad), JSON.stringify(bad)).toBeNull()
+        }
+        expect(parseDirectoryPage(['1', '2'])).toBeNull()
+    })
+})
+
+describe('directoryPath', () => {
+    it('builds the index, letter and paged URLs from one place', () => {
+        expect(directoryPath()).toBe('/coupons/stores')
+        expect(directoryPath('m')).toBe('/coupons/stores/m')
+        expect(directoryPath('0-9')).toBe('/coupons/stores/0-9')
+        expect(directoryPath('m', 1)).toBe('/coupons/stores/m')
+        expect(directoryPath('m', 2)).toBe('/coupons/stores/m?page=2')
+    })
+})
+
+describe('bucketStoresByLetter', () => {
+    it('groups entries by letter in DIRECTORY_LETTERS order, preserves the base-sorted input order inside each bucket, and omits empty letters entirely', () => {
+        // Input is collapseStoreRows' output: already base-sorted. The
+        // bucketing is a stable partition of that order, not a re-sort.
+        const buckets = bucketStoresByLetter([
+            entry('123ink.ca'),
+            entry('barkevs.com'),
+            entry('bobstores.com'),
+            entry('brooklinen.com'),
+            entry('michaels.com', 12),
+        ])
+        expect(buckets.map(b => b.letter)).toEqual(['0-9', 'b', 'm'])
+        expect(buckets[1]!.stores.map(s => s.base)).toEqual([
+            'barkevs.com',
+            'bobstores.com',
+            'brooklinen.com',
+        ])
+        expect(buckets[2]!.stores).toEqual([entry('michaels.com', 12)])
+        // A letter with no stores is not a bucket (the route 404s it, the
+        // sitemap and strips never link it).
+        expect(buckets.find(b => b.letter === 'a')).toBeUndefined()
+    })
+
+    it('an empty catalog yields no buckets', () => {
+        expect(bucketStoresByLetter([])).toEqual([])
+    })
+})
+
+describe('paginateDirectoryBucket', () => {
+    const many = Array.from({ length: DIRECTORY_PAGE_SIZE + 1 }, (_, i) =>
+        entry(`b${String(i).padStart(4, '0')}.com`),
+    )
+
+    it('a bucket within DIRECTORY_PAGE_SIZE is one page holding everything', () => {
+        const page = paginateDirectoryBucket(
+            [entry('a.com'), entry('b.com')],
+            1,
+        )
+        expect(page).toEqual({
+            page: 1,
+            pageCount: 1,
+            stores: [entry('a.com'), entry('b.com')],
+        })
+    })
+
+    it('one store past the cap splits into two pages; page 2 holds the remainder', () => {
+        const first = paginateDirectoryBucket(many, 1)!
+        const second = paginateDirectoryBucket(many, 2)!
+        expect(first.pageCount).toBe(2)
+        expect(first.stores).toHaveLength(DIRECTORY_PAGE_SIZE)
+        expect(second.stores).toHaveLength(1)
+        expect(second.stores[0]!.base).toBe('b0500.com')
+        // No overlap, nothing lost.
+        expect([...first.stores, ...second.stores]).toEqual(many)
+    })
+
+    it('an out-of-range page, page 0, a non-integer page, or ANY page of an empty bucket → null (404, never an empty page)', () => {
+        expect(paginateDirectoryBucket(many, 3)).toBeNull()
+        expect(paginateDirectoryBucket(many, 0)).toBeNull()
+        expect(paginateDirectoryBucket(many, 1.5)).toBeNull()
+        expect(paginateDirectoryBucket([], 1)).toBeNull()
+    })
+
+    it('honours an explicit page size', () => {
+        const page = paginateDirectoryBucket(many.slice(0, 5), 2, 2)!
+        expect(page.pageCount).toBe(3)
+        expect(page.stores.map(s => s.base)).toEqual(['b0002.com', 'b0003.com'])
+    })
+})
+
+describe('pickNeighbourStores', () => {
+    const row = (site: string, coupon_count = 3) => ({
+        site,
+        coupon_count,
+        last_updated: d('2026-09-01T00:00:00Z'),
+    })
+
+    it('over-fetches 3× the neighbour count so subdomain folds cannot starve a side', () => {
+        expect(NEIGHBOUR_STORE_COUNT).toBe(5)
+        expect(NEIGHBOUR_FETCH_LIMIT).toBe(15)
+    })
+
+    it('collapses each window to canonical bases, drops the current base and its own subdomain rows, keeps the nearest N per side, both ascending', () => {
+        // Raw `site < 'gap.com' ORDER BY site DESC` window (nearest first),
+        // as the repo returns it: includes a subdomain of the current store
+        // (folds into gap.com → dropped) and a mixed-case twin pair.
+        const before = [
+            row('gaomon.com'),
+            row('gamestop.com'),
+            row('galaxus.ch'),
+            row('g2a.com'),
+            row('fye.com'),
+            row('fujifilm.com'),
+            row('freshly.com'),
+            row('athleta.gap.com', 7),
+        ]
+        // Raw `site > 'gap.com' ORDER BY site ASC` window.
+        const after = [
+            row('gapfactory.com'),
+            row('garmin.com'),
+            row('gettyimages.com'),
+            row('ghostbed.com'),
+            row('giftcards.com'),
+            row('glossier.com'),
+            row('godaddy.com'),
+            row('bananarepublic.gap.com', 4),
+        ]
+
+        const { previous, next } = pickNeighbourStores(
+            { before, after },
+            'gap.com',
+            5,
+        )
+        expect(previous.map(e => e.base)).toEqual([
+            'fye.com',
+            'g2a.com',
+            'galaxus.ch',
+            'gamestop.com',
+            'gaomon.com',
+        ])
+        expect(next.map(e => e.base)).toEqual([
+            'gapfactory.com',
+            'garmin.com',
+            'gettyimages.com',
+            'ghostbed.com',
+            'giftcards.com',
+        ])
+        // Nearest-N: gaomon.com (adjacent) is in; fujifilm.com (6th nearest)
+        // and freshly.com (7th) are out on the previous side.
+        expect(previous.map(e => e.base)).not.toContain('fujifilm.com')
+        expect(previous.map(e => e.base)).not.toContain('freshly.com')
+        expect([...previous, ...next].some(e => e.base === 'gap.com')).toBe(
+            false,
+        )
+    })
+
+    it('a raw slug in one window that folds into a base already taken by the other side is not linked twice', () => {
+        const { previous, next } = pickNeighbourStores(
+            {
+                before: [row('roborock.com')],
+                after: [row('us.roborock.com'), row('rockauto.com')],
+            },
+            'robot-store.com',
+            5,
+        )
+        expect(previous.map(e => e.base)).toEqual(['roborock.com'])
+        expect(next.map(e => e.base)).toEqual(['rockauto.com'])
+    })
+
+    it('carries the real coupon count through (summed across folded slugs) and never links a zero-count or non-store row', () => {
+        const { next } = pickNeighbourStores(
+            {
+                before: [],
+                after: [
+                    row('athleta.gap.com', 7),
+                    row('gap.com', 30),
+                    row('zero.com', 0),
+                    row('co.uk', 50),
+                ],
+            },
+            'fye.com',
+            5,
+        )
+        expect(next).toEqual([
+            {
+                base: 'gap.com',
+                couponCount: 37,
+                lastModified: d('2026-09-01T00:00:00Z'),
+            },
+        ])
+    })
+
+    it('both windows empty (a one-store catalog) → no neighbours, no throw', () => {
+        expect(
+            pickNeighbourStores({ before: [], after: [] }, 'only.com'),
+        ).toEqual({ previous: [], next: [] })
+    })
+})
diff --git a/apps/caramel-app/tests/unit/storeDirectoryCache.test.ts b/apps/caramel-app/tests/unit/storeDirectoryCache.test.ts
new file mode 100644
index 00000000..6f060604
--- /dev/null
+++ b/apps/caramel-app/tests/unit/storeDirectoryCache.test.ts
@@ -0,0 +1,86 @@
+import {
+    STORE_DIRECTORY_TTL_MS,
+    getStoreDirectoryEntries,
+    resetStoreDirectoryCache,
+} from '@/lib/seo/storeDirectoryCache'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Pins src/lib/seo/storeDirectoryCache.ts: ONE sitemap-identical read
+// (listStoreSitemapEntries under the shared 5000 cap → collapseStoreRows)
+// cached per process for 5 minutes, in-flight de-duplicated, stale-on-error.
+// The repo boundary is mocked so no SQL runs; the collapse is the real one.
+
+const { repoMock } = vi.hoisted(() => ({
+    repoMock: { listStoreSitemapEntries: vi.fn() },
+}))
+vi.mock('@/lib/couponsRepo', () => repoMock)
+
+const d = (iso: string) => new Date(iso)
+const ROWS = [
+    { site: 'athleta.gap.com', coupon_count: 7, last_updated: d('2026-09-01') },
+    { site: 'gap.com', coupon_count: 30, last_updated: d('2026-08-15') },
+    { site: 'co.uk', coupon_count: 50, last_updated: d('2026-09-01') },
+]
+
+beforeEach(() => {
+    resetStoreDirectoryCache()
+    repoMock.listStoreSitemapEntries.mockReset()
+    repoMock.listStoreSitemapEntries.mockResolvedValue(ROWS)
+})
+
+describe('getStoreDirectoryEntries', () => {
+    it('reads the sitemap window (5000 grouped rows) and returns the collapsed, policy-gated, base-sorted entries', async () => {
+        const entries = await getStoreDirectoryEntries()
+        expect(repoMock.listStoreSitemapEntries).toHaveBeenCalledWith(5000)
+        expect(entries).toEqual([
+            { base: 'gap.com', couponCount: 37, lastModified: d('2026-09-01') },
+        ])
+    })
+
+    it('serves from memory within the TTL and rebuilds once it has expired', async () => {
+        const t0 = 1_000_000
+        const first = await getStoreDirectoryEntries(t0)
+        const warm = await getStoreDirectoryEntries(
+            t0 + STORE_DIRECTORY_TTL_MS - 1,
+        )
+        expect(warm).toBe(first)
+        expect(repoMock.listStoreSitemapEntries).toHaveBeenCalledTimes(1)
+
+        repoMock.listStoreSitemapEntries.mockResolvedValue([
+            {
+                site: 'nike.com',
+                coupon_count: 2,
+                last_updated: d('2026-09-02'),
+            },
+        ])
+        // builtAt is Date.now() of the build, so expire relative to that.
+        const expired = await getStoreDirectoryEntries(
+            Date.now() + STORE_DIRECTORY_TTL_MS + 1,
+        )
+        expect(repoMock.listStoreSitemapEntries).toHaveBeenCalledTimes(2)
+        expect(expired.map(e => e.base)).toEqual(['nike.com'])
+    })
+
+    it('concurrent cold callers share ONE build (no stampede)', async () => {
+        const [a, b, c] = await Promise.all([
+            getStoreDirectoryEntries(),
+            getStoreDirectoryEntries(),
+            getStoreDirectoryEntries(),
+        ])
+        expect(repoMock.listStoreSitemapEntries).toHaveBeenCalledTimes(1)
+        expect(a).toBe(b)
+        expect(b).toBe(c)
+    })
+
+    it('a failed rebuild keeps serving the previous entries; a failed COLD build throws', async () => {
+        const warm = await getStoreDirectoryEntries(0)
+        repoMock.listStoreSitemapEntries.mockRejectedValue(new Error('pg down'))
+        const stale = await getStoreDirectoryEntries(
+            Date.now() + STORE_DIRECTORY_TTL_MS + 1,
+        )
+        expect(stale).toBe(warm)
+
+        resetStoreDirectoryCache()
+        await expect(getStoreDirectoryEntries()).rejects.toThrow('pg down')
+    })
+})