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|.*\\..*).*)'],
 };