diff --git a/.agents/skills/docs-aggregation-rules/SKILL.md b/.agents/skills/docs-aggregation-rules/SKILL.md
index ac78d1c..c3ea877 100644
--- a/.agents/skills/docs-aggregation-rules/SKILL.md
+++ b/.agents/skills/docs-aggregation-rules/SKILL.md
@@ -109,8 +109,11 @@ The wikis of several product repositories are mirrored into `docs/wiki`, so the
 - Page order comes from, in priority: `docs.order` (explicit slug list) → a `_Sidebar.md` link order
   (both for `wiki` and for a mirrored wiki under `github-path`) → `1000`.
 - The landing page is always `order: -1`, so it heads the sidebar as "Overview".
-- Page slugs are slugified file names (`Getting-Started.md` → `getting-started`) and the URLs are
-  `/docs/<id>/<slug>/`. A `docsPage` in a use case must use that slug form.
+- A page's slug is its path from the docs root (ADR 0011): a flat corpus keeps the single-segment
+  slug (`Getting-Started.md` → `getting-started`, served at `/docs/<id>/getting-started/`), and a
+  topic folder stays a path segment (`schemas/Custom-Rules.md` →
+  `/docs/<id>/schemas/custom-rules/`). A `docsPage` in a use case must use a slug that still resolves
+  in the **default** channel, which is why it stays a single segment.
 
 ## Injected front matter (per page)
 
@@ -128,6 +131,13 @@ H1s are demoted to keep one title per document.
 
 - Each documented project becomes a `starlight-sidebar-topics` topic whose items come from
   `src/.cache/docs/index.json` (so the mirror and the manifest must come from the same sync).
+- The sidebar mirrors the published tree (ADR 0011): every folder in a slug becomes a nested
+  `starlight` group labelled with the folder's name spelled out (`schemas` → `Schemas`), placed where
+  its first page appears and holding all of that folder's pages in channel order. Nesting is
+  recursive, a folder's `index.md` links the folder's own address, and a flat corpus renders exactly
+  the flat list it always did (`buildChannelItems` in `src/lib/docs/sidebar.ts`).
+- Each aggregated page also names the folders above it, above the title, in the same spelling as the
+  sidebar (`PageTitle.astro` + `docSectionTrail`).
 - Archived projects are excluded from the docs portal, the sidebar topics, and per-project LLM
   bundles, even if they declare `docs`.
 - Every documented project gets `/projects/<id>/llms.txt` and `/projects/<id>/llms-full.txt`, linked
@@ -142,3 +152,7 @@ just data-sync                      # expect "docs <id>: <n> pages" per project
 node -e "console.log(require('./src/.cache/docs/index.json').projects)"
 just build && just check-generated  # asserts the mirror matches the manifest
 ```
+
+A reorganised tree is verified in the built output: the old flat slug must be a meta-refresh page
+pointing at the new address, on every channel that publishes the tree (`/docs/<id>/<old>/` and
+`/docs/<id>/prerelease/<old>/`), and the sidebar of a nested channel must contain a `group-label`.
diff --git a/AGENTS.md b/AGENTS.md
index 7278b1d..5503e2c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -97,8 +97,13 @@ prints advisory observations (which never fail the build) when a project's decla
    - A page's slug is its path from the docs root (ADR 0011): a topic folder stays a path segment
      (`schemas/Custom-Rules.md` is published at `/docs/<id>/schemas/custom-rules/`), a flat corpus
      keeps the single-segment slug it always had, and every relative link resolves against the page
-     that contains it. A project whose docs are reorganised records the old→new slug in
-     `docs.redirects`, which the build turns into redirects; a redirect never shadows a real page.
+     that contains it. The display mirrors that tree: the docs sidebar nests each folder as a group
+     (labelled with the folder's name spelled out) and each page names its section above the title,
+     so a flat corpus renders exactly as before. A project whose docs are reorganised records the
+     old→new slug in `docs.redirects`, which the build turns into redirects on **every** channel that
+     publishes the tree — the default channel at `/docs/<id>/` and the prerelease one at
+     `/docs/<id>/prerelease/`, each pair written only once its destination exists; a redirect never
+     shadows a real page.
    - Agent Skills a project publishes are declared in `skills:` (ADR 0010) at
      `skills/<name>/SKILL.md`; the sync mirrors the whole directory to
      `/skills/<id>/<name>/` and each project page renders the same install block
diff --git a/docs/decisions/0011-documentation-folders.md b/docs/decisions/0011-documentation-folders.md
index 7ff3ad6..9cc8d2d 100644
--- a/docs/decisions/0011-documentation-folders.md
+++ b/docs/decisions/0011-documentation-folders.md
@@ -75,7 +75,35 @@ the newer tree, the new address is unpublished too, so forwarding the reader wou
 be forwarding into a 404 — the post-build link crawl fails the build on exactly
 that, which is how this was found. Both halves activate per page, at promotion.
 
-### 4. `docsPage` stays a single segment
+A pair is emitted for every base the project publishes: the default channel at
+`/docs/<id>/` and, when `live` and `prerelease` are both declared, the prerelease
+channel at `/docs/<id>/prerelease/`. The reorganised tree is usually published on
+the prerelease channel *first* — that is what a default-branch docs change is —
+and its readers follow URLs that move at the same moment the default channel's
+do later. The same two guards decide which pairs are real, so a withheld channel
+still writes nothing here; its URLs belong to the retired-channel redirects.
+
+### 4. The sidebar and the page show the tree the URL describes
+
+Publishing a hierarchy in the URL and then flattening it in the sidebar would
+leave the reader with the one thing folders were meant to fix: grouping that the
+address disagrees with. So the display follows the slug:
+
+- `buildChannelItems` nests a channel's pages into Starlight sidebar groups, one
+  per folder, labelled with the folder's segment spelled out (`schemas` →
+  `Schemas`, `json-schema` → `JSON Schema`). A group appears where its first page
+  appears and absorbs its later pages, so a folder is listed once and the sync's
+  reading order (`docs.order` / `_Sidebar.md`) survives.
+- Nesting is recursive, because a slug is a path: `guides/getting-started/install`
+  is a group inside a group. A folder's index file (`schemas/index.md`) is
+  published at the folder's own address, so its sidebar entry links the folder.
+- A flat corpus has no folder in any slug, so it produces no group and no code
+  path changes for the projects that never nested.
+- A page names its section above the title (`PageTitle.astro`), using the same
+  spelling as the sidebar, so a reader arriving from search knows which part of
+  the documentation they are in.
+
+### 5. `docsPage` stays a single segment
 
 The catalogue's deep-link slug keeps its `^[a-z0-9-]+$` shape and resolves against
 the default channel. A deep link must therefore keep working across two trees that
@@ -94,7 +122,14 @@ move the failure to the moment a channel's tree diverges.
 - Documentation written for a flat corpus is unaffected in both slug and link
   terms, so this landed without touching another project's catalogue.
 - ZodSharp's own move is the first user of `docs.redirects`: 30 entries that stay
-  inert until the release that carries the folders is promoted to `live`.
+  inert on the default channel until the release that carries the folders is
+  promoted to `live`, and apply immediately to the prerelease channel, which reads
+  the reorganised tree today.
+- `buildChannelItems` returns a tree instead of a list. That is the only shape
+  change the display took: `SidebarDocItem[]` replaced `SidebarSlugEntry[]`, and
+  every other use of the docs cache (`llms` bundles, discovery resources, the docs
+  portal) still reads the flat page list, which remains the source of truth for
+  what a channel publishes.
 
 ## Alternatives considered
 
diff --git a/src/src/components/starlight/PageTitle.astro b/src/src/components/starlight/PageTitle.astro
index befeb26..5517714 100644
--- a/src/src/components/starlight/PageTitle.astro
+++ b/src/src/components/starlight/PageTitle.astro
@@ -4,6 +4,7 @@ import StarOnGitHub from '~/components/StarOnGitHub.astro';
 import StatusBadge from '~/components/StatusBadge.astro';
 import { readDocsManifest } from '~/lib/docs/aggregate';
 import { channelBasePath, channelDisplayLabel } from '~/lib/docs/channels';
+import { docSectionTrail } from '~/lib/docs/sidebar';
 import { isStale, STALE_AFTER_DAYS } from '~/lib/docs/staleness';
 import { projectChannelLlmsFullPath, projectChannelLlmsPath } from '~/lib/discovery/urls';
 import { LLMS_LINK_ATTRS } from '~/lib/llms';
@@ -35,6 +36,14 @@ const showChannelSwitcher = channels.length > 1 && activeChannel !== undefined;
 const channelHref = (channelId: 'live' | 'prerelease', isDefault: boolean): string =>
   withBase(channelBasePath(sourceProjectId ?? '', channelId, isDefault));
 
+// A page's folder is part of its URL (ADR 0011), so a reader who arrives from
+// search on `schemas/custom-rules` is told which section of the documentation
+// they are in, not only which project. The trail is the same spelling the
+// sidebar uses for its folder groups, and it is empty for a flat corpus — a
+// page at the docs root has no section above it.
+const activePage = activeChannel?.pages.find((page) => page.sourcePath === data?.sourcePath);
+const sectionTrail = activePage ? docSectionTrail(activePage.slug) : [];
+
 // A tag-pinned channel does not move, so its review date is the release date:
 // flagging it as stale would be noise rather than drift.
 const pinnedChannel = activeChannel?.refKind === 'tag';
@@ -86,6 +95,15 @@ const starCount =
   : (getReleaseIndex().data.repos[sourceRepo]?.stargazersCount ?? null);
 ---
 
+{
+  sectionTrail.length > 0 && (
+    <p class="doc-sections">
+      <span class="sr-only">Documentation section: </span>
+      {sectionTrail.join(' / ')}
+    </p>
+  )
+}
+
 <h1 id="_top">{data?.title}</h1>
 
 {
@@ -224,6 +242,19 @@ const starCount =
 }
 
 <style>
+  /* The section trail names the folders above the page (ADR 0011). It sits
+   * directly above the title, in the same tracked-uppercase treatment as the
+   * sidebar's folder groups, so the two read as the same hierarchy. Hidden for
+   * pages at the docs root, which have no section. */
+  .doc-sections {
+    margin: 0 0 0.375rem;
+    font-size: 0.6875rem;
+    font-weight: 600;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--sl-color-gray-2);
+  }
+
   /* Channel switcher (ADR 0009). Rendered only when a project publishes both a
    * live and a prerelease channel. It is a native <details> disclosure so the
    * versions stay reachable without JavaScript: the summary names the channel
diff --git a/src/src/lib/docs/redirects.ts b/src/src/lib/docs/redirects.ts
index d7d759d..5c086bf 100644
--- a/src/src/lib/docs/redirects.ts
+++ b/src/src/lib/docs/redirects.ts
@@ -105,6 +105,15 @@ export function retiredChannelRedirects(
  * catalogue. `writeStaticRedirect` never overwrites a file, which is what makes
  * the declaration timing-safe - while the `live` channel still reads an older tag,
  * the old slug is a real page and the redirect is simply not written.
+ *
+ * Every published channel owns URLs of its own, so a move is forwarded from each
+ * base the project publishes: the default channel at `/docs/<id>/` and, when the
+ * project declares both channels, the prerelease one at `/docs/<id>/prerelease/`.
+ * A tree can be reorganised on the default branch long before the release that
+ * carries it is promoted, and the readers on the prerelease channel are following
+ * URLs that change at the same moment. Whether a pair is real is decided by the
+ * write guards exactly as for the default channel, so a withheld channel writes
+ * nothing here (its URLs are retired-channel redirects instead).
  */
 export function docsPageRedirects(projects: readonly ResolvedProject[]): DocChannelRedirect[] {
   const redirects: DocChannelRedirect[] = [];
@@ -113,13 +122,22 @@ export function docsPageRedirects(projects: readonly ResolvedProject[]): DocChan
       continue;
     }
     const moved = project.docs.redirects ?? {};
+    const bases = [`/docs/${project.id}`];
+    // `prerelease` is only a second channel when `live` is declared with it;
+    // on its own it would be the default channel and own the canonical URLs.
+    const declared = project.docs.channels;
+    if (declared?.live !== undefined && declared.prerelease !== undefined) {
+      bases.push(`/docs/${project.id}/prerelease`);
+    }
     for (const [from, to] of Object.entries(moved)) {
-      redirects.push({
-        from: `/docs/${project.id}/${from}/`,
-        to: `/docs/${project.id}/${to}/`,
-        title: 'This documentation page moved…',
-        message: 'The page now lives at its new address.',
-      });
+      for (const base of bases) {
+        redirects.push({
+          from: `${base}/${from}/`,
+          to: `${base}/${to}/`,
+          title: 'This documentation page moved…',
+          message: 'The page now lives at its new address.',
+        });
+      }
     }
   }
   return redirects;
diff --git a/src/src/lib/docs/sidebar.ts b/src/src/lib/docs/sidebar.ts
index 159a0b7..4514796 100644
--- a/src/src/lib/docs/sidebar.ts
+++ b/src/src/lib/docs/sidebar.ts
@@ -3,11 +3,29 @@ import type { DocsManifest, DocsManifestChannel } from './aggregate';
 
 import { channelBasePath } from './channels';
 
+/** A single documentation page, linked by its content-collection slug. */
 export interface SidebarSlugEntry {
   label?: string;
   slug: string;
 }
 
+/**
+ * A folder of the documentation tree, rendered as a Starlight sidebar group.
+ *
+ * A folder is a place in the tree rather than a page, so the group carries no
+ * link of its own: a source tree that ships an index file for the folder
+ * contributes a page (see `nestPages`), and otherwise the pages inside it are
+ * the links.
+ */
+export interface SidebarGroupEntry {
+  label: string;
+  items: SidebarDocItem[];
+  /** Folders start open; Starlight remembers what a reader collapses. */
+  collapsed?: boolean;
+}
+
+export type SidebarDocItem = SidebarSlugEntry | SidebarGroupEntry;
+
 /**
  * One documentation version, exposed as its own Starlight topic.
  *
@@ -19,7 +37,63 @@ export interface SidebarChannelTopic {
   id: string;
   label: string;
   link: string;
-  items: SidebarSlugEntry[];
+  items: SidebarDocItem[];
+}
+
+/**
+ * Segments whose spelled-out form is wrong in a label: a folder called `json`
+ * is JSON, not "Json".
+ */
+const SEGMENT_UPPERCASE = new Set([
+  'aot',
+  'api',
+  'cli',
+  'http',
+  'https',
+  'json',
+  'mcp',
+  'nuget',
+  'sdk',
+  'sql',
+  'ui',
+  'url',
+  'xml',
+  'yaml',
+]);
+
+/**
+ * Display label for one slug segment: `compiled-validators` → `Compiled Validators`.
+ *
+ * A source folder has no title of its own — only its name — so a group label is
+ * the folder's segment spelled out, exactly as `extractTitle` spells out a file
+ * name when a page has no heading.
+ */
+export function docSectionLabel(segment: string): string {
+  return segment
+    .split(/[-_]+/)
+    .filter((word) => word !== '')
+    .map((word) =>
+      SEGMENT_UPPERCASE.has(word)
+        ? word.toUpperCase()
+        : word.charAt(0).toUpperCase() + word.slice(1),
+    )
+    .join(' ');
+}
+
+/**
+ * Display labels of the folders a page lives in, outermost first:
+ * `schemas/custom-rules` → `['Schemas']`.
+ *
+ * The page itself is not part of the trail; this names the sections above it, so
+ * a page can say where in the tree it lives as well as which project it belongs
+ * to.
+ */
+export function docSectionTrail(slug: string): string[] {
+  return slug
+    .split('/')
+    .slice(0, -1)
+    .filter((segment) => segment !== '')
+    .map(docSectionLabel);
 }
 
 /** Content-relative base for a channel: `docs/<id>` or `docs/<id>/<channel>`. */
@@ -27,26 +101,76 @@ function channelBase(projectId: string, channel: DocsManifestChannel): string {
   return channel.default ? `docs/${projectId}` : `docs/${projectId}/${channel.id}`;
 }
 
+/**
+ * Slug of the content entry a page is published as.
+ *
+ * An `index` page addresses the directory that holds it — Starlight strips the
+ * `index` segment, so `schemas/index.md` is served at `<base>/schemas`, not at
+ * `<base>/schemas/index`. Starlight prefixes the locale dir itself.
+ */
+function entrySlug(base: string, slug: string): string {
+  const segments = slug.split('/');
+  if (segments[segments.length - 1] === 'index') {
+    return [base, ...segments.slice(0, -1)].join('/');
+  }
+  return `${base}/${slug}`;
+}
+
+/**
+ * Arrange a channel's pages into the folder tree their slugs describe.
+ *
+ * Since ADR 0011 a slug is a path (`schemas/custom-rules`), so the hierarchy a
+ * project publishes is already in the data: the sidebar renders it instead of
+ * flattening it into one list of thirty links. A folder appears where its first
+ * page appears and its pages keep the order the channel gives them (`docs.order`
+ * or `_Sidebar.md`), which is what keeps the sync's reading order intact.
+ *
+ * A flat corpus has no folder in any slug, so it produces no group here: the
+ * entries are exactly the page list, in order, as before.
+ */
+function nestPages(pages: DocsManifestChannel['pages'], base: string): SidebarDocItem[] {
+  const items: SidebarDocItem[] = [];
+  // Keyed by the folder's full path (`schemas`, `guides/getting-started`), never
+  // by its own name, so two folders may share a leaf name at different depths.
+  const groups = new Map<string, SidebarGroupEntry>();
+  for (const page of pages) {
+    const segments = page.slug.split('/');
+    let siblings = items;
+    let path = base;
+    for (const folder of segments.slice(0, -1)) {
+      path = `${path}/${folder}`;
+      let group = groups.get(path);
+      if (!group) {
+        group = { label: docSectionLabel(folder), items: [] };
+        groups.set(path, group);
+        siblings.push(group);
+      }
+      siblings = group.items;
+    }
+    siblings.push({ label: page.title, slug: entrySlug(base, page.slug) });
+  }
+  return items;
+}
+
 /**
  * Items for one channel: an Overview entry when the channel has an index page,
- * then one entry per page. Index pages resolve to the directory slug (no
- * trailing `/index`); Starlight prefixes the locale dir itself.
+ * then one entry per page, nested by the folders its slug names.
  */
 export function buildChannelItems(
   projectId: string,
   channel: DocsManifestChannel,
-): SidebarSlugEntry[] {
+): SidebarDocItem[] {
   const base = channelBase(projectId, channel);
-  const items: SidebarSlugEntry[] = [];
+  const items: SidebarDocItem[] = [];
   if (channel.pages.some((page) => page.slug === 'index')) {
     items.push({ label: 'Overview', slug: base });
   }
-  for (const page of channel.pages) {
-    if (page.slug === 'index') {
-      continue;
-    }
-    items.push({ label: page.title, slug: `${base}/${page.slug}` });
-  }
+  items.push(
+    ...nestPages(
+      channel.pages.filter((page) => page.slug !== 'index'),
+      base,
+    ),
+  );
   return items;
 }
 
diff --git a/src/src/styles/global.css b/src/src/styles/global.css
index f1e3ebf..0190a55 100644
--- a/src/src/styles/global.css
+++ b/src/src/styles/global.css
@@ -557,6 +557,30 @@
     font-size: 0.8125rem;
   }
 
+  /* -------------------------------------------------------------------------
+   * Documentation folders in the docs sidebar
+   * -----------------------------------------------------------------------
+   * A page's folder is part of its URL (ADR 0011), and the sidebar nests it as a
+   * Starlight group so the list mirrors the tree instead of flattening thirty
+   * links. Starlight gives every group label the top-level "large" treatment,
+   * which would make a folder read like a second project inside the topic, so a
+   * *nested* group is reduced to a tracked section label: smaller than a page
+   * link, uppercase, and muted. A project with a flat corpus renders no group at
+   * all, so nothing here reaches it. The classes are Starlight internals
+   * (SidebarSublist.astro) and are re-checked when Starlight is upgraded.
+   */
+  .sidebar-content ul:not(.top-level) > li > details > summary {
+    margin-top: 0.625rem;
+  }
+
+  .sidebar-content ul:not(.top-level) > li > details > summary .large {
+    font-size: var(--sl-text-xs);
+    font-weight: 600;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--sl-color-gray-2);
+  }
+
   /* -------------------------------------------------------------------------
    * Wide-screen documentation layout
    * -----------------------------------------------------------------------
diff --git a/src/tests/dist/built-output.test.ts b/src/tests/dist/built-output.test.ts
index b146962..6c16c11 100644
--- a/src/tests/dist/built-output.test.ts
+++ b/src/tests/dist/built-output.test.ts
@@ -6,6 +6,7 @@ import { LOCAL_PATH_PATTERNS, SECRET_PATTERNS } from '../../src/lib/build-paths'
 import { DISCOVERY_MANIFEST_SCHEMA_VERSION } from '../../src/lib/discovery/types';
 import { readDocsManifest } from '../../src/lib/docs/aggregate';
 import { channelDisplayLabel } from '../../src/lib/docs/channels';
+import { docSectionLabel } from '../../src/lib/docs/sidebar';
 import { buildLlmsDetails } from '../../src/lib/llms-details';
 import { loadProjects } from '../../src/lib/manifest/load';
 import { compareNuGetVersions } from '../../src/lib/nuget-version';
@@ -577,4 +578,54 @@ describe('built documentation channels', () => {
     expect(existsSync(resolve(DIST, 'docs/event-sourcing/index.html'))).toBe(true);
     expect(existsSync(resolve(DIST, 'docs/event-sourcing/prerelease'))).toBe(false);
   });
+
+  test('the docs sidebar mirrors the documentation tree of each published channel', () => {
+    // A page's folder is a path segment of its URL (ADR 0011), so the sidebar
+    // nests it as a group and the page names its section above the title. A
+    // channel whose pages all sit at the docs root renders neither, which is what
+    // keeps a flat corpus looking exactly as it did before folders existed.
+    const channels = [live, prerelease].filter(
+      (channel): channel is NonNullable<typeof channel> => channel !== undefined,
+    );
+    expect(channels.length).toBeGreaterThan(0);
+
+    for (const channel of channels) {
+      const site = channel.default ? '/docs/zodsharp/' : `/docs/zodsharp/${channel.id}/`;
+      const distBase = channel.default ? 'docs/zodsharp/' : `docs/zodsharp/${channel.id}/`;
+      const content = requireBuilt(`${distBase}index.html`);
+      const start = content.indexOf('class="sidebar-content');
+      const sidebar = content.slice(start, content.indexOf('</sl-sidebar-pane', start));
+      const folders = [
+        ...new Set(
+          channel.pages
+            .filter((page) => page.slug.includes('/'))
+            .map((page) => page.slug.split('/')[0] ?? ''),
+        ),
+      ];
+
+      if (folders.length === 0) {
+        expect(sidebar).not.toContain('group-label');
+      }
+      for (const folder of folders) {
+        // One group per folder, labelled with the segment spelled out, holding
+        // links to the hierarchical addresses.
+        expect(sidebar).toContain('group-label');
+        expect(sidebar).toContain(`>${docSectionLabel(folder)}<`);
+      }
+
+      const nested = channel.pages.find((page) => page.slug.includes('/'));
+      if (nested) {
+        expect(sidebar).toContain(`href="${site}${nested.slug}/"`);
+        const page = requireBuilt(`${distBase}${nested.slug}/index.html`);
+        expect(page).toContain('class="doc-sections');
+      }
+      const atRoot = channel.pages.find(
+        (page) => page.slug !== 'index' && !page.slug.includes('/'),
+      );
+      if (atRoot) {
+        const page = requireBuilt(`${distBase}${atRoot.slug}/index.html`);
+        expect(page).not.toContain('class="doc-sections');
+      }
+    }
+  });
 });
diff --git a/src/tests/unit/docs-redirects.test.ts b/src/tests/unit/docs-redirects.test.ts
index 0624e97..95bde96 100644
--- a/src/tests/unit/docs-redirects.test.ts
+++ b/src/tests/unit/docs-redirects.test.ts
@@ -162,6 +162,41 @@ describe('moved documentation page redirects', () => {
     });
   });
 
+  test('a move is forwarded on every channel that publishes the tree', () => {
+    // The prerelease channel publishes the reorganised tree long before the
+    // release that carries it is promoted, so its readers follow the same move:
+    // every pair exists under both bases, and the write guards decide which of
+    // them are real in the build at hand.
+    expect(docsPageRedirects(projects)).toContainEqual({
+      from: '/docs/zodsharp/prerelease/performance/',
+      to: '/docs/zodsharp/prerelease/quality/performance/',
+      title: 'This documentation page moved…',
+      message: 'The page now lives at its new address.',
+    });
+  });
+
+  test('a single-channel project forwards the canonical base only', () => {
+    // Without a second declared channel there is no `/prerelease/` URL to
+    // forward: the channel is the default one, and it owns `/docs/<id>/`.
+    const singleChannel = projects.map((project) =>
+      project.id === 'zodsharp'
+        ? {
+            ...project,
+            docs: {
+              source: 'github-path' as const,
+              path: 'docs/wiki',
+              redirects: { performance: 'quality/performance' },
+            },
+          }
+        : project,
+    );
+    expect(
+      docsPageRedirects(singleChannel)
+        .filter((redirect) => redirect.from.startsWith('/docs/zodsharp/'))
+        .map((redirect) => [redirect.from, redirect.to]),
+    ).toEqual([['/docs/zodsharp/performance/', '/docs/zodsharp/quality/performance/']]);
+  });
+
   test('a moved page is written as a redirect once its new address is published', () => {
     const dist = mkdtempSync(join(tmpdir(), 'purview-redirects-'));
     try {
diff --git a/src/tests/unit/docs-sidebar.test.ts b/src/tests/unit/docs-sidebar.test.ts
index 644ebeb..3afbd27 100644
--- a/src/tests/unit/docs-sidebar.test.ts
+++ b/src/tests/unit/docs-sidebar.test.ts
@@ -1,10 +1,15 @@
 import type { DocsManifest, DocsManifestChannel } from '../../src/lib/docs/aggregate';
 import type { DocChannelId } from '../../src/lib/docs/channels';
+import type {
+  SidebarDocItem,
+  SidebarGroupEntry,
+  SidebarSlugEntry,
+} from '../../src/lib/docs/sidebar';
 
 import { describe, expect, test } from 'bun:test';
 
 import { DOCS_MANIFEST_SCHEMA } from '../../src/lib/docs/aggregate';
-import { buildProjectTopics } from '../../src/lib/docs/sidebar';
+import { buildProjectTopics, docSectionLabel, docSectionTrail } from '../../src/lib/docs/sidebar';
 import { loadProjects } from '../../src/lib/manifest/load';
 
 const project = loadProjects().find((candidate) => candidate.id === 'zodsharp');
@@ -12,6 +17,34 @@ if (!project) {
   throw new Error('the catalogue must define zodsharp for these tests');
 }
 
+function page(slug: string, title: string, order: number): DocsManifestChannel['pages'][number] {
+  return {
+    slug,
+    title,
+    order,
+    sourcePath: `docs/wiki/${slug.replace(/\//g, '-')}.md`,
+    hash: `${slug}-hash`,
+  };
+}
+
+const flatPages = [page('index', 'ZodSharp', -1), page('core-concepts', 'Core concepts', 1)];
+
+/**
+ * The shape ZodSharp's prerelease tree publishes (ADR 0011): pages at the docs
+ * root beside folders that carry their own pages, in the order `_Sidebar.md`
+ * gives, which is the order the sync keeps.
+ */
+const nestedPages = [
+  page('index', 'ZodSharp', -1),
+  page('getting-started', 'Getting Started', 1),
+  page('concepts/core-concepts', 'Core Concepts', 2),
+  page('fluent-schema-api', 'Fluent Schema API', 3),
+  page('schemas/string-validation', 'String Validation', 4),
+  page('concepts/composition-and-transforms', 'Composition and Transforms', 5),
+  page('schemas/custom-rules', 'Custom Rules', 6),
+  page('development/contributing', 'Contributing', 7),
+];
+
 function channel(
   id: DocChannelId,
   overrides: Partial<DocsManifestChannel> = {},
@@ -24,22 +57,7 @@ function channel(
     version: live ? '2.4.2' : '3.0.0-prerelease.2',
     label: live ? '2.4.2' : '3.0.0-prerelease.2',
     default: live,
-    pages: [
-      {
-        slug: 'index',
-        title: 'ZodSharp',
-        order: -1,
-        sourcePath: 'docs/wiki/Getting-Started.md',
-        hash: `${id}-index`,
-      },
-      {
-        slug: 'core-concepts',
-        title: 'Core concepts',
-        order: 1,
-        sourcePath: 'docs/wiki/Core-Concepts.md',
-        hash: `${id}-core`,
-      },
-    ],
+    pages: flatPages,
     ...overrides,
   };
 }
@@ -55,6 +73,16 @@ function manifest(channels: DocsManifestChannel[]): DocsManifest {
 
 const bothChannels = () => manifest([channel('live'), channel('prerelease')]);
 
+/** A group is the only sidebar item that carries children. */
+function isGroup(item: SidebarDocItem): item is SidebarGroupEntry {
+  return 'items' in item;
+}
+
+/** Every page link in an item list, depth-first, so tests can assert on the pages. */
+function leaves(items: SidebarDocItem[]): SidebarSlugEntry[] {
+  return items.flatMap((item) => (isGroup(item) ? leaves(item.items) : [item]));
+}
+
 describe('documentation sidebar topics', () => {
   test('a single-channel project keeps one flat topic named after the project', () => {
     const topics = buildProjectTopics(project!, manifest([channel('live')]));
@@ -88,23 +116,170 @@ describe('documentation sidebar topics', () => {
 
   test('the two versions never share a page or a group', () => {
     const [live, prerelease] = buildProjectTopics(project!, bothChannels());
-    const liveSlugs = new Set(live!.items.map((item) => item.slug));
-    expect(prerelease!.items.some((item) => liveSlugs.has(item.slug))).toBe(false);
+    const liveSlugs = new Set(leaves(live!.items).map((item) => item.slug));
+    expect(leaves(prerelease!.items).some((item) => liveSlugs.has(item.slug))).toBe(false);
     expect(prerelease!.items).toEqual([
       { label: 'Overview', slug: 'docs/zodsharp/prerelease' },
       { label: 'Core concepts', slug: 'docs/zodsharp/prerelease/core-concepts' },
     ]);
   });
 
-  test('a topic is a flat list of links, never nested groups', () => {
+  test('a flat corpus stays a flat list of links', () => {
+    // A project that never nests a page renders exactly what it did before
+    // folders existed: no group, one link per page, in the channel's order.
     for (const topic of buildProjectTopics(project!, bothChannels())) {
+      expect(topic.items.every((item) => !isGroup(item))).toBe(true);
       for (const item of topic.items) {
         expect(Object.keys(item).toSorted()).toEqual(['label', 'slug']);
       }
     }
   });
 
+  test('a page folder is a group that mirrors the published path', () => {
+    const topics = buildProjectTopics(
+      project!,
+      manifest([channel('prerelease', { pages: nestedPages })]),
+    );
+    expect(topics[0]!.items).toEqual([
+      { label: 'Overview', slug: 'docs/zodsharp/prerelease' },
+      { label: 'Getting Started', slug: 'docs/zodsharp/prerelease/getting-started' },
+      {
+        label: 'Concepts',
+        items: [
+          { label: 'Core Concepts', slug: 'docs/zodsharp/prerelease/concepts/core-concepts' },
+          {
+            label: 'Composition and Transforms',
+            slug: 'docs/zodsharp/prerelease/concepts/composition-and-transforms',
+          },
+        ],
+      },
+      { label: 'Fluent Schema API', slug: 'docs/zodsharp/prerelease/fluent-schema-api' },
+      {
+        label: 'Schemas',
+        items: [
+          {
+            label: 'String Validation',
+            slug: 'docs/zodsharp/prerelease/schemas/string-validation',
+          },
+          { label: 'Custom Rules', slug: 'docs/zodsharp/prerelease/schemas/custom-rules' },
+        ],
+      },
+      {
+        label: 'Development',
+        items: [
+          { label: 'Contributing', slug: 'docs/zodsharp/prerelease/development/contributing' },
+        ],
+      },
+    ]);
+  });
+
+  test('a group sits where its first page sits and holds its whole folder', () => {
+    // `concepts` is entered by Core Concepts (third entry) and continued by
+    // Composition and Transforms (sixth): the group keeps the first position and
+    // absorbs the later page, so a folder is listed once and its pages keep the
+    // order the channel gave them.
+    const [topic] = buildProjectTopics(
+      project!,
+      manifest([channel('prerelease', { pages: nestedPages })]),
+    );
+    expect(topic!.items.map((item) => item.label)).toEqual([
+      'Overview',
+      'Getting Started',
+      'Concepts',
+      'Fluent Schema API',
+      'Schemas',
+      'Development',
+    ]);
+    const concepts = topic!.items.find(
+      (item): item is SidebarGroupEntry => isGroup(item) && item.label === 'Concepts',
+    );
+    expect(concepts!.items.map((item) => item.label)).toEqual([
+      'Core Concepts',
+      'Composition and Transforms',
+    ]);
+  });
+
+  test('folders nest as deeply as the tree does', () => {
+    const topics = buildProjectTopics(
+      project!,
+      manifest([
+        channel('live', {
+          pages: [
+            page('index', 'ZodSharp', -1),
+            page('guides/getting-started/install', 'Install', 1),
+            page('guides/getting-started/upgrade', 'Upgrade', 2),
+          ],
+        }),
+      ]),
+    );
+    expect(topics[0]!.items).toEqual([
+      { label: 'Overview', slug: 'docs/zodsharp' },
+      {
+        label: 'Guides',
+        items: [
+          {
+            label: 'Getting Started',
+            items: [
+              { label: 'Install', slug: 'docs/zodsharp/guides/getting-started/install' },
+              { label: 'Upgrade', slug: 'docs/zodsharp/guides/getting-started/upgrade' },
+            ],
+          },
+        ],
+      },
+    ]);
+  });
+
+  test('a folder index page links the folder, not a page called index', () => {
+    // Starlight serves `<base>/schemas/` for `schemas/index.md`, so a nested
+    // index is published at the folder's own address and must be linked there.
+    const topics = buildProjectTopics(
+      project!,
+      manifest([
+        channel('live', {
+          pages: [
+            page('index', 'ZodSharp', -1),
+            page('schemas/index', 'Schemas', 1),
+            page('schemas/custom-rules', 'Custom Rules', 2),
+          ],
+        }),
+      ]),
+    );
+    expect(topics[0]!.items).toEqual([
+      { label: 'Overview', slug: 'docs/zodsharp' },
+      {
+        label: 'Schemas',
+        items: [
+          { label: 'Schemas', slug: 'docs/zodsharp/schemas' },
+          { label: 'Custom Rules', slug: 'docs/zodsharp/schemas/custom-rules' },
+        ],
+      },
+    ]);
+  });
+
   test('no docs manifest means no topics', () => {
     expect(buildProjectTopics(project!, null)).toEqual([]);
   });
 });
+
+describe('documentation sections', () => {
+  test('a folder segment is spelled out as a label', () => {
+    expect(docSectionLabel('schemas')).toBe('Schemas');
+    expect(docSectionLabel('compiled-validators')).toBe('Compiled Validators');
+    expect(docSectionLabel('getting_started')).toBe('Getting Started');
+    // A segment that is an initialism keeps its capitalisation.
+    expect(docSectionLabel('json')).toBe('JSON');
+    expect(docSectionLabel('json-schema')).toBe('JSON Schema');
+  });
+
+  test('a page reports the folders above it', () => {
+    expect(docSectionTrail('schemas/custom-rules')).toEqual(['Schemas']);
+    expect(docSectionTrail('guides/getting-started/install')).toEqual([
+      'Guides',
+      'Getting Started',
+    ]);
+    expect(docSectionTrail('schemas/index')).toEqual(['Schemas']);
+    // A page at the docs root has no section above it.
+    expect(docSectionTrail('core-concepts')).toEqual([]);
+    expect(docSectionTrail('index')).toEqual([]);
+  });
+});