From 84e0b2851595164c20045b9c8928ffc404f7df17 Mon Sep 17 00:00:00 2001
From: Kieron Lanning <kieronlanning@users.noreply.github.com>
Date: Sun, 8 Nov 2026 13:06:07 +0000
Subject: [PATCH] fix(catalogue): alias the playbook's flat dependency-versions
 address

`docs/wiki/foundations/Dependency-Versions.md` publishes under its topic
folder, so its URL is
`/docs/engineering-playbook/foundations/dependency-versions/` (ADR 0011) and
the docs-root address a reader may look for 404s. The catalogue now declares
that address in `docs.redirects`, so the build writes a noindex meta-refresh
page pointing at the nested one - and only while the nested page is published,
because a real page always owns its URL.

Verified in the built site: the flat address is a redirect, and the nested page
still renders its 11 registry badges verbatim (no `raw.githubusercontent.com`
rewrite).
---
 src/src/data/projects/engineering-playbook.yml |  7 +++++++
 src/tests/unit/docs-redirects.test.ts          | 14 ++++++++++++++
 2 files changed, 21 insertions(+)

diff --git a/src/src/data/projects/engineering-playbook.yml b/src/src/data/projects/engineering-playbook.yml
index e27e363..197043d 100644
--- a/src/src/data/projects/engineering-playbook.yml
+++ b/src/src/data/projects/engineering-playbook.yml
@@ -41,6 +41,13 @@ docs:
   # `Home.md` is the hub (`rootPage` above) and is published as the landing page.
   exclude:
     - _Sidebar.md
+  # A page's folder is part of its URL (ADR 0011), so `Dependency-Versions.md`
+  # publishes at `/docs/engineering-playbook/foundations/dependency-versions/`.
+  # The flat address is kept as an alias for anyone who looks for that page at
+  # the docs root: the build writes a meta-refresh redirect there, and only once
+  # the nested page it forwards to actually exists.
+  redirects:
+    dependency-versions: foundations/dependency-versions
 related:
   - build-sdk
   - containers
diff --git a/src/tests/unit/docs-redirects.test.ts b/src/tests/unit/docs-redirects.test.ts
index 95bde96..c58c1b7 100644
--- a/src/tests/unit/docs-redirects.test.ts
+++ b/src/tests/unit/docs-redirects.test.ts
@@ -197,6 +197,20 @@ describe('moved documentation page redirects', () => {
     ).toEqual([['/docs/zodsharp/performance/', '/docs/zodsharp/quality/performance/']]);
   });
 
+  test('the playbook keeps its docs-root dependency-versions address', () => {
+    // The page lives under its topic folder, which makes the folder part of the
+    // URL (ADR 0011), so the catalogue declares the docs-root address as an
+    // alias: a reader or a link that looks for `dependency-versions` at the
+    // project root lands on the page instead of a 404. The pair is only written
+    // while the nested page it forwards to is published.
+    expect(docsPageRedirects(projects)).toContainEqual({
+      from: '/docs/engineering-playbook/dependency-versions/',
+      to: '/docs/engineering-playbook/foundations/dependency-versions/',
+      title: 'This documentation page moved…',
+      message: 'The page now lives at its new address.',
+    });
+  });
+
   test('a moved page is written as a redirect once its new address is published', () => {
     const dist = mkdtempSync(join(tmpdir(), 'purview-redirects-'));
     try {