docs(og): gate the OG card URL's dotted final segment, and name the coupling on both sides

.github/workflows/lint.yml

@@ -1460,12 +1460,23 @@ jobs:
  # every type still checks, every link still resolves. The only symptom is
  # a 200 where a 404 belongs, on URLs no test requests.
  #
+ # The same matcher rule holds up a SECOND surface, gated by the same
+ # script: `lib/source.ts`'s `getPageImage()` appends an `image.png` marker
+ # to every Open Graph card URL, and that marker's DOT is the only reason
+ # `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...` (not a
+ # route -- `app/og/` is top-level, not under `app/[lang]/`). Measured:
+ # `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200, so the
+ # marker's NAME is free and its dot is not. Rename it to anything dotless
+ # and every `og:image` on the site 404s at once; nothing fetches those
+ # URLs, so it is the same silent shape as the catch-all above.
+ #
  # Runs its own --self-test first (via the pnpm script). Not ceremony: the
  # live tree is green by construction after the fix, so a passing run over
  # real data cannot distinguish a working gate from one that approves
- # everything. The self-test is where every limb is observed failing, and
- # where the proxy condition is observed flipping the requirement off.
- - name: Docs locale catch-all rejects non-locale segments
+ # everything. The self-test is where every limb is observed failing --
+ # including the OG marker stripped of its dot -- and where the proxy
+ # condition is observed flipping the catch-all requirement off.
+ - name: Docs locale catch-all and OG card URL dot invariant
  run: pnpm check:docs-locale-catch-all
 
  # #11050 route spellings taught in prose: every /api/v1 wire-path

apps/docs/lib/source.ts

@@ -15,6 +15,31 @@ export const blog = loader({
  source: blogCollection.toFumadocsSource(),
 });
 
+/**
+ * The Open Graph card URL for a page: `/og/docs/<...page.slugs>/image.png`.
+ *
+ * The trailing `image.png` marker is load-bearing TWICE, and only the first is
+ * visible from this file:
+ *
+ * 1. `app/og/docs/[...slug]/route.tsx` resolves the page with
+ * `source.getPage(slug.slice(0, -1))` -- the marker is the sacrificial
+ * segment that slice discards. Its NAME does not matter to that.
+ * 2. Its DOT is what keeps this URL out of the locale rewriter. The matcher in
+ * `apps/docs/proxy.ts` excludes any path containing a dot, so a dotted final
+ * segment skips the proxy and reaches the route above. A marker WITHOUT a
+ * dot is rewritten to `/en/og/docs/...`, which is not a route at all --
+ * `app/og/` is top-level, not under `app/[lang]/`.
+ *
+ * Measured: `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200. So
+ * the marker's name is free; the presence of a dot is everything. Rename it to
+ * anything dotless -- or widen the proxy matcher on the other side -- and every
+ * `og:image` on the site 404s at once, which is worse than emitting none
+ * (crawlers fall back to scraping whatever else the page offers). Nothing
+ * fetches these URLs, so no test, type or link check would notice.
+ *
+ * `pnpm check:docs-locale-catch-all` gates the dot from here; the matcher half
+ * is commented on in `apps/docs/proxy.ts`.
+ */
 export function getPageImage(page: InferPageType<typeof source>) {
  const segments = [...page.slugs, 'image.png'];
 

apps/docs/proxy.ts

@@ -108,5 +108,23 @@ export const config = {
  // - Next.js static files (/_next/static/*)
  // - Next.js image optimization (/_next/image/*)
  // - Favicon and other static assets
+ //
+ // The `.*\..*` limb -- exclude any path containing a DOT -- is load-bearing
+ // for two surfaces beyond static assets, and neither is visible from here:
+ //
+ // - `apps/docs/lib/source.ts`'s `getPageImage()` appends an `image.png`
+ // marker to every Open Graph card URL. That marker's dot is the ONLY reason
+ // `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...`, which
+ // is not a route -- the `app/og/` tree is top-level, not under
+ // `app/[lang]/`. Widening this pattern 404s every `og:image` on the site at
+ // once, and nothing fetches those URLs, so the break is silent. Already
+ // ruled out as a surface to widen for the same reason from the other end:
+ // it would also 404 `/llms.txt`, `/llms-full.txt`, `/og/**` and
+ // `/docs/**.mdx`.
+ // - Conversely, BECAUSE dotted paths skip this proxy they reach `app/[lang]/`
+ // with `lang` set to the literal segment (`robots.txt`, `ads.txt`), which is
+ // why `apps/docs/lib/i18n.ts` carries the `isSupportedLanguage` guard.
+ //
+ // `pnpm check:docs-locale-catch-all` gates both halves.
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)'],
 };

.github/workflows/lint.yml

@@ -1460,12 +1460,23 @@ jobs:
  # every type still checks, every link still resolves. The only symptom is
  # a 200 where a 404 belongs, on URLs no test requests.
  #
+ # The same matcher rule holds up a SECOND surface, gated by the same
+ # script: `lib/source.ts`'s `getPageImage()` appends an `image.png` marker
+ # to every Open Graph card URL, and that marker's DOT is the only reason
+ # `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...` (not a
+ # route -- `app/og/` is top-level, not under `app/[lang]/`). Measured:
+ # `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200, so the
+ # marker's NAME is free and its dot is not. Rename it to anything dotless
+ # and every `og:image` on the site 404s at once; nothing fetches those
+ # URLs, so it is the same silent shape as the catch-all above.
+ #
  # Runs its own --self-test first (via the pnpm script). Not ceremony: the
  # live tree is green by construction after the fix, so a passing run over
  # real data cannot distinguish a working gate from one that approves
- # everything. The self-test is where every limb is observed failing, and
- # where the proxy condition is observed flipping the requirement off.
- - name: Docs locale catch-all rejects non-locale segments
+ # everything. The self-test is where every limb is observed failing --
+ # including the OG marker stripped of its dot -- and where the proxy
+ # condition is observed flipping the catch-all requirement off.
+ - name: Docs locale catch-all and OG card URL dot invariant
  run: pnpm check:docs-locale-catch-all
 
  # #11050 route spellings taught in prose: every /api/v1 wire-path

apps/docs/lib/source.ts

@@ -15,6 +15,31 @@ export const blog = loader({
  source: blogCollection.toFumadocsSource(),
 });
 
+/**
+ * The Open Graph card URL for a page: `/og/docs/<...page.slugs>/image.png`.
+ *
+ * The trailing `image.png` marker is load-bearing TWICE, and only the first is
+ * visible from this file:
+ *
+ * 1. `app/og/docs/[...slug]/route.tsx` resolves the page with
+ * `source.getPage(slug.slice(0, -1))` -- the marker is the sacrificial
+ * segment that slice discards. Its NAME does not matter to that.
+ * 2. Its DOT is what keeps this URL out of the locale rewriter. The matcher in
+ * `apps/docs/proxy.ts` excludes any path containing a dot, so a dotted final
+ * segment skips the proxy and reaches the route above. A marker WITHOUT a
+ * dot is rewritten to `/en/og/docs/...`, which is not a route at all --
+ * `app/og/` is top-level, not under `app/[lang]/`.
+ *
+ * Measured: `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200. So
+ * the marker's name is free; the presence of a dot is everything. Rename it to
+ * anything dotless -- or widen the proxy matcher on the other side -- and every
+ * `og:image` on the site 404s at once, which is worse than emitting none
+ * (crawlers fall back to scraping whatever else the page offers). Nothing
+ * fetches these URLs, so no test, type or link check would notice.
+ *
+ * `pnpm check:docs-locale-catch-all` gates the dot from here; the matcher half
+ * is commented on in `apps/docs/proxy.ts`.
+ */
 export function getPageImage(page: InferPageType<typeof source>) {
  const segments = [...page.slugs, 'image.png'];
 

apps/docs/proxy.ts

@@ -108,5 +108,23 @@ export const config = {
  // - Next.js static files (/_next/static/*)
  // - Next.js image optimization (/_next/image/*)
  // - Favicon and other static assets
+ //
+ // The `.*\..*` limb -- exclude any path containing a DOT -- is load-bearing
+ // for two surfaces beyond static assets, and neither is visible from here:
+ //
+ // - `apps/docs/lib/source.ts`'s `getPageImage()` appends an `image.png`
+ // marker to every Open Graph card URL. That marker's dot is the ONLY reason
+ // `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...`, which
+ // is not a route -- the `app/og/` tree is top-level, not under
+ // `app/[lang]/`. Widening this pattern 404s every `og:image` on the site at
+ // once, and nothing fetches those URLs, so the break is silent. Already
+ // ruled out as a surface to widen for the same reason from the other end:
+ // it would also 404 `/llms.txt`, `/llms-full.txt`, `/og/**` and
+ // `/docs/**.mdx`.
+ // - Conversely, BECAUSE dotted paths skip this proxy they reach `app/[lang]/`
+ // with `lang` set to the literal segment (`robots.txt`, `ads.txt`), which is
+ // why `apps/docs/lib/i18n.ts` carries the `isSupportedLanguage` guard.
+ //
+ // `pnpm check:docs-locale-catch-all` gates both halves.
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)'],
 };

.github/workflows/lint.yml

@@ -1460,12 +1460,23 @@ jobs:
  # every type still checks, every link still resolves. The only symptom is
  # a 200 where a 404 belongs, on URLs no test requests.
  #
+ # The same matcher rule holds up a SECOND surface, gated by the same
+ # script: `lib/source.ts`'s `getPageImage()` appends an `image.png` marker
+ # to every Open Graph card URL, and that marker's DOT is the only reason
+ # `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...` (not a
+ # route -- `app/og/` is top-level, not under `app/[lang]/`). Measured:
+ # `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200, so the
+ # marker's NAME is free and its dot is not. Rename it to anything dotless
+ # and every `og:image` on the site 404s at once; nothing fetches those
+ # URLs, so it is the same silent shape as the catch-all above.
+ #
  # Runs its own --self-test first (via the pnpm script). Not ceremony: the
  # live tree is green by construction after the fix, so a passing run over
  # real data cannot distinguish a working gate from one that approves
- # everything. The self-test is where every limb is observed failing, and
- # where the proxy condition is observed flipping the requirement off.
- - name: Docs locale catch-all rejects non-locale segments
+ # everything. The self-test is where every limb is observed failing --
+ # including the OG marker stripped of its dot -- and where the proxy
+ # condition is observed flipping the catch-all requirement off.
+ - name: Docs locale catch-all and OG card URL dot invariant
  run: pnpm check:docs-locale-catch-all
 
  # #11050 route spellings taught in prose: every /api/v1 wire-path

apps/docs/lib/source.ts

@@ -15,6 +15,31 @@ export const blog = loader({
  source: blogCollection.toFumadocsSource(),
 });
 
+/**
+ * The Open Graph card URL for a page: `/og/docs/<...page.slugs>/image.png`.
+ *
+ * The trailing `image.png` marker is load-bearing TWICE, and only the first is
+ * visible from this file:
+ *
+ * 1. `app/og/docs/[...slug]/route.tsx` resolves the page with
+ * `source.getPage(slug.slice(0, -1))` -- the marker is the sacrificial
+ * segment that slice discards. Its NAME does not matter to that.
+ * 2. Its DOT is what keeps this URL out of the locale rewriter. The matcher in
+ * `apps/docs/proxy.ts` excludes any path containing a dot, so a dotted final
+ * segment skips the proxy and reaches the route above. A marker WITHOUT a
+ * dot is rewritten to `/en/og/docs/...`, which is not a route at all --
+ * `app/og/` is top-level, not under `app/[lang]/`.
+ *
+ * Measured: `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200. So
+ * the marker's name is free; the presence of a dot is everything. Rename it to
+ * anything dotless -- or widen the proxy matcher on the other side -- and every
+ * `og:image` on the site 404s at once, which is worse than emitting none
+ * (crawlers fall back to scraping whatever else the page offers). Nothing
+ * fetches these URLs, so no test, type or link check would notice.
+ *
+ * `pnpm check:docs-locale-catch-all` gates the dot from here; the matcher half
+ * is commented on in `apps/docs/proxy.ts`.
+ */
 export function getPageImage(page: InferPageType<typeof source>) {
  const segments = [...page.slugs, 'image.png'];
 

apps/docs/proxy.ts

@@ -108,5 +108,23 @@ export const config = {
  // - Next.js static files (/_next/static/*)
  // - Next.js image optimization (/_next/image/*)
  // - Favicon and other static assets
+ //
+ // The `.*\..*` limb -- exclude any path containing a DOT -- is load-bearing
+ // for two surfaces beyond static assets, and neither is visible from here:
+ //
+ // - `apps/docs/lib/source.ts`'s `getPageImage()` appends an `image.png`
+ // marker to every Open Graph card URL. That marker's dot is the ONLY reason
+ // `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...`, which
+ // is not a route -- the `app/og/` tree is top-level, not under
+ // `app/[lang]/`. Widening this pattern 404s every `og:image` on the site at
+ // once, and nothing fetches those URLs, so the break is silent. Already
+ // ruled out as a surface to widen for the same reason from the other end:
+ // it would also 404 `/llms.txt`, `/llms-full.txt`, `/og/**` and
+ // `/docs/**.mdx`.
+ // - Conversely, BECAUSE dotted paths skip this proxy they reach `app/[lang]/`
+ // with `lang` set to the literal segment (`robots.txt`, `ads.txt`), which is
+ // why `apps/docs/lib/i18n.ts` carries the `isSupportedLanguage` guard.
+ //
+ // `pnpm check:docs-locale-catch-all` gates both halves.
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)'],
 };

.github/workflows/lint.yml

@@ -1460,12 +1460,23 @@ jobs:
  # every type still checks, every link still resolves. The only symptom is
  # a 200 where a 404 belongs, on URLs no test requests.
  #
+ # The same matcher rule holds up a SECOND surface, gated by the same
+ # script: `lib/source.ts`'s `getPageImage()` appends an `image.png` marker
+ # to every Open Graph card URL, and that marker's DOT is the only reason
+ # `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...` (not a
+ # route -- `app/og/` is top-level, not under `app/[lang]/`). Measured:
+ # `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200, so the
+ # marker's NAME is free and its dot is not. Rename it to anything dotless
+ # and every `og:image` on the site 404s at once; nothing fetches those
+ # URLs, so it is the same silent shape as the catch-all above.
+ #
  # Runs its own --self-test first (via the pnpm script). Not ceremony: the
  # live tree is green by construction after the fix, so a passing run over
  # real data cannot distinguish a working gate from one that approves
- # everything. The self-test is where every limb is observed failing, and
- # where the proxy condition is observed flipping the requirement off.
- - name: Docs locale catch-all rejects non-locale segments
+ # everything. The self-test is where every limb is observed failing --
+ # including the OG marker stripped of its dot -- and where the proxy
+ # condition is observed flipping the catch-all requirement off.
+ - name: Docs locale catch-all and OG card URL dot invariant
  run: pnpm check:docs-locale-catch-all
 
  # #11050 route spellings taught in prose: every /api/v1 wire-path

apps/docs/lib/source.ts

@@ -15,6 +15,31 @@ export const blog = loader({
  source: blogCollection.toFumadocsSource(),
 });
 
+/**
+ * The Open Graph card URL for a page: `/og/docs/<...page.slugs>/image.png`.
+ *
+ * The trailing `image.png` marker is load-bearing TWICE, and only the first is
+ * visible from this file:
+ *
+ * 1. `app/og/docs/[...slug]/route.tsx` resolves the page with
+ * `source.getPage(slug.slice(0, -1))` -- the marker is the sacrificial
+ * segment that slice discards. Its NAME does not matter to that.
+ * 2. Its DOT is what keeps this URL out of the locale rewriter. The matcher in
+ * `apps/docs/proxy.ts` excludes any path containing a dot, so a dotted final
+ * segment skips the proxy and reaches the route above. A marker WITHOUT a
+ * dot is rewritten to `/en/og/docs/...`, which is not a route at all --
+ * `app/og/` is top-level, not under `app/[lang]/`.
+ *
+ * Measured: `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200. So
+ * the marker's name is free; the presence of a dot is everything. Rename it to
+ * anything dotless -- or widen the proxy matcher on the other side -- and every
+ * `og:image` on the site 404s at once, which is worse than emitting none
+ * (crawlers fall back to scraping whatever else the page offers). Nothing
+ * fetches these URLs, so no test, type or link check would notice.
+ *
+ * `pnpm check:docs-locale-catch-all` gates the dot from here; the matcher half
+ * is commented on in `apps/docs/proxy.ts`.
+ */
 export function getPageImage(page: InferPageType<typeof source>) {
  const segments = [...page.slugs, 'image.png'];
 

apps/docs/proxy.ts

@@ -108,5 +108,23 @@ export const config = {
  // - Next.js static files (/_next/static/*)
  // - Next.js image optimization (/_next/image/*)
  // - Favicon and other static assets
+ //
+ // The `.*\..*` limb -- exclude any path containing a DOT -- is load-bearing
+ // for two surfaces beyond static assets, and neither is visible from here:
+ //
+ // - `apps/docs/lib/source.ts`'s `getPageImage()` appends an `image.png`
+ // marker to every Open Graph card URL. That marker's dot is the ONLY reason
+ // `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...`, which
+ // is not a route -- the `app/og/` tree is top-level, not under
+ // `app/[lang]/`. Widening this pattern 404s every `og:image` on the site at
+ // once, and nothing fetches those URLs, so the break is silent. Already
+ // ruled out as a surface to widen for the same reason from the other end:
+ // it would also 404 `/llms.txt`, `/llms-full.txt`, `/og/**` and
+ // `/docs/**.mdx`.
+ // - Conversely, BECAUSE dotted paths skip this proxy they reach `app/[lang]/`
+ // with `lang` set to the literal segment (`robots.txt`, `ads.txt`), which is
+ // why `apps/docs/lib/i18n.ts` carries the `isSupportedLanguage` guard.
+ //
+ // `pnpm check:docs-locale-catch-all` gates both halves.
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)'],
 };

.github/workflows/lint.yml

@@ -1460,12 +1460,23 @@ jobs:
  # every type still checks, every link still resolves. The only symptom is
  # a 200 where a 404 belongs, on URLs no test requests.
  #
+ # The same matcher rule holds up a SECOND surface, gated by the same
+ # script: `lib/source.ts`'s `getPageImage()` appends an `image.png` marker
+ # to every Open Graph card URL, and that marker's DOT is the only reason
+ # `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...` (not a
+ # route -- `app/og/` is top-level, not under `app/[lang]/`). Measured:
+ # `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200, so the
+ # marker's NAME is free and its dot is not. Rename it to anything dotless
+ # and every `og:image` on the site 404s at once; nothing fetches those
+ # URLs, so it is the same silent shape as the catch-all above.
+ #
  # Runs its own --self-test first (via the pnpm script). Not ceremony: the
  # live tree is green by construction after the fix, so a passing run over
  # real data cannot distinguish a working gate from one that approves
- # everything. The self-test is where every limb is observed failing, and
- # where the proxy condition is observed flipping the requirement off.
- - name: Docs locale catch-all rejects non-locale segments
+ # everything. The self-test is where every limb is observed failing --
+ # including the OG marker stripped of its dot -- and where the proxy
+ # condition is observed flipping the catch-all requirement off.
+ - name: Docs locale catch-all and OG card URL dot invariant
  run: pnpm check:docs-locale-catch-all
 
  # #11050 route spellings taught in prose: every /api/v1 wire-path

apps/docs/lib/source.ts

@@ -15,6 +15,31 @@ export const blog = loader({
  source: blogCollection.toFumadocsSource(),
 });
 
+/**
+ * The Open Graph card URL for a page: `/og/docs/<...page.slugs>/image.png`.
+ *
+ * The trailing `image.png` marker is load-bearing TWICE, and only the first is
+ * visible from this file:
+ *
+ * 1. `app/og/docs/[...slug]/route.tsx` resolves the page with
+ * `source.getPage(slug.slice(0, -1))` -- the marker is the sacrificial
+ * segment that slice discards. Its NAME does not matter to that.
+ * 2. Its DOT is what keeps this URL out of the locale rewriter. The matcher in
+ * `apps/docs/proxy.ts` excludes any path containing a dot, so a dotted final
+ * segment skips the proxy and reaches the route above. A marker WITHOUT a
+ * dot is rewritten to `/en/og/docs/...`, which is not a route at all --
+ * `app/og/` is top-level, not under `app/[lang]/`.
+ *
+ * Measured: `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200. So
+ * the marker's name is free; the presence of a dot is everything. Rename it to
+ * anything dotless -- or widen the proxy matcher on the other side -- and every
+ * `og:image` on the site 404s at once, which is worse than emitting none
+ * (crawlers fall back to scraping whatever else the page offers). Nothing
+ * fetches these URLs, so no test, type or link check would notice.
+ *
+ * `pnpm check:docs-locale-catch-all` gates the dot from here; the matcher half
+ * is commented on in `apps/docs/proxy.ts`.
+ */
 export function getPageImage(page: InferPageType<typeof source>) {
  const segments = [...page.slugs, 'image.png'];
 

apps/docs/proxy.ts

@@ -108,5 +108,23 @@ export const config = {
  // - Next.js static files (/_next/static/*)
  // - Next.js image optimization (/_next/image/*)
  // - Favicon and other static assets
+ //
+ // The `.*\..*` limb -- exclude any path containing a DOT -- is load-bearing
+ // for two surfaces beyond static assets, and neither is visible from here:
+ //
+ // - `apps/docs/lib/source.ts`'s `getPageImage()` appends an `image.png`
+ // marker to every Open Graph card URL. That marker's dot is the ONLY reason
+ // `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...`, which
+ // is not a route -- the `app/og/` tree is top-level, not under
+ // `app/[lang]/`. Widening this pattern 404s every `og:image` on the site at
+ // once, and nothing fetches those URLs, so the break is silent. Already
+ // ruled out as a surface to widen for the same reason from the other end:
+ // it would also 404 `/llms.txt`, `/llms-full.txt`, `/og/**` and
+ // `/docs/**.mdx`.
+ // - Conversely, BECAUSE dotted paths skip this proxy they reach `app/[lang]/`
+ // with `lang` set to the literal segment (`robots.txt`, `ads.txt`), which is
+ // why `apps/docs/lib/i18n.ts` carries the `isSupportedLanguage` guard.
+ //
+ // `pnpm check:docs-locale-catch-all` gates both halves.
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)'],
 };

.github/workflows/lint.yml

@@ -1460,12 +1460,23 @@ jobs:
  # every type still checks, every link still resolves. The only symptom is
  # a 200 where a 404 belongs, on URLs no test requests.
  #
+ # The same matcher rule holds up a SECOND surface, gated by the same
+ # script: `lib/source.ts`'s `getPageImage()` appends an `image.png` marker
+ # to every Open Graph card URL, and that marker's DOT is the only reason
+ # `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...` (not a
+ # route -- `app/og/` is top-level, not under `app/[lang]/`). Measured:
+ # `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200, so the
+ # marker's NAME is free and its dot is not. Rename it to anything dotless
+ # and every `og:image` on the site 404s at once; nothing fetches those
+ # URLs, so it is the same silent shape as the catch-all above.
+ #
  # Runs its own --self-test first (via the pnpm script). Not ceremony: the
  # live tree is green by construction after the fix, so a passing run over
  # real data cannot distinguish a working gate from one that approves
- # everything. The self-test is where every limb is observed failing, and
- # where the proxy condition is observed flipping the requirement off.
- - name: Docs locale catch-all rejects non-locale segments
+ # everything. The self-test is where every limb is observed failing --
+ # including the OG marker stripped of its dot -- and where the proxy
+ # condition is observed flipping the catch-all requirement off.
+ - name: Docs locale catch-all and OG card URL dot invariant
  run: pnpm check:docs-locale-catch-all
 
  # #11050 route spellings taught in prose: every /api/v1 wire-path

apps/docs/lib/source.ts

@@ -15,6 +15,31 @@ export const blog = loader({
  source: blogCollection.toFumadocsSource(),
 });
 
+/**
+ * The Open Graph card URL for a page: `/og/docs/<...page.slugs>/image.png`.
+ *
+ * The trailing `image.png` marker is load-bearing TWICE, and only the first is
+ * visible from this file:
+ *
+ * 1. `app/og/docs/[...slug]/route.tsx` resolves the page with
+ * `source.getPage(slug.slice(0, -1))` -- the marker is the sacrificial
+ * segment that slice discards. Its NAME does not matter to that.
+ * 2. Its DOT is what keeps this URL out of the locale rewriter. The matcher in
+ * `apps/docs/proxy.ts` excludes any path containing a dot, so a dotted final
+ * segment skips the proxy and reaches the route above. A marker WITHOUT a
+ * dot is rewritten to `/en/og/docs/...`, which is not a route at all --
+ * `app/og/` is top-level, not under `app/[lang]/`.
+ *
+ * Measured: `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200. So
+ * the marker's name is free; the presence of a dot is everything. Rename it to
+ * anything dotless -- or widen the proxy matcher on the other side -- and every
+ * `og:image` on the site 404s at once, which is worse than emitting none
+ * (crawlers fall back to scraping whatever else the page offers). Nothing
+ * fetches these URLs, so no test, type or link check would notice.
+ *
+ * `pnpm check:docs-locale-catch-all` gates the dot from here; the matcher half
+ * is commented on in `apps/docs/proxy.ts`.
+ */
 export function getPageImage(page: InferPageType<typeof source>) {
  const segments = [...page.slugs, 'image.png'];
 

apps/docs/proxy.ts

@@ -108,5 +108,23 @@ export const config = {
  // - Next.js static files (/_next/static/*)
  // - Next.js image optimization (/_next/image/*)
  // - Favicon and other static assets
+ //
+ // The `.*\..*` limb -- exclude any path containing a DOT -- is load-bearing
+ // for two surfaces beyond static assets, and neither is visible from here:
+ //
+ // - `apps/docs/lib/source.ts`'s `getPageImage()` appends an `image.png`
+ // marker to every Open Graph card URL. That marker's dot is the ONLY reason
+ // `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...`, which
+ // is not a route -- the `app/og/` tree is top-level, not under
+ // `app/[lang]/`. Widening this pattern 404s every `og:image` on the site at
+ // once, and nothing fetches those URLs, so the break is silent. Already
+ // ruled out as a surface to widen for the same reason from the other end:
+ // it would also 404 `/llms.txt`, `/llms-full.txt`, `/og/**` and
+ // `/docs/**.mdx`.
+ // - Conversely, BECAUSE dotted paths skip this proxy they reach `app/[lang]/`
+ // with `lang` set to the literal segment (`robots.txt`, `ads.txt`), which is
+ // why `apps/docs/lib/i18n.ts` carries the `isSupportedLanguage` guard.
+ //
+ // `pnpm check:docs-locale-catch-all` gates both halves.
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)'],
 };

.github/workflows/lint.yml

@@ -1460,12 +1460,23 @@ jobs:
  # every type still checks, every link still resolves. The only symptom is
  # a 200 where a 404 belongs, on URLs no test requests.
  #
+ # The same matcher rule holds up a SECOND surface, gated by the same
+ # script: `lib/source.ts`'s `getPageImage()` appends an `image.png` marker
+ # to every Open Graph card URL, and that marker's DOT is the only reason
+ # `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...` (not a
+ # route -- `app/og/` is top-level, not under `app/[lang]/`). Measured:
+ # `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200, so the
+ # marker's NAME is free and its dot is not. Rename it to anything dotless
+ # and every `og:image` on the site 404s at once; nothing fetches those
+ # URLs, so it is the same silent shape as the catch-all above.
+ #
  # Runs its own --self-test first (via the pnpm script). Not ceremony: the
  # live tree is green by construction after the fix, so a passing run over
  # real data cannot distinguish a working gate from one that approves
- # everything. The self-test is where every limb is observed failing, and
- # where the proxy condition is observed flipping the requirement off.
- - name: Docs locale catch-all rejects non-locale segments
+ # everything. The self-test is where every limb is observed failing --
+ # including the OG marker stripped of its dot -- and where the proxy
+ # condition is observed flipping the catch-all requirement off.
+ - name: Docs locale catch-all and OG card URL dot invariant
  run: pnpm check:docs-locale-catch-all
 
  # #11050 route spellings taught in prose: every /api/v1 wire-path

apps/docs/lib/source.ts

@@ -15,6 +15,31 @@ export const blog = loader({
  source: blogCollection.toFumadocsSource(),
 });
 
+/**
+ * The Open Graph card URL for a page: `/og/docs/<...page.slugs>/image.png`.
+ *
+ * The trailing `image.png` marker is load-bearing TWICE, and only the first is
+ * visible from this file:
+ *
+ * 1. `app/og/docs/[...slug]/route.tsx` resolves the page with
+ * `source.getPage(slug.slice(0, -1))` -- the marker is the sacrificial
+ * segment that slice discards. Its NAME does not matter to that.
+ * 2. Its DOT is what keeps this URL out of the locale rewriter. The matcher in
+ * `apps/docs/proxy.ts` excludes any path containing a dot, so a dotted final
+ * segment skips the proxy and reaches the route above. A marker WITHOUT a
+ * dot is rewritten to `/en/og/docs/...`, which is not a route at all --
+ * `app/og/` is top-level, not under `app/[lang]/`.
+ *
+ * Measured: `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200. So
+ * the marker's name is free; the presence of a dot is everything. Rename it to
+ * anything dotless -- or widen the proxy matcher on the other side -- and every
+ * `og:image` on the site 404s at once, which is worse than emitting none
+ * (crawlers fall back to scraping whatever else the page offers). Nothing
+ * fetches these URLs, so no test, type or link check would notice.
+ *
+ * `pnpm check:docs-locale-catch-all` gates the dot from here; the matcher half
+ * is commented on in `apps/docs/proxy.ts`.
+ */
 export function getPageImage(page: InferPageType<typeof source>) {
  const segments = [...page.slugs, 'image.png'];
 

apps/docs/proxy.ts

@@ -108,5 +108,23 @@ export const config = {
  // - Next.js static files (/_next/static/*)
  // - Next.js image optimization (/_next/image/*)
  // - Favicon and other static assets
+ //
+ // The `.*\..*` limb -- exclude any path containing a DOT -- is load-bearing
+ // for two surfaces beyond static assets, and neither is visible from here:
+ //
+ // - `apps/docs/lib/source.ts`'s `getPageImage()` appends an `image.png`
+ // marker to every Open Graph card URL. That marker's dot is the ONLY reason
+ // `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...`, which
+ // is not a route -- the `app/og/` tree is top-level, not under
+ // `app/[lang]/`. Widening this pattern 404s every `og:image` on the site at
+ // once, and nothing fetches those URLs, so the break is silent. Already
+ // ruled out as a surface to widen for the same reason from the other end:
+ // it would also 404 `/llms.txt`, `/llms-full.txt`, `/og/**` and
+ // `/docs/**.mdx`.
+ // - Conversely, BECAUSE dotted paths skip this proxy they reach `app/[lang]/`
+ // with `lang` set to the literal segment (`robots.txt`, `ads.txt`), which is
+ // why `apps/docs/lib/i18n.ts` carries the `isSupportedLanguage` guard.
+ //
+ // `pnpm check:docs-locale-catch-all` gates both halves.
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)'],
 };

.github/workflows/lint.yml

@@ -1460,12 +1460,23 @@ jobs:
  # every type still checks, every link still resolves. The only symptom is
  # a 200 where a 404 belongs, on URLs no test requests.
  #
+ # The same matcher rule holds up a SECOND surface, gated by the same
+ # script: `lib/source.ts`'s `getPageImage()` appends an `image.png` marker
+ # to every Open Graph card URL, and that marker's DOT is the only reason
+ # `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...` (not a
+ # route -- `app/og/` is top-level, not under `app/[lang]/`). Measured:
+ # `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200, so the
+ # marker's NAME is free and its dot is not. Rename it to anything dotless
+ # and every `og:image` on the site 404s at once; nothing fetches those
+ # URLs, so it is the same silent shape as the catch-all above.
+ #
  # Runs its own --self-test first (via the pnpm script). Not ceremony: the
  # live tree is green by construction after the fix, so a passing run over
  # real data cannot distinguish a working gate from one that approves
- # everything. The self-test is where every limb is observed failing, and
- # where the proxy condition is observed flipping the requirement off.
- - name: Docs locale catch-all rejects non-locale segments
+ # everything. The self-test is where every limb is observed failing --
+ # including the OG marker stripped of its dot -- and where the proxy
+ # condition is observed flipping the catch-all requirement off.
+ - name: Docs locale catch-all and OG card URL dot invariant
  run: pnpm check:docs-locale-catch-all
 
  # #11050 route spellings taught in prose: every /api/v1 wire-path

apps/docs/lib/source.ts

@@ -15,6 +15,31 @@ export const blog = loader({
  source: blogCollection.toFumadocsSource(),
 });
 
+/**
+ * The Open Graph card URL for a page: `/og/docs/<...page.slugs>/image.png`.
+ *
+ * The trailing `image.png` marker is load-bearing TWICE, and only the first is
+ * visible from this file:
+ *
+ * 1. `app/og/docs/[...slug]/route.tsx` resolves the page with
+ * `source.getPage(slug.slice(0, -1))` -- the marker is the sacrificial
+ * segment that slice discards. Its NAME does not matter to that.
+ * 2. Its DOT is what keeps this URL out of the locale rewriter. The matcher in
+ * `apps/docs/proxy.ts` excludes any path containing a dot, so a dotted final
+ * segment skips the proxy and reaches the route above. A marker WITHOUT a
+ * dot is rewritten to `/en/og/docs/...`, which is not a route at all --
+ * `app/og/` is top-level, not under `app/[lang]/`.
+ *
+ * Measured: `/og/docs/ai/agents` -> 404, `/og/docs/ai/agents/x.png` -> 200. So
+ * the marker's name is free; the presence of a dot is everything. Rename it to
+ * anything dotless -- or widen the proxy matcher on the other side -- and every
+ * `og:image` on the site 404s at once, which is worse than emitting none
+ * (crawlers fall back to scraping whatever else the page offers). Nothing
+ * fetches these URLs, so no test, type or link check would notice.
+ *
+ * `pnpm check:docs-locale-catch-all` gates the dot from here; the matcher half
+ * is commented on in `apps/docs/proxy.ts`.
+ */
 export function getPageImage(page: InferPageType<typeof source>) {
  const segments = [...page.slugs, 'image.png'];
 

apps/docs/proxy.ts

@@ -108,5 +108,23 @@ export const config = {
  // - Next.js static files (/_next/static/*)
  // - Next.js image optimization (/_next/image/*)
  // - Favicon and other static assets
+ //
+ // The `.*\..*` limb -- exclude any path containing a DOT -- is load-bearing
+ // for two surfaces beyond static assets, and neither is visible from here:
+ //
+ // - `apps/docs/lib/source.ts`'s `getPageImage()` appends an `image.png`
+ // marker to every Open Graph card URL. That marker's dot is the ONLY reason
+ // `/og/docs/<page>/image.png` is not rewritten to `/en/og/docs/...`, which
+ // is not a route -- the `app/og/` tree is top-level, not under
+ // `app/[lang]/`. Widening this pattern 404s every `og:image` on the site at
+ // once, and nothing fetches those URLs, so the break is silent. Already
+ // ruled out as a surface to widen for the same reason from the other end:
+ // it would also 404 `/llms.txt`, `/llms-full.txt`, `/og/**` and
+ // `/docs/**.mdx`.
+ // - Conversely, BECAUSE dotted paths skip this proxy they reach `app/[lang]/`
+ // with `lang` set to the literal segment (`robots.txt`, `ads.txt`), which is
+ // why `apps/docs/lib/i18n.ts` carries the `isSupportedLanguage` guard.
+ //
+ // `pnpm check:docs-locale-catch-all` gates both halves.
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)'],
 };