From 189a2914b720c1c80a7357ee65cffaaffacb0f30 Mon Sep 17 00:00:00 2001
From: Bruno Germano <bruno.germano@gmail.com>
Date: Fri, 11 Sep 2026 18:58:13 -0300
Subject: [PATCH 1/8] fix(styles): stop base.css from overriding every theme
 font token
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`* { font-family: 'Sora' }` was unlayered, so it outranked Tailwind's
`@layer utilities` regardless of specificity, and matched every element
directly, defeating inheritance. Together that silently forced Sora over
`text-overline-*`, `text-big-number-*` and `font-mono` — the other
properties of those tokens still applied, which is why it read as "the
mono font is broken" rather than "the token is broken".

The base family already comes from the theme's `--default-font-family`
via Tailwind preflight on `html`, so the declaration was redundant.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/styles/base.css | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/styles/base.css b/src/styles/base.css
index 5389f0cdac..c1c8fa84b1 100644
--- a/src/styles/base.css
+++ b/src/styles/base.css
@@ -8,8 +8,12 @@ body {
 	color: var(--text-default);
 }
 
+/* NEVER set font-family here. `*` matches every element directly, so it defeats
+   inheritance AND — being unlayered — it outranks every normal utility in
+   `@layer utilities`, silently killing `text-overline-*`, `text-big-number-*`,
+   `font-mono` and friends. The base family already comes from the theme's
+   `--default-font-family` (Sora) via Tailwind preflight on `html`. */
 * {
-	font-family: 'Sora', sans-serif;
 	box-sizing: border-box;
 	text-rendering: optimizeLegibility;
 	-webkit-font-smoothing: antialiased;

From b7204e67a2e847b15057b727686a238ffc3c4194 Mon Sep 17 00:00:00 2001
From: Bruno Germano <bruno.germano@gmail.com>
Date: Fri, 11 Sep 2026 18:58:30 -0300
Subject: [PATCH 2/8] fix(footer): point the two stale docs links at their real
 permalinks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`/products/azion-platform-overview/` and `/products/release-notes/` both
404 — the pages live at the permalinks declared in their own frontmatter,
`/fundamentals/` and `/changelog/`. Verified 200 on both local and the
preview deploy.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/i18n/en/footer.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/i18n/en/footer.ts b/src/i18n/en/footer.ts
index a7933da076..efa6876257 100644
--- a/src/i18n/en/footer.ts
+++ b/src/i18n/en/footer.ts
@@ -58,7 +58,7 @@ const listData = [
 			},
 			{
 				title: 'How to start',
-				link: '/en/documentation/products/azion-platform-overview/',
+				link: '/en/documentation/fundamentals/',
 			},
 			{
 				title: 'Pricing',
@@ -87,7 +87,7 @@ const listData = [
 			},
 			{
 				title: 'Release Notes',
-				link: '/en/documentation/products/release-notes/',
+				link: '/en/documentation/changelog/',
 			},
 			{
 				title: 'Our Community',

From 8604d4cca53ce17ccdce38d3819504ff7c91acd5 Mon Sep 17 00:00:00 2001
From: Bruno Germano <bruno.germano@gmail.com>
Date: Fri, 11 Sep 2026 18:59:11 -0300
Subject: [PATCH 3/8] refactor(sidebar): move the theme switch into the rail
 footer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The light/dark control lived in the site footer, which put it below the
fold on every docs page. It now sits in the Sidebar's footer slot, where
it is reachable from anywhere in the rail.

Patches webkit's Sidebar so the footer region is a bar rather than a
padded block — one row at the header's own height with a top rule, so the
rail ends on the baseline the top bar starts on. That also lets DocsSidebar
drop its `--rail-w` style override and the eslint-disable it needed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 patches/@aziontech__webkit@5.0.0.patch        | 50 +++++++++++++++----
 pnpm-lock.yaml                                |  6 +--
 src/components/Footer.vue                     |  3 --
 src/components/webkit/DocsSidebar.vue         | 21 +++-----
 .../webkit/DropdownThemeSwitcher.vue          |  4 +-
 src/layouts/BaseLayout.astro                  |  4 --
 6 files changed, 50 insertions(+), 38 deletions(-)

diff --git a/patches/@aziontech__webkit@5.0.0.patch b/patches/@aziontech__webkit@5.0.0.patch
index 990763318b..8e1edc063e 100644
--- a/patches/@aziontech__webkit@5.0.0.patch
+++ b/patches/@aziontech__webkit@5.0.0.patch
@@ -1,5 +1,5 @@
 diff --git a/package.json b/package.json
-index b2b7bc4..1d6cab3 100644
+index b2b7bc46f632597afdc1104ddc701ab5c3aa3eb3..1d6cab340858046f4d112e39d0f2eaed47410002 100644
 --- a/package.json
 +++ b/package.json
 @@ -348,6 +348,7 @@
@@ -11,7 +11,7 @@ index b2b7bc4..1d6cab3 100644
      "./vite": "./src/vite/index.js"
    }
 diff --git a/src/components/documentation/doc-page-header/doc-page-header.vue b/src/components/documentation/doc-page-header/doc-page-header.vue
-index bd7aee0..bf37ca2 100644
+index bd7aee09c96243e3d40418608c2e3c579a25b309..bf37ca2e51cda1e24ec7fbf790c5bc40a760607f 100644
 --- a/src/components/documentation/doc-page-header/doc-page-header.vue
 +++ b/src/components/documentation/doc-page-header/doc-page-header.vue
 @@ -41,6 +41,10 @@
@@ -53,7 +53,7 @@ index bd7aee0..bf37ca2 100644
          </span>
        </p>
 diff --git a/src/components/documentation/doc-prose/doc-prose.vue b/src/components/documentation/doc-prose/doc-prose.vue
-index 090fd5e..f79ea6d 100644
+index 090fd5e0dad546180edb21b4a6d3cb0dde0dd7b1..f79ea6d19780b927a12f717b60c2c6ee80f1e103 100644
 --- a/src/components/documentation/doc-prose/doc-prose.vue
 +++ b/src/components/documentation/doc-prose/doc-prose.vue
 @@ -1,6 +1,8 @@
@@ -87,7 +87,7 @@ index 090fd5e..f79ea6d 100644
          enter-active-class="animate-popup-scale-in motion-reduce:animate-none"
          leave-active-class="animate-popup-scale-out motion-reduce:animate-none"
 diff --git a/src/components/documentation/doc-step/doc-step.vue b/src/components/documentation/doc-step/doc-step.vue
-index 6c963f0..640d2cf 100644
+index 6c963f0ac90595a07c58e83cb9e88c654c7dfdd8..640d2cf523441a631709ea03633e1e594e13a04a 100644
 --- a/src/components/documentation/doc-step/doc-step.vue
 +++ b/src/components/documentation/doc-step/doc-step.vue
 @@ -1,7 +1,7 @@
@@ -135,7 +135,7 @@ index 6c963f0..640d2cf 100644
          data-step-connector
          class="w-px flex-1 bg-(--border-default)"
 diff --git a/src/components/documentation/doc-steps/doc-steps.vue b/src/components/documentation/doc-steps/doc-steps.vue
-index bedd592..291587d 100644
+index bedd592536501fe4bb7cec496784b1a40020e7ed..291587d3cf4f29ddd875eb9f7a88ae2a6ece41b8 100644
 --- a/src/components/documentation/doc-steps/doc-steps.vue
 +++ b/src/components/documentation/doc-steps/doc-steps.vue
 @@ -46,6 +46,7 @@
@@ -146,8 +146,38 @@ index bedd592..291587d 100644
      :data-testid="testId"
      class="flex w-full flex-col items-start"
    >
+diff --git a/src/components/layout/sidebar/sidebar.vue b/src/components/layout/sidebar/sidebar.vue
+index fd51d19623ddc9940b10fa338fb4e42e41487ed1..a8943e38d42fdbf6732ffc4547bdbd55afb0ca19 100644
+--- a/src/components/layout/sidebar/sidebar.vue
++++ b/src/components/layout/sidebar/sidebar.vue
+@@ -157,16 +157,17 @@
+     INNER_MOTION_CLASS
+   )
+ 
+-  const FOOTER_REGION_CLASS = 'w-full shrink-0 px-(--spacing-md) pb-(--spacing-md)'
++  // The footer is a bar, not a padded block: one row at the header's own height, so
++  // the rail ends on the same baseline the top bar starts on. The rule belongs to the
++  // region (full-bleed across the rail); the band inside it only lays the row out.
++  const FOOTER_REGION_CLASS =
++    'flex h-(--size-14) w-full shrink-0 items-center border-t border-(--border-default) px-(--spacing-md)'
+ 
+   const footerBandClass = computed(() =>
+-    props.collapsible
+-      ? cn(
+-          'flex items-center gap-(--spacing-xs)',
+-          'border-t border-(--border-muted) pt-(--spacing-md)',
+-          !slots['footer'] ? 'justify-end' : undefined
+-        )
+-      : undefined
++    cn(
++      'flex min-w-0 flex-1 items-center gap-(--spacing-xs)',
++      props.collapsible && !slots['footer'] ? 'justify-end' : undefined
++    )
+   )
+ 
+   const scrollClass = computed(() =>
 diff --git a/src/components/navigation/dropdown/dropdown.vue b/src/components/navigation/dropdown/dropdown.vue
-index 91e42e8..0a3cba6 100644
+index 91e42e8da0ac60a784937bc248d70b620e669510..0a3cba6d2193fcdb8a210c278dd67105dd0a9748 100644
 --- a/src/components/navigation/dropdown/dropdown.vue
 +++ b/src/components/navigation/dropdown/dropdown.vue
 @@ -12,6 +12,7 @@
@@ -180,7 +210,7 @@ index 91e42e8..0a3cba6 100644
          enter-active-class="animate-popup-scale-in motion-reduce:animate-none"
          leave-active-class="animate-popup-scale-out motion-reduce:animate-none"
 diff --git a/src/components/navigation/menu/menu-sub-trigger/menu-sub-trigger.vue b/src/components/navigation/menu/menu-sub-trigger/menu-sub-trigger.vue
-index 6b29257..ec17332 100644
+index 6b29257f9aa685228948543b717e680aa7e6abaf..ec17332390bf1e1a4f17e1a3ec5e740100789099 100644
 --- a/src/components/navigation/menu/menu-sub-trigger/menu-sub-trigger.vue
 +++ b/src/components/navigation/menu/menu-sub-trigger/menu-sub-trigger.vue
 @@ -62,8 +62,9 @@
@@ -196,7 +226,7 @@ index 6b29257..ec17332 100644
    // Names the arrow: an inline arrow names the disclosure state, a drill arrow names the level it opens.
    const arrowAriaLabel = computed(() => {
 diff --git a/src/components/navigation/tab-view/tab-view-panel.vue b/src/components/navigation/tab-view/tab-view-panel.vue
-index 607875d..f8fd34b 100644
+index 607875d360f1e8fca6f6bef35dffbccac38a087c..f8fd34bd6f6652d5301ae3c9c6b8ad377f3d2778 100644
 --- a/src/components/navigation/tab-view/tab-view-panel.vue
 +++ b/src/components/navigation/tab-view/tab-view-panel.vue
 @@ -69,6 +69,10 @@
@@ -211,7 +241,7 @@ index 607875d..f8fd34b 100644
          motionReady.value = true
        })
 diff --git a/src/components/overlay/tooltip/tooltip.vue b/src/components/overlay/tooltip/tooltip.vue
-index bc46309..2a57369 100644
+index bc46309e6fd6c3734f59c7338770e02d09012eb0..2a57369713bd76f09c83cb17b806d567a5d3494e 100644
 --- a/src/components/overlay/tooltip/tooltip.vue
 +++ b/src/components/overlay/tooltip/tooltip.vue
 @@ -2,6 +2,7 @@
@@ -245,7 +275,7 @@ index bc46309..2a57369 100644
        leave-active-class="animate-popup-scale-out motion-reduce:animate-none"
 diff --git a/src/composables/use-mounted/index.ts b/src/composables/use-mounted/index.ts
 new file mode 100644
-index 0000000..c4816ed
+index 0000000000000000000000000000000000000000..c4816edb01a52d096d2e917156b831b855dedfb7
 --- /dev/null
 +++ b/src/composables/use-mounted/index.ts
 @@ -0,0 +1,22 @@
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 91b44dd60e..777aff9eb0 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -5,7 +5,7 @@ settings:
   excludeLinksFromLockfile: false
 
 patchedDependencies:
-  '@aziontech/webkit@5.0.0': 685dcce2e0fc35723ffe3ad74610e97ea9420d875d89b2bb0c554fec6b126f9d
+  '@aziontech/webkit@5.0.0': c802272627b578d3409127445a41bf6053e097155dfb3f3c5d0deeba44c3bad8
 
 importers:
 
@@ -22,7 +22,7 @@ importers:
         version: 5.0.0
       '@aziontech/webkit':
         specifier: 5.0.0
-        version: 5.0.0(patch_hash=685dcce2e0fc35723ffe3ad74610e97ea9420d875d89b2bb0c554fec6b126f9d)(eslint@9.39.5(jiti@2.7.0)(supports-color@7.2.0))(stylelint@16.26.1(supports-color@7.2.0)(typescript@5.9.3))(supports-color@7.2.0)(vue-eslint-parser@10.4.1(eslint@9.39.5(jiti@2.7.0)(supports-color@7.2.0))(supports-color@7.2.0))(vue@3.5.42(typescript@5.9.3))
+        version: 5.0.0(patch_hash=c802272627b578d3409127445a41bf6053e097155dfb3f3c5d0deeba44c3bad8)(eslint@9.39.5(jiti@2.7.0)(supports-color@7.2.0))(stylelint@16.26.1(supports-color@7.2.0)(typescript@5.9.3))(supports-color@7.2.0)(vue-eslint-parser@10.4.1(eslint@9.39.5(jiti@2.7.0)(supports-color@7.2.0))(supports-color@7.2.0))(vue@3.5.42(typescript@5.9.3))
       '@babel/types':
         specifier: ^7.22.19
         version: 7.29.8
@@ -5708,7 +5708,7 @@ snapshots:
 
   '@aziontech/theme@5.0.0': {}
 
-  '@aziontech/webkit@5.0.0(patch_hash=685dcce2e0fc35723ffe3ad74610e97ea9420d875d89b2bb0c554fec6b126f9d)(eslint@9.39.5(jiti@2.7.0)(supports-color@7.2.0))(stylelint@16.26.1(supports-color@7.2.0)(typescript@5.9.3))(supports-color@7.2.0)(vue-eslint-parser@10.4.1(eslint@9.39.5(jiti@2.7.0)(supports-color@7.2.0))(supports-color@7.2.0))(vue@3.5.42(typescript@5.9.3))':
+  '@aziontech/webkit@5.0.0(patch_hash=c802272627b578d3409127445a41bf6053e097155dfb3f3c5d0deeba44c3bad8)(eslint@9.39.5(jiti@2.7.0)(supports-color@7.2.0))(stylelint@16.26.1(supports-color@7.2.0)(typescript@5.9.3))(supports-color@7.2.0)(vue-eslint-parser@10.4.1(eslint@9.39.5(jiti@2.7.0)(supports-color@7.2.0))(supports-color@7.2.0))(vue@3.5.42(typescript@5.9.3))':
     dependencies:
       '@aziontech/theme': 4.3.1
       '@modelcontextprotocol/sdk': 1.30.0(supports-color@7.2.0)(zod@3.25.76)
diff --git a/src/components/Footer.vue b/src/components/Footer.vue
index 3295254d63..d2d4dabc43 100644
--- a/src/components/Footer.vue
+++ b/src/components/Footer.vue
@@ -42,7 +42,6 @@
 
 			<template #language>
 				<slot name="action" />
-				<slot name="theme-switch" />
 			</template>
 		</Footer>
 	</div>
@@ -89,8 +88,6 @@ defineSlots<{
 	'system-status'(): unknown;
 	/** The language switcher. */
 	action(): unknown;
-	/** The light/dark control. */
-	'theme-switch'(): unknown;
 }>();
 
 // The treatment every other brand redirect in the app carries: hover opacity, focus ring.
diff --git a/src/components/webkit/DocsSidebar.vue b/src/components/webkit/DocsSidebar.vue
index 5d0a2dad8b..72c8ff74c9 100644
--- a/src/components/webkit/DocsSidebar.vue
+++ b/src/components/webkit/DocsSidebar.vue
@@ -1,8 +1,4 @@
 <template>
-	<!-- eslint-disable webkit/no-style-override -- `--rail-w` IS the collapse
-	     mechanism: the computed style drives the width the rail animates to, and
-	     the class is what consumes it. Composing this inside a slot is not
-	     possible, so the override stays, deliberately and in one place. -->
 	<Sidebar
 		ref="sidebarRef"
 		v-model:collapsed="collapsed"
@@ -10,8 +6,6 @@
 		resizable
 		collapsible
 		:aria-label="ariaLabel"
-		class="h-full w-(--rail-w)"
-		:style="railWidthStyle"
 	>
 		<DocsSidebarMenu
 			presentation
@@ -21,14 +15,19 @@
 			:filter="filter"
 			:no-matches-label="noMatchesLabel"
 		/>
+
+		<template #footer>
+			<DropdownThemeSwitcher />
+		</template>
 	</Sidebar>
 </template>
 
 <script setup lang="ts">
 import Sidebar from '@aziontech/webkit/sidebar';
-import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import { nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue';
 
 import DocsSidebarMenu from './DocsSidebarMenu.vue';
+import DropdownThemeSwitcher from './DropdownThemeSwitcher.vue';
 
 import type { MenuGroupNode, SidebarHeader as SidebarHeaderModel } from '~/nav/resolve';
 
@@ -62,14 +61,6 @@ const width = ref<number | null>(null);
 /** The webkit `Sidebar` instance; only its `measure()` affordance is used. */
 const sidebarRef = ref<{ measure?: () => void } | null>(null);
 
-const railWidthStyle = computed(() => ({
-	'--rail-w': collapsed.value
-		? '0px'
-		: width.value != null
-		? `${width.value}px`
-		: 'var(--container-xs)',
-}));
-
 const railQuery = typeof window !== 'undefined' ? window.matchMedia('(min-width: 1024px)') : null;
 const isRail = ref(false);
 const remeasure = () => {
diff --git a/src/components/webkit/DropdownThemeSwitcher.vue b/src/components/webkit/DropdownThemeSwitcher.vue
index cee93969e7..529e9241c1 100644
--- a/src/components/webkit/DropdownThemeSwitcher.vue
+++ b/src/components/webkit/DropdownThemeSwitcher.vue
@@ -1,7 +1,5 @@
 <template>
-	<span class="inline-flex h-8 items-center">
-		<ThemeSwitcher v-model:value="mode" aria-label="Theme" />
-	</span>
+	<ThemeSwitcher v-model:value="mode" aria-label="Theme" />
 </template>
 
 <script setup>
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index 32b126b331..6f815edcc3 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -18,7 +18,6 @@ import HeaderRightSidebar from '~/components/webkit/HeaderRightSidebar.vue';
 import DocsTopNav from '~/components/webkit/DocsTopNav.vue';
 import SystemStatus from '~/components/webkit/SystemStatus.vue';
 import SelectLang from '~/components/webkit/SelectLang.vue';
-import ThemeSwitcher from '~/components/webkit/DropdownThemeSwitcher.vue';
 
 import { getLanguageFromURL, normalizeCanonicalPath } from '~/util';
 // import { getPageCategory } from '~/util/getPageCategory';
@@ -220,9 +219,6 @@ const translatedPages = await (async (c) => {
 					<Fragment slot="system-status">
 						<SystemStatus {lang} client:visible={{ rootMargin: '600px' }} />
 					</Fragment>
-					<Fragment slot="theme-switch">
-						<ThemeSwitcher client:visible={{ rootMargin: '600px' }} />
-					</Fragment>
 				</Footer>
 			</div>
 

From 631575a59921ab5434b86c536678c7cdc9b0b631 Mon Sep 17 00:00:00 2001
From: Bruno Germano <bruno.germano@gmail.com>
Date: Fri, 11 Sep 2026 18:59:39 -0300
Subject: [PATCH 4/8] feat(guides): render the catalog's loading, error and
 empty states

The catalog only ever drew its happy path. It now covers the full state
surface: a Skeleton card grid while the 351 rows resolve, an error
Message with a retry action, and an EmptyState that explains what to try
next instead of stating the negative and stopping.

Adds the four strings each state needs, in both published languages.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/components/GuidesHomeSection.astro |   4 +
 src/components/webkit/GuidesHome.vue   | 440 +++++++++++++++++--------
 src/i18n/en/ui.ts                      |   4 +
 src/i18n/pt-br/ui.ts                   |   4 +
 4 files changed, 321 insertions(+), 131 deletions(-)

diff --git a/src/components/GuidesHomeSection.astro b/src/components/GuidesHomeSection.astro
index 4a44c55af2..26456a10e5 100644
--- a/src/components/GuidesHomeSection.astro
+++ b/src/components/GuidesHomeSection.astro
@@ -31,6 +31,10 @@ const labels = {
 	countMany: t('guides.count.many'),
 	clear: t('guides.clear'),
 	empty: t('guides.empty'),
+	emptyHint: t('guides.emptyHint'),
+	error: t('guides.error'),
+	retry: t('guides.retry'),
+	loading: t('guides.loading'),
 	pagination: t('guides.pagination'),
 	previous: t('guides.previous'),
 	next: t('guides.next'),
diff --git a/src/components/webkit/GuidesHome.vue b/src/components/webkit/GuidesHome.vue
index ceb735a23f..59454a5b0c 100644
--- a/src/components/webkit/GuidesHome.vue
+++ b/src/components/webkit/GuidesHome.vue
@@ -1,65 +1,115 @@
 <template>
-	<div class="grid items-start gap-(--spacing-lg) lg:grid-cols-[15rem_1fr]">
+	<div
+		v-bind="$attrs"
+		:data-testid="testId"
+		class="grid items-start gap-(--spacing-xl) lg:grid-cols-[var(--container-3xs)_1fr]"
+	>
+		<!-- The page's only navigation — DocsDirectoryLayout drops the docs rail for it. Sticky
+		     and internally scrolled, which clips a focus ring (3px outside its checkbox) and
+		     squeezes a count against the scrollbar: the `-m`/`p` pair buys that clearance
+		     without moving the content off the page's left boundary, and `top` matches it. -->
 		<aside
 			:aria-label="labels.filters"
-			class="flex flex-col gap-(--spacing-md) lg:sticky lg:top-18 lg:max-h-[calc(100vh-5rem)] lg:overflow-y-auto lg:[scrollbar-width:thin] lg:[scrollbar-color:var(--border-muted)_transparent]"
+			class="flex flex-col gap-(--spacing-lg) lg:sticky lg:top-[calc(var(--spacing-14)+var(--spacing-xs))] lg:-m-(--spacing-xs) lg:max-h-[calc(100dvh-var(--spacing-14))] lg:overflow-y-auto lg:overscroll-contain lg:p-(--spacing-xs) lg:pb-(--spacing-xl) lg:[scrollbar-color:var(--border-muted)_transparent] lg:[scrollbar-width:thin]"
 		>
 			<InputText
 				v-model="query"
-				type="search"
 				size="medium"
 				:placeholder="labels.search"
 				:aria-label="labels.search"
 			>
+				<!-- The slot wrapper already carries `aria-hidden` and the muted token, and
+				     `type="search"` is not one of InputText's declared values — the field is a
+				     plain text input and `Clear filters` is the way back to everything. -->
 				<template #iconLeft>
-					<i class="pi pi-search text-body-sm" aria-hidden="true" />
+					<i class="pi pi-search" />
 				</template>
 			</InputText>
 
-			<fieldset class="m-0 flex flex-col gap-(--spacing-xs) border-0 p-0">
-				<legend class="mb-(--spacing-xs) p-0 text-overline-sm text-(--text-muted)">
-					{{ labels.contentType }}
-				</legend>
-				<label
-					v-for="kind in kinds"
-					:key="kind"
-					class="flex cursor-pointer items-center gap-(--spacing-xs) text-label-sm text-(--text-default)"
-				>
-					<Checkbox
-						binary
-						:model-value="kindsOn.includes(kind)"
-						@update:model-value="toggleKind(kind, Boolean($event))"
-					/>
-					<span>{{ labels.kinds[kind] ?? kind }}</span>
-					<span class="text-body-xs text-(--text-muted)">{{ totals.kinds[kind] ?? 0 }}</span>
-				</label>
-			</fieldset>
-
-			<fieldset v-if="products.length" class="m-0 flex flex-col gap-(--spacing-xs) border-0 p-0">
-				<legend class="mb-(--spacing-xs) p-0 text-overline-sm text-(--text-muted)">
-					{{ labels.topics }}
-				</legend>
-				<label
-					v-for="product in products"
-					:key="product.id"
-					class="flex cursor-pointer items-center gap-(--spacing-xs) text-label-sm text-(--text-default)"
-				>
-					<Checkbox
-						binary
-						:model-value="productsOn.includes(product.id)"
-						@update:model-value="toggleProduct(product.id, Boolean($event))"
-					/>
-					<span>{{ product.label }}</span>
-					<span class="text-body-xs text-(--text-muted)">{{
-						totals.products[product.id] ?? 0
-					}}</span>
-				</label>
-			</fieldset>
+			<!-- Below `lg` the facets are a disclosure: stacked open on a phone, thirty-odd
+			     checkboxes sit between the reader and the first guide. The toggle exists only
+			     there (`lg:hidden` on the wrapper, never on the Button), and `wide` starts true
+			     so the server — and a browser with no JS — keeps the open shape. -->
+			<div ref="facetsToggle" class="lg:hidden">
+				<Button
+					kind="secondary"
+					size="medium"
+					icon="pi pi-filter"
+					:label="labels.filters"
+					@click="facetsOpen = !facetsOpen"
+				/>
+			</div>
+
+			<!-- `v-if`, not `v-show`: Tailwind is imported in `important` mode here, so the
+			     `flex` utility on this element wins over the inline `display: none` that
+			     `v-show` writes and the panel never actually hides. -->
+			<Transition
+				enter-active-class="animate-slide-down motion-reduce:animate-none"
+				leave-active-class="animate-fade-out motion-reduce:animate-none"
+			>
+				<div v-if="facetsVisible" :id="facetsId" class="flex flex-col gap-(--spacing-lg)">
+					<!-- One content column: legend, checkbox and count start on the same x. No
+					     optical inset — no card sits below these titles to line up with. -->
+					<fieldset class="m-0 flex flex-col gap-(--spacing-xs) border-0 p-0">
+						<legend class="mb-(--spacing-xs) p-0 text-heading-xxs text-(--text-default)">
+							{{ labels.contentType }}
+						</legend>
+						<label
+							v-for="kind in kinds"
+							:key="kind"
+							class="flex cursor-pointer items-center gap-(--spacing-xs) text-label-sm text-(--text-default)"
+						>
+							<Checkbox
+								binary
+								:model-value="kindsOn.includes(kind)"
+								@update:model-value="toggleKind(kind, Boolean($event))"
+							/>
+							<span class="min-w-0 flex-1 truncate">{{ labels.kinds[kind] ?? kind }}</span>
+							<span class="shrink-0 text-body-xs tabular-nums text-(--text-muted)">{{
+								totals.kinds[kind] ?? 0
+							}}</span>
+						</label>
+					</fieldset>
+
+					<fieldset
+						v-if="products.length"
+						class="m-0 flex flex-col gap-(--spacing-xs) border-0 p-0"
+					>
+						<legend class="mb-(--spacing-xs) p-0 text-heading-xxs text-(--text-default)">
+							{{ labels.topics }}
+						</legend>
+						<label
+							v-for="product in products"
+							:key="product.id"
+							class="flex cursor-pointer items-center gap-(--spacing-xs) text-label-sm text-(--text-default)"
+						>
+							<Checkbox
+								binary
+								:model-value="productsOn.includes(product.id)"
+								@update:model-value="toggleProduct(product.id, Boolean($event))"
+							/>
+							<span class="min-w-0 flex-1 truncate">{{ product.label }}</span>
+							<span class="shrink-0 text-body-xs tabular-nums text-(--text-muted)">
+								{{ totals.products[product.id] ?? 0 }}
+							</span>
+						</label>
+					</fieldset>
+				</div>
+			</Transition>
 		</aside>
 
-		<section class="flex min-w-0 flex-col gap-(--spacing-sm)">
-			<div class="flex items-center justify-between gap-(--spacing-sm)">
-				<p class="text-body-sm text-(--text-muted)" aria-live="polite">
+		<!-- One band, joined by the GROUP step: the count row, the grid and the paginator are
+		     a set and two readings of it, not three stacked blocks. -->
+		<section
+			ref="results"
+			:data-loading="pending || null"
+			class="flex min-w-0 scroll-mt-(--spacing-14) flex-col gap-(--layout-group-gap)"
+		>
+			<div class="flex min-h-(--size-8) items-center justify-between gap-(--spacing-sm)">
+				<!-- While the catalog is in flight the only rows here are the first page, so a
+				     count would be a number the page cannot yet stand behind. It waits. -->
+				<Skeleton v-if="pending" width="var(--container-3xs)" height="0.875rem" />
+				<p v-else class="text-body-sm text-(--text-muted)" aria-live="polite">
 					{{ countLabel }}
 				</p>
 				<Button
@@ -71,8 +121,31 @@
 				/>
 			</div>
 
-			<div v-if="visible.length" ref="results" class="flex flex-col gap-(--spacing-md)">
-				<DocCardGroup :cols="2">
+			<!-- A banner, not a replacement: the first page came down with the document and is
+			     still worth reading — only the rest of the catalog is missing. -->
+			<Message
+				v-if="failed"
+				severity="error"
+				:label="labels.error"
+				:action-label="labels.retry"
+				@action="retry"
+			/>
+
+			<!-- Until the catalog lands only the first page is in the browser, so a filter
+			     typed early could narrow 24 of 351 rows. The skeleton is what stops the page
+			     from answering that question wrongly. -->
+			<DocCardGroup v-if="pending" :cols="3" :aria-busy="true" :aria-label="labels.loading">
+				<DocCard v-for="index in SKELETONS" :key="index">
+					<div class="flex flex-col gap-(--spacing-sm)">
+						<Skeleton width="40%" height="0.75rem" />
+						<Skeleton width="80%" height="1.25rem" />
+						<Skeleton height="0.875rem" />
+					</div>
+				</DocCard>
+			</DocCardGroup>
+
+			<template v-else-if="paged.length">
+				<DocCardGroup :cols="3">
 					<DocCard
 						v-for="entry in paged"
 						:key="entry.href"
@@ -91,16 +164,26 @@
 						:disabled="page <= 1"
 						@click="goTo(page - 1)"
 					/>
-					<Paginator.Button
-						v-for="item in pageItems"
-						:key="item.key"
-						:kind="item.type === 'page' ? 'number' : 'more'"
-						:selected="item.type === 'page' && item.value === page"
-						:disabled="item.type === 'more'"
-						@click="item.type === 'page' && goTo(item.value)"
-					>
-						{{ item.type === 'page' ? item.value : '' }}
-					</Paginator.Button>
+					<template v-for="item in pageItems" :key="item.key">
+						<Paginator.Button
+							v-if="item.type === 'page'"
+							kind="number"
+							:selected="item.value === page"
+							@click="goTo(item.value)"
+						>
+							{{ item.value }}
+						</Paginator.Button>
+						<!-- A separator, not a control: webkit's `kind="more"` button renders only an
+						     `aria-hidden` glyph, which is a button with no accessible name. Sized to
+						     the buttons beside it with the component's own `h-7`/`w-10`. -->
+						<span
+							v-else
+							class="inline-flex h-7 w-10 items-center justify-center text-(--text-muted)"
+							aria-hidden="true"
+						>
+							<i class="pi pi-ellipsis-h text-[length:inherit] leading-none" />
+						</span>
+					</template>
 					<Paginator.Button
 						kind="next"
 						:aria-label="labels.next"
@@ -108,14 +191,61 @@
 						@click="goTo(page + 1)"
 					/>
 				</Paginator>
-			</div>
-			<EmptyState v-else :title="labels.empty" icon="pi pi-search" size="small" bordered />
+			</template>
+
+			<EmptyState
+				v-else
+				bordered
+				size="small"
+				icon="pi pi-search"
+				:title="labels.empty"
+				:description="labels.emptyHint"
+			>
+				<template #actions>
+					<Button kind="secondary" size="medium" :label="labels.clear" @click="clear" />
+				</template>
+			</EmptyState>
 		</section>
 	</div>
 </template>
 
 <script lang="ts">
 export const PAGE_SIZE = 24;
+
+/** The four content types the guides tree tags a page with. */
+export type GuideKind = 'learning-path' | 'tutorial' | 'reference-architecture' | 'video';
+
+/** One catalogued page: what it takes to filter it and to draw its card. */
+export interface GuidesEntry {
+	label: string;
+	href: string;
+	description?: string;
+	kind: GuideKind;
+	products: string[];
+	topic: string;
+	external?: boolean;
+}
+
+/** Every string the surface renders, resolved on the server. */
+export interface GuidesLabels {
+	search: string;
+	filters: string;
+	contentType: string;
+	topics: string;
+	kinds: Partial<Record<GuideKind, string>>;
+	countOne: string;
+	countMany: string;
+	clear: string;
+	empty: string;
+	emptyHint: string;
+	error: string;
+	retry: string;
+	loading: string;
+	pagination: string;
+	previous: string;
+	next: string;
+	range: string;
+}
 </script>
 
 <script setup lang="ts">
@@ -125,92 +255,117 @@ import DocCard from '@aziontech/webkit/doc-card';
 import DocCardGroup from '@aziontech/webkit/doc-card-group';
 import EmptyState from '@aziontech/webkit/empty-state';
 import InputText from '@aziontech/webkit/input-text';
+import Message from '@aziontech/webkit/message';
 import Paginator from '@aziontech/webkit/paginator';
-import { computed, onMounted, ref, watch } from 'vue';
+import Skeleton from '@aziontech/webkit/skeleton';
+import { computed, onMounted, onScopeDispose, ref, useAttrs, useId, watch, watchEffect } from 'vue';
 
-type Kind = 'learning-path' | 'tutorial' | 'reference-architecture' | 'video';
+defineOptions({ name: 'GuidesHome', inheritAttrs: false });
 
-interface Entry {
-	label: string;
-	href: string;
-	description?: string;
-	kind: Kind;
-	products: string[];
-	topic: string;
-	external?: boolean;
+/** Placeholder cards drawn while the catalog is in flight — two rows of three is
+ *  enough to read as "loading" without standing in for a screenful of content. */
+const SKELETONS = 6;
+
+interface Props {
+	/** The first page, rendered on the server; the rest of the catalog is fetched from `catalogHref` after mount. */
+	initial?: GuidesEntry[];
+	/** The unfiltered size of the catalog, known on the server before the fetch lands. */
+	total?: number;
+	/** Catalog-wide counts per filter value, so a facet can show its size without the catalog. */
+	totals?: { kinds: Partial<Record<GuideKind, number>>; products: Record<string, number> };
+	/** Where the full catalog is fetched from. */
+	catalogHref?: string;
+	/** Content types present in the catalog, in display order. */
+	kinds?: GuideKind[];
+	/** Topics present in the catalog, in display order. */
+	products?: { id: string; label: string }[];
+	/** Every string the surface renders. */
+	labels?: GuidesLabels;
 }
 
-const props = withDefaults(
-	defineProps<{
-		/** The first page, rendered on the server; the rest of the catalog is fetched from `catalogHref` after mount. */
-		initial?: Entry[];
-		total?: number;
-		totals?: { kinds: Partial<Record<Kind, number>>; products: Record<string, number> };
-		catalogHref?: string;
-		kinds?: Kind[];
-		products?: { id: string; label: string }[];
-		labels?: {
-			search: string;
-			filters: string;
-			contentType: string;
-			topics: string;
-			kinds: Partial<Record<Kind, string>>;
-			countOne: string;
-			countMany: string;
-			clear: string;
-			empty: string;
-			pagination: string;
-			previous: string;
-			next: string;
-			range: string;
-		};
-	}>(),
-	{
-		initial: () => [],
-		total: 0,
-		totals: () => ({ kinds: {}, products: {} }),
-		catalogHref: '',
-		kinds: () => [],
-		products: () => [],
-		labels: () => ({
-			search: 'Search by name or description',
-			filters: 'Filters',
-			contentType: 'Content type',
-			topics: 'Topics',
-			kinds: {},
-			countOne: '{count} page',
-			countMany: '{count} pages',
-			clear: 'Clear filters',
-			empty: 'No pages match your filters.',
-			pagination: 'Pagination',
-			previous: 'Previous page',
-			next: 'Next page',
-			range: 'Showing {start} to {end} of {total}',
-		}),
-	}
-);
+const props = withDefaults(defineProps<Props>(), {
+	initial: () => [],
+	total: 0,
+	totals: () => ({ kinds: {}, products: {} }),
+	catalogHref: '',
+	kinds: () => [],
+	products: () => [],
+	labels: () => ({
+		search: 'Search by name or description',
+		filters: 'Filters',
+		contentType: 'Content type',
+		topics: 'Topics',
+		kinds: {},
+		countOne: '{count} page',
+		countMany: '{count} pages',
+		clear: 'Clear filters',
+		empty: 'No pages match your filters.',
+		emptyHint: 'Try another term, or clear the filters to browse every page.',
+		error: 'The guides catalog could not be loaded.',
+		retry: 'Try again',
+		loading: 'Loading guides',
+		pagination: 'Pagination',
+		previous: 'Previous page',
+		next: 'Next page',
+		range: 'Showing {start} to {end} of {total}',
+	}),
+});
+
+const attrs = useAttrs();
+const testId = computed(() => (attrs['data-testid'] as string) ?? 'documentation-guides-home');
+
+// `lg` — the width at which the rail becomes a column beside the grid instead of a
+// block above it. It starts true so the server renders the open shape: a desktop reader
+// (and anyone without JS) never sees the facets collapse.
+const facetsId = useId();
+const wide = ref(true);
+const facetsOpen = ref(false);
+const facetsVisible = computed(() => wide.value || facetsOpen.value);
+const facetsToggle = ref<HTMLElement | null>(null);
+
+// webkit's Button declares no ARIA props and does not forward attributes, so the
+// disclosure relationship is written onto the control it renders. A toggle that does not
+// say what it controls, or whether that thing is open, is a button with no state to a
+// screen reader. Drop this the day Button carries the attributes itself.
+watchEffect(() => {
+	const control = facetsToggle.value?.querySelector('button');
+	if (!control) return;
+	control.setAttribute('aria-expanded', String(facetsOpen.value));
+	control.setAttribute('aria-controls', facetsId);
+});
 
 const query = ref('');
-const kindsOn = ref<Kind[]>([...props.kinds]);
+const kindsOn = ref<GuideKind[]>([...props.kinds]);
 const productsOn = ref<string[]>([]);
 const page = ref(1);
 const results = ref<HTMLElement | null>(null);
 
-const catalog = ref<Entry[] | null>(null);
+const catalog = ref<GuidesEntry[] | null>(null);
+const failed = ref(false);
 let loading: Promise<void> | null = null;
 
 function loadCatalog(): Promise<void> {
 	loading ??= fetch(props.catalogHref)
-		.then((response) => response.json())
-		.then((rows: Entry[]) => {
+		.then((response) => {
+			if (!response.ok) throw new Error(String(response.status));
+			return response.json();
+		})
+		.then((rows: GuidesEntry[]) => {
 			catalog.value = rows;
+			failed.value = false;
 		})
 		.catch(() => {
+			failed.value = true;
 			loading = null;
 		});
 	return loading;
 }
 
+function retry() {
+	failed.value = false;
+	void loadCatalog();
+}
+
 const entries = computed(() => catalog.value ?? props.initial);
 const totals = computed(() => props.totals);
 
@@ -239,9 +394,17 @@ const filtered = computed(
 		query.value !== '' || productsOn.value.length > 0 || kindsOn.value.length !== props.kinds.length
 );
 
-// Until the catalog arrives only the first page is here, so an unfiltered count comes from the server.
+// Only the first page is in the browser until the catalog lands, so ANY question the
+// first page cannot answer — a filter, or a page past the first — is pending, not empty.
+const pending = computed(
+	() => !catalog.value && !failed.value && (filtered.value || page.value > 1)
+);
+
+// Until the catalog arrives only the first page is here, so an unfiltered count comes
+// from the server — unless it never will arrive, in which case the honest count is the
+// one the page can actually show, and the banner above says why it is short.
 const resultCount = computed(() =>
-	catalog.value || filtered.value ? visible.value.length : props.total
+	catalog.value || filtered.value || failed.value ? visible.value.length : props.total
 );
 
 const countLabel = computed(() =>
@@ -292,17 +455,21 @@ const pageItems = computed<PageItem[]>(() => {
 });
 
 async function goTo(next: number) {
-	await loadCatalog();
 	page.value = Math.min(Math.max(1, next), pageCount.value);
-	const top = results.value?.getBoundingClientRect().top;
-	if (top !== undefined) window.scrollTo({ top: top + window.scrollY - 80, behavior: 'smooth' });
+	await loadCatalog();
+	results.value?.scrollIntoView({
+		block: 'start',
+		behavior: window.matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth',
+	});
 }
 
-function overline(entry: Entry) {
-	return [props.labels.kinds[entry.kind] ?? entry.kind, entry.topic].filter(Boolean).join(' · ');
+// The content type, alone. Pairing it with the topic ran to two uppercase lines above
+// most titles, and the topic is already a facet in the rail and usually in the title.
+function overline(entry: GuidesEntry) {
+	return props.labels.kinds[entry.kind] ?? entry.kind;
 }
 
-function toggleKind(kind: Kind, on: boolean) {
+function toggleKind(kind: GuideKind, on: boolean) {
 	kindsOn.value = props.kinds.filter((each) => (each === kind ? on : kindsOn.value.includes(each)));
 }
 
@@ -345,11 +512,22 @@ function writeUrl() {
 }
 
 onMounted(async () => {
+	// NOT named `query` — that is the search model this file already owns, and shadowing
+	// it here would hand the watchers below a MediaQueryList instead of the search term.
+	const columnWidth = window.matchMedia('(min-width: 64rem)');
+	const syncWidth = () => {
+		wide.value = columnWidth.matches;
+	};
+	syncWidth();
+	columnWidth.addEventListener('change', syncWidth);
+	onScopeDispose(() => columnWidth.removeEventListener('change', syncWidth));
+
 	const load = loadCatalog();
 	if (window.location.search) await load;
 	readUrl();
 	watch([query, kindsOn, productsOn], () => {
 		page.value = 1;
+		void loadCatalog();
 	});
 	watch([query, kindsOn, productsOn, page], writeUrl);
 });
diff --git a/src/i18n/en/ui.ts b/src/i18n/en/ui.ts
index d87946e793..463f2b9ac1 100644
--- a/src/i18n/en/ui.ts
+++ b/src/i18n/en/ui.ts
@@ -21,6 +21,10 @@ export default {
 	'guides.count.many': '{count} pages',
 	'guides.clear': 'Clear filters',
 	'guides.empty': 'No pages match your filters.',
+	'guides.emptyHint': 'Try another term, or clear the filters to browse every page.',
+	'guides.error': 'The guides catalog could not be loaded.',
+	'guides.retry': 'Try again',
+	'guides.loading': 'Loading guides',
 	'guides.pagination': 'Pagination',
 	'guides.previous': 'Previous page',
 	'guides.next': 'Next page',
diff --git a/src/i18n/pt-br/ui.ts b/src/i18n/pt-br/ui.ts
index 6133c24597..2bef70f190 100644
--- a/src/i18n/pt-br/ui.ts
+++ b/src/i18n/pt-br/ui.ts
@@ -23,6 +23,10 @@ export default UIDictionary({
 	'guides.count.many': '{count} páginas',
 	'guides.clear': 'Limpar filtros',
 	'guides.empty': 'Nenhuma página corresponde aos filtros.',
+	'guides.emptyHint': 'Tente outro termo ou limpe os filtros para ver todas as páginas.',
+	'guides.error': 'Não foi possível carregar o catálogo de guias.',
+	'guides.retry': 'Tentar novamente',
+	'guides.loading': 'Carregando guias',
 	'guides.pagination': 'Paginação',
 	'guides.previous': 'Página anterior',
 	'guides.next': 'Próxima página',

From ea4d741a9e22ca30d832fea7b69ca12a3e4eb208 Mon Sep 17 00:00:00 2001
From: Bruno Germano <bruno.germano@gmail.com>
Date: Fri, 11 Sep 2026 19:00:02 -0300
Subject: [PATCH 5/8] feat(guides): give the hub its own directory layout

The guides hub is a catalog, not a document, but it was rendering in the
reading shell: a docs rail beside a page that already carries its own
filter column, an "On this page" outline over a card grid, and a prose
measure the grid must not take.

Adds DocsDirectoryLayout, selected by namespace the way pricing already
is, so both language editions switch together. BaseLayout grows a
`primarySidebar` prop to suppress the rail; the hub draws the docs home's
masthead instead, taking its lede from the page's own MDX so the sentence
and its link stay in the file a translator edits.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/components/GuidesHomeSection.astro        | 28 ++++++++++++
 src/content/docs/en/pages/guides/index.mdx    |  4 +-
 src/content/docs/pt-br/pages/guias/guides.mdx |  4 +-
 src/layouts/BaseLayout.astro                  | 25 ++++++++---
 src/layouts/DocsDirectoryLayout.astro         | 44 +++++++++++++++++++
 src/layouts/LayoutSwitcher.astro              | 10 +++++
 6 files changed, 105 insertions(+), 10 deletions(-)
 create mode 100644 src/layouts/DocsDirectoryLayout.astro

diff --git a/src/components/GuidesHomeSection.astro b/src/components/GuidesHomeSection.astro
index 26456a10e5..c4cd486eb5 100644
--- a/src/components/GuidesHomeSection.astro
+++ b/src/components/GuidesHomeSection.astro
@@ -1,10 +1,20 @@
 ---
+/** The guides DIRECTORY: a masthead band, then the catalog band. */
+// The masthead is the docs home's, rung for rung — the two hubs are the same kind of page.
+// The reading chrome a doc page carries (breadcrumb, last-updated, Copy as Markdown, Agent
+// setup) is deliberately absent: none of it describes a catalog.
 import { getLanguageFromURL } from '~/util';
 import { useTranslations } from '~/i18n/util';
 import type { Lang } from '~/nav/index';
 import { guidesCatalog, guidesCatalogHref } from '~/util/guidesCatalog';
 import GuidesHome, { PAGE_SIZE } from '~/components/webkit/GuidesHome.vue';
 
+interface Props {
+	/** The page's own heading; falls back to the catalogue's name. */
+	title: string;
+}
+
+const { title } = Astro.props;
 const lang = getLanguageFromURL(Astro.url.pathname) as Lang;
 const t = useTranslations(Astro);
 const { rows, kinds, products } = await guidesCatalog(lang);
@@ -42,6 +52,24 @@ const labels = {
 };
 ---
 
+{
+	/*
+	  The lede comes from the page's own MDX so the sentence — and the link inside it —
+	  stays in the file a translator edits. `[&_p]:m-0` is what lets it arrive as a
+	  paragraph without opening a second margin under the one this header already sets.
+	*/
+}
+<header class="mb-(--spacing-xxl) sm:mb-16">
+	<h1 class="m-0 max-w-(--container-2xl) text-balance text-heading-2xl text-(--text-default)">
+		{title}
+	</h1>
+	<div
+		class="mt-(--spacing-lg) max-w-(--container-xl) text-pretty text-body-lg leading-relaxed text-(--text-muted) [&_a:hover]:text-(--text-link-hover) [&_a]:text-(--text-link-color) [&_a]:underline [&_a]:underline-offset-2 [&_p]:m-0"
+	>
+		<slot />
+	</div>
+</header>
+
 <GuidesHome
 	client:load
 	initial={rows.slice(0, PAGE_SIZE)}
diff --git a/src/content/docs/en/pages/guides/index.mdx b/src/content/docs/en/pages/guides/index.mdx
index 3ebee86244..0122a8865a 100644
--- a/src/content/docs/en/pages/guides/index.mdx
+++ b/src/content/docs/en/pages/guides/index.mdx
@@ -10,6 +10,6 @@ permalink: /documentation/guides/
 
 import GuidesHomeSection from '~/components/GuidesHomeSection.astro';
 
+<GuidesHomeSection title="Guides">
 Every learning path, tutorial, reference architecture and video for the Azion Web Platform, in one place. Filter by content type or topic, or search by name. Videos come from the [Azion channel on YouTube](https://www.youtube.com/@aziontech) and open there.
-
-<GuidesHomeSection />
+</GuidesHomeSection>
diff --git a/src/content/docs/pt-br/pages/guias/guides.mdx b/src/content/docs/pt-br/pages/guias/guides.mdx
index 2fed203466..7325850cb5 100644
--- a/src/content/docs/pt-br/pages/guias/guides.mdx
+++ b/src/content/docs/pt-br/pages/guias/guides.mdx
@@ -8,6 +8,6 @@ permalink: /documentacao/guias/
 
 import GuidesHomeSection from '~/components/GuidesHomeSection.astro';
 
+<GuidesHomeSection title="Guias">
 Todas as trilhas de aprendizado, tutoriais, arquiteturas de referência e vídeos da Azion Web Platform, em um só lugar. Filtre por tipo de conteúdo ou tópico, ou busque pelo nome. Os vídeos vêm do [canal da Azion no YouTube](https://www.youtube.com/@aziontech) e abrem lá.
-
-<GuidesHomeSection />
+</GuidesHomeSection>
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index 6f815edcc3..35f3379b94 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -30,12 +30,18 @@ import { useTranslations } from '~/i18n/util';
 
 export interface Props {
 	content: CollectionEntry<'docs'>['data'];
+	/**
+	 * Set false by a layout whose page is its own directory — the guides hub — so the
+	 * docs navigation rail is not drawn beside it. The rail still reaches those pages
+	 * through the mobile menu, which is the only place it lives under `lg`.
+	 */
+	primarySidebar?: boolean;
 }
 
 import '@aziontech/icons';
 import '~/styles/main.css';
 
-const { content } = Astro.props;
+const { content, primarySidebar = true } = Astro.props;
 // A layout that fills `secondary-sidebar` gets the rail and the third grid track;
 // one that does not (the docs home) gets neither, so no dead gutter is reserved.
 const hasSecondarySidebar = Astro.slots.has('secondary-sidebar');
@@ -194,11 +200,18 @@ const translatedPages = await (async (c) => {
 			     columns off from a rule that already separates them. `shrink-0` because the
 			     rail's width is the Sidebar's to decide (seeded at --container-2xs, then
 			     driven by its drag handle and collapse). -->
-			<aside id="left-sidebar" class="hidden shrink-0 lg:block">
-				<div class={SIDEBAR_COLUMN}>
-					<LeftSidebar sidebar={sidebar} />
-				</div>
-			</aside>
+			{
+				/* A page that IS the directory does not get the directory beside it —
+				   the guides hub owns the whole content width, so no rail and no
+				   hairline are drawn where its own filter column starts. */
+				primarySidebar && (
+					<aside id="left-sidebar" class="hidden shrink-0 lg:block">
+						<div class={SIDEBAR_COLUMN}>
+							<LeftSidebar sidebar={sidebar} />
+						</div>
+					</aside>
+				)
+			}
 
 			<div id="main-content" class="flex min-h-0 min-w-0 flex-1 flex-col">
 				<slot />
diff --git a/src/layouts/DocsDirectoryLayout.astro b/src/layouts/DocsDirectoryLayout.astro
new file mode 100644
index 0000000000..7cceb1c4c0
--- /dev/null
+++ b/src/layouts/DocsDirectoryLayout.astro
@@ -0,0 +1,44 @@
+---
+/** The layout for a DIRECTORY page — a page that IS a catalog, not a document. */
+// Three pieces of the reading shell are wrong for one, and each is dropped here: the docs
+// rail (`primarySidebar={false}` — the page's own filter column is the navigation), the
+// "On this page" outline (no `secondary-sidebar` slot, so no third track is reserved), and
+// `PageContent`'s prose measure (4xl, the one width a card grid must not take). The docs
+// container stays, so the shell holds under the first link out. The closing prev/next pair
+// does not: it walks a reading SEQUENCE, and a catalog is the thing you pick from, not a
+// page in one — "Next page" under 351 cards names a neighbour nobody was reading toward.
+import type { MarkdownHeading } from 'astro';
+import type { CollectionEntry } from 'astro:content';
+
+import BaseLayout from '~/layouts/BaseLayout.astro';
+
+import { normalizeLangTag } from '~/i18n/bcp-normalize';
+import { rtlLanguages } from '~/i18n/languages';
+import { getLanguageFromURL } from '~/util';
+import type { Lang } from '~/nav/index';
+
+export interface Props {
+	content: CollectionEntry<'docs'>['data'];
+	headings?: MarkdownHeading[];
+	id?: String;
+	/** Set by pages outside the `docs` collection, for the GitHub edit link. */
+	editFilePath?: string;
+}
+
+/** The docs home's column, to the pixel — the two hubs open on the same measure. */
+const COLUMN = 'layout-boundary-inline mx-auto w-full max-w-(--layout-measure-site)';
+
+const lang = getLanguageFromURL(Astro.url.pathname) as Lang;
+const direction = rtlLanguages.has(lang) ? 'rtl' : 'ltr';
+const bcpLang = normalizeLangTag(lang);
+---
+
+<BaseLayout {...Astro.props} primarySidebar={false}>
+	<div dir={direction} lang={bcpLang}>
+		<article class="pb-(--spacing-16) sm:pb-(--spacing-24)">
+			<section class:list={[COLUMN, 'pt-(--spacing-16) sm:pt-(--spacing-24)']}>
+				<slot />
+			</section>
+		</article>
+	</div>
+</BaseLayout>
diff --git a/src/layouts/LayoutSwitcher.astro b/src/layouts/LayoutSwitcher.astro
index 1ff4b3e3e6..246a69871e 100644
--- a/src/layouts/LayoutSwitcher.astro
+++ b/src/layouts/LayoutSwitcher.astro
@@ -2,6 +2,7 @@
 import type { MarkdownHeading } from 'astro';
 import type { CollectionEntry } from 'astro:content';
 import MainLayout from '~/layouts/MainLayout.astro';
+import DocsDirectoryLayout from './DocsDirectoryLayout.astro';
 import HomepageLayout from './HomepageLayout.astro';
 import PricingLayout from './PricingLayout.astro';
 
@@ -15,6 +16,11 @@ const { data, headings, id } = Astro.props;
 
 // Check if this is a pricing page by namespace
 const isPricingPage = data.namespace === 'documentation_pricing';
+// The guides hub is a CATALOG, not a document: it carries its own filter column and a
+// card grid, so it takes the directory shell (no docs rail, no outline, no prose
+// measure) instead of the reading one. Keyed off the namespace, like pricing above, so
+// both language editions of the page switch together.
+const isDirectoryPage = data.namespace === 'documentation_how_to';
 ---
 
 {
@@ -26,6 +32,10 @@ const isPricingPage = data.namespace === 'documentation_pricing';
 		<PricingLayout content={data} headings={headings} id={id}>
 			<slot />
 		</PricingLayout>
+	) : isDirectoryPage ? (
+		<DocsDirectoryLayout content={data} headings={headings} id={id}>
+			<slot />
+		</DocsDirectoryLayout>
 	) : (
 		<MainLayout content={data} headings={headings} id={id}>
 			<slot />

From 64f3e6d0b7c9b3369b5b627da691d1901b327ab9 Mon Sep 17 00:00:00 2001
From: Bruno Germano <bruno.germano@gmail.com>
Date: Fri, 11 Sep 2026 19:00:16 -0300
Subject: [PATCH 6/8] refactor(layout): take the docs home's spacing from theme
 tokens
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The section step was written as bare Tailwind numbers that resolved to
the right place by luck. It now names `--spacing-16` / `--spacing-24`,
the theme's own primitive rungs above where the semantic scale tops out.

The closing prev/next pair also carried `px-container` — a different
measure from the content above it — so "Next page" sat ~35px inside the
last card it followed. Both blocks now read one COLUMN constant, so
neither can drift from the other again.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/components/homes/DocsHome.astro |  2 +-
 src/layouts/DocsHomeLayout.astro    | 37 +++++++++++++++++++++++------
 2 files changed, 31 insertions(+), 8 deletions(-)

diff --git a/src/components/homes/DocsHome.astro b/src/components/homes/DocsHome.astro
index 4616df5315..38bbf2d784 100644
--- a/src/components/homes/DocsHome.astro
+++ b/src/components/homes/DocsHome.astro
@@ -31,7 +31,7 @@ const { hero, interfaceSection, sections } = content;
   under it (644) so it breaks to two even lines instead of a stub.
 */
 }
-<header data-doc-chrome class="mb-12 sm:mb-16">
+<header data-doc-chrome class="mb-(--spacing-12) sm:mb-(--spacing-16)">
 	<h1 class="m-0 max-w-(--container-2xl) text-balance text-heading-2xl text-(--text-default)">
 		{hero.title}
 	</h1>
diff --git a/src/layouts/DocsHomeLayout.astro b/src/layouts/DocsHomeLayout.astro
index 96af170023..80328e9d13 100644
--- a/src/layouts/DocsHomeLayout.astro
+++ b/src/layouts/DocsHomeLayout.astro
@@ -28,6 +28,14 @@ export interface Props {
 	next?: { title: string; href: string };
 }
 
+/**
+ * THE PAGE HAS ONE COLUMN, AND IT IS WRITTEN ONCE. The closing pair used to carry
+ * `px-container` — a 4xl measure with its own gutter — while the content above it took
+ * the site measure, so "Next page" sat ~35px inside the last card it followed. Both
+ * blocks read this constant now, so neither can drift from the other again.
+ */
+const COLUMN = 'layout-boundary-inline mx-auto w-full max-w-(--layout-measure-site)';
+
 const { next } = Astro.props;
 const lang = getLanguageFromURL(Astro.url.pathname);
 const direction = rtlLanguages.has(lang) ? 'rtl' : 'ltr';
@@ -37,9 +45,20 @@ const t = useTranslations(Astro);
 
 <BaseLayout {...Astro.props}>
 	<div dir={direction} lang={bcpLang}>
-		<article class="docs-home pb-16 sm:pb-24">
+		{
+			/*
+			 * Every step below is a theme token: the semantic `--spacing-*` scale tops out at
+			 * `xxl` (32), and the home's section step is 64 / 96 — the next two rungs of the
+			 * theme's own primitive ladder, named as `--spacing-16` / `--spacing-24` rather
+			 * than left as bare Tailwind numbers that resolve to the same place by luck.
+			 */
+		}
+		<article class="docs-home pb-(--spacing-16) sm:pb-(--spacing-24)">
 			<section
-				class="layout-boundary-inline mx-auto w-full max-w-(--layout-measure-site) pt-16 pb-16 [&_h2]:pt-16! sm:pt-24 sm:pb-24 sm:[&_h2]:pt-24!"
+				class:list={[
+					COLUMN,
+					'pt-(--spacing-16) pb-(--spacing-16) sm:pt-(--spacing-24) sm:pb-(--spacing-24)',
+				]}
 			>
 				<ReadableContent client:load>
 					<slot />
@@ -47,12 +66,16 @@ const t = useTranslations(Astro);
 			</section>
 
 			{
+				/*
+				 * The pair is placed by its wrapper, not restyled: the column is the wrapper's
+				 * job and the row inside it stays the design system's. Its own top step is
+				 * kept as it was — note it lands UNDER the section's `pb`, so the gap above
+				 * the pair is 96 + 64, not one section step.
+				 */
 				next && (
-					<DocPagination
-						next={next}
-						nextLabel={t('articleNav.nextPage')}
-						class="px-container pt-16"
-					/>
+					<div class:list={[COLUMN, 'pt-(--spacing-16)']}>
+						<DocPagination next={next} nextLabel={t('articleNav.nextPage')} />
+					</div>
 				)
 			}
 		</article>

From 129219dd371429959ba209c3cf0f563c521b1db2 Mon Sep 17 00:00:00 2001
From: Bruno Germano <bruno.germano@gmail.com>
Date: Fri, 11 Sep 2026 19:00:28 -0300
Subject: [PATCH 7/8] chore: strip trailing whitespace and order an import

Formatting only, no behaviour change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/components/LeftSidebar/LeftSidebar.astro                   | 2 +-
 .../reference/build/edge-application/edge-application.mdx      | 3 +--
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/components/LeftSidebar/LeftSidebar.astro b/src/components/LeftSidebar/LeftSidebar.astro
index 745b020c21..54cf9c4a03 100644
--- a/src/components/LeftSidebar/LeftSidebar.astro
+++ b/src/components/LeftSidebar/LeftSidebar.astro
@@ -1,7 +1,7 @@
 ---
+import DocsSidebar from '~/components/webkit/DocsSidebar.vue';
 import { useTranslations } from '~/i18n/util';
 import type { SidebarModel } from '~/nav/index';
-import DocsSidebar from '~/components/webkit/DocsSidebar.vue';
 
 export interface Props {
 	sidebar: SidebarModel;
diff --git a/src/content/docs/en/pages/main-menu/reference/build/edge-application/edge-application.mdx b/src/content/docs/en/pages/main-menu/reference/build/edge-application/edge-application.mdx
index 4809e6badf..6e0187ca5f 100644
--- a/src/content/docs/en/pages/main-menu/reference/build/edge-application/edge-application.mdx
+++ b/src/content/docs/en/pages/main-menu/reference/build/edge-application/edge-application.mdx
@@ -90,7 +90,7 @@ See the documentation for each available setting:
 
 ## Real-Time Purge
 
-Use **Real-Time Purge** to clear cached content from Azion's edge or from the [tiered cache layer]](/en/documentation/build/cache/tiered-cache/) to maintain content accuracy, reduce outdated content delivery, and deliver an optimal user experience on your application. 
+Use **Real-Time Purge** to clear cached content from Azion's edge or from the [tiered cache layer]](/en/documentation/build/cache/tiered-cache/) to maintain content accuracy, reduce outdated content delivery, and deliver an optimal user experience on your application.
 
 <DocButton kind="secondary" label="Learn more about Real-Time Purge" href="/en/documentation/build/cache/real-time-purge/" size="medium" />
 
@@ -119,4 +119,3 @@ These are the **default limits** for each Support service:
 | Scope | Developer | Business | Enterprise | Mission-Critical |
 | ----- | --------- | -------- | ---------- | ---------------- |
 | Applications per account | 10 | 50 | 200 | Customizable |
-

From 2685e53e9e630274510fb7c6621299c4cdd473c4 Mon Sep 17 00:00:00 2001
From: Bruno Germano <bruno.germano@gmail.com>
Date: Fri, 11 Sep 2026 19:32:12 -0300
Subject: [PATCH 8/8] fix(agents): stop AgentMark from dropping the consumer's
 class
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The template's v-if/v-else pair is wrapped in eslint pragma comments. A
comment counts as a root node in a dev build, which makes the component
a fragment — and Vue silently drops automatic attribute inheritance on a
fragment. Every class passed in was discarded.

On the docs home that meant CopyPromptButton's `size-(--size-5)` never
landed, so the four agent marks rendered at their intrinsic 24px, over-
flowed the button and were clipped by its `overflow-hidden`: three of the
four were invisible. AgentCompareTable's `size-4` was being dropped the
same way.

Production strips template comments, so the root collapses to a single
element and the bug disappears there — which is what kept it hidden.
Owning the root with inheritAttrs + $attrs removes the dependency on how
many nodes the compiler happens to emit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/components/webkit/AgentMark.vue | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/components/webkit/AgentMark.vue b/src/components/webkit/AgentMark.vue
index a412947e46..017e189c03 100644
--- a/src/components/webkit/AgentMark.vue
+++ b/src/components/webkit/AgentMark.vue
@@ -2,6 +2,7 @@
 	<!-- eslint-disable vue/no-v-html -- body is the hardcoded MARKS constant below, never user input -->
 	<svg
 		v-if="body"
+		v-bind="$attrs"
 		:viewBox="mark.viewBox"
 		xmlns="http://www.w3.org/2000/svg"
 		role="img"
@@ -12,6 +13,7 @@
 	<!-- eslint-enable vue/no-v-html -->
 	<svg
 		v-else
+		v-bind="$attrs"
 		:viewBox="mark.viewBox"
 		xmlns="http://www.w3.org/2000/svg"
 		role="img"
@@ -27,6 +29,13 @@
 <script setup lang="ts">
 import { computed } from 'vue';
 
+/*
+ * Own the root: the template's v-if/v-else pair is wrapped in eslint pragma comments,
+ * which count as root nodes in a dev build and make this a fragment — and Vue drops
+ * automatic attribute inheritance on a fragment, silently discarding a consumer's class.
+ */
+defineOptions({ name: 'AgentMark', inheritAttrs: false });
+
 export type AgentName =
 	| 'claude'
 	| 'codex'