diff --git a/CHANGELOG.md b/CHANGELOG.md
index b79ecf0..d07650e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,19 @@ Notable changes to this project are recorded here. The format follows
 
 ## [Unreleased]
 
+### Changed
+
+- The theme is a thin layer over the VitePress default theme: one
+  `style.css`, Lucide icons in the sidebar, and the same header geometry on
+  every page. `ApiCard` is a plain key/description list.
+- Each home page is the stock VitePress hero with a pointer-following
+  `HomeSpotlight` behind it and a screenshot of the portal below.
+
+### Removed
+
+- `HeroSection` and `SpotlightBackground`, and the `theme.css`, `sidebar.css`
+  and `api-docs-responsive.css` stylesheets.
+
 ## [0.1.0] - 2026-11-05
 
 ### Added
diff --git a/README.md b/README.md
index 167b610..6a8aee3 100644
--- a/README.md
+++ b/README.md
@@ -44,8 +44,8 @@ raw spec ──► hydrate ► fix ► validate ──► docs/public/openapi.<l
 
 - **Guides** are Markdown in `docs/{en,pt,es,fr}/`. Each locale has its own nav and sidebar in `docs/.vitepress/config.ts`.
 - **API reference**: `docs/.vitepress/components/ScalarApi.vue` embeds Scalar and picks the spec from the page language (`en` → `openapi.en.json`, `pt` → `openapi.pt-BR.json`, ...). Pass `spec-url` to override.
-- **Theme**: Scalar runs with `theme: 'none'` and its CSS variables are mapped onto VitePress's, so the reference follows the site's colors, fonts and dark mode. The palette lives in `docs/.vitepress/theme/theme.css`.
-- **Components**: `ApiCard` (key/description tables used in the guides), `HeroSection` + `SpotlightBackground` (landing page).
+- **Theme**: Scalar runs with `theme: 'none'` and its CSS variables are mapped onto VitePress's, so the reference follows the site's colors, fonts and dark mode. The brand color and fonts live in `docs/.vitepress/theme/style.css`, a thin layer over the VitePress default theme.
+- **Components**: `ApiCard` (key/description tables used in the guides), Each locale's home page is the stock VitePress hero, configured in `docs/<lang>/index.md`, with `HomeSpotlight` (a glow that follows the pointer) behind it.
 - **Language routing**: `/` (`docs/index.md`) sends the browser to `/pt/`, `/es/` or `/fr/` based on its language, and to `/en/` otherwise. Without JavaScript it shows a list of the four languages.
 
 ## Project structure
@@ -53,12 +53,13 @@ raw spec ──► hydrate ► fix ► validate ──► docs/public/openapi.<l
 ```text
 docs/
 ├── .vitepress/
-│   ├── components/      ApiCard, HeroSection, ScalarApi, SpotlightBackground
-│   ├── theme/           theme.css (palette), style.css, api-docs-responsive.css, sidebar.css, fonts.css
+│   ├── components/      ApiCard, HomeSpotlight, ScalarApi
+│   ├── theme/           style.css (brand, fonts, surfaces), fonts.css
 │   └── config.ts        locales, nav, sidebars
 ├── public/
 │   ├── openapi.{en,pt-BR,es,fr}.json   one spec per language
-│   ├── preview.png                     hero image (also used above)
+│   ├── preview.png                     screenshot used above
+│   ├── preview-{1080,1761}.webp        the same image on the home pages
 │   └── favicon.svg, logo-{light,dark}.svg
 ├── en/ pt/ es/ fr/      intro, authentication, rate-limits, examples, pagination, errors, api-reference
 └── index.md             language redirect
@@ -68,8 +69,8 @@ docs/
 
 1. Replace `docs/public/openapi.*.json` with your specs (one per language, or point every locale at the same file in `SPEC_BY_LANG` inside `ScalarApi.vue`).
 2. Rewrite the guide pages in `docs/<lang>/` and adjust the sidebars in `docs/.vitepress/config.ts`.
-3. Change the brand block in `docs/.vitepress/theme/theme.css` and the logos in `docs/public/`.
-4. Take a new `docs/public/preview.png` (the hero shows it inside a MacBook frame: screenshot at 1440×932 and composite it into the screen area).
+3. Change the brand block in `docs/.vitepress/theme/style.css` and the logos in `docs/public/`.
+4. Replace `docs/public/preview.png` and the two `preview-*.webp` files that the home pages show (1761×1075, a laptop frame with a 1440×932 screenshot composited into the screen).
 5. Deploy: any static host works. The live demo runs on Cloudflare Workers Static Assets: `pnpm run deploy` builds the site and runs `wrangler deploy` (config in `wrangler.jsonc`).
 
 ## Contributing
diff --git a/README.pt-br.md b/README.pt-br.md
index 385deee..7d04c34 100644
--- a/README.pt-br.md
+++ b/README.pt-br.md
@@ -44,8 +44,8 @@ spec crua ──► hydrate ► fix ► validate ──► docs/public/openapi.<
 
 - **Guias** são Markdown em `docs/{en,pt,es,fr}/`. Cada idioma tem nav e sidebar próprios em `docs/.vitepress/config.ts`.
 - **Referência da API**: `docs/.vitepress/components/ScalarApi.vue` embute o Scalar e escolhe a spec pelo idioma da página (`pt` → `openapi.pt-BR.json`, `en` → `openapi.en.json`, ...). Use `spec-url` para sobrescrever.
-- **Tema**: o Scalar roda com `theme: 'none'` e suas variáveis CSS são mapeadas para as do VitePress, então a referência segue cores, fontes e modo escuro do site. A paleta fica em `docs/.vitepress/theme/theme.css`.
-- **Componentes**: `ApiCard` (tabelas chave/descrição dos guias), `HeroSection` + `SpotlightBackground` (página inicial).
+- **Tema**: o Scalar roda com `theme: 'none'` e suas variáveis CSS são mapeadas para as do VitePress, então a referência segue cores, fontes e modo escuro do site. A cor da marca e as fontes ficam em `docs/.vitepress/theme/style.css`, uma camada fina sobre o tema padrão do VitePress.
+- **Componentes**: `ApiCard` (tabelas chave/descrição dos guias), A página inicial de cada idioma é o hero padrão do VitePress, configurado em `docs/<lang>/index.md`, com o `HomeSpotlight` (um brilho que segue o ponteiro) por trás.
 - **Idioma**: `/` (`docs/index.md`) leva o navegador para `/pt/`, `/es/` ou `/fr/` conforme o idioma dele, e para `/en/` nos demais casos. Sem JavaScript, mostra a lista dos quatro idiomas.
 
 ## Estrutura do projeto
@@ -53,12 +53,13 @@ spec crua ──► hydrate ► fix ► validate ──► docs/public/openapi.<
 ```text
 docs/
 ├── .vitepress/
-│   ├── components/      ApiCard, HeroSection, ScalarApi, SpotlightBackground
-│   ├── theme/           theme.css (paleta), style.css, api-docs-responsive.css, sidebar.css, fonts.css
+│   ├── components/      ApiCard, HomeSpotlight, ScalarApi
+│   ├── theme/           style.css (marca, fontes, superfícies), fonts.css
 │   └── config.ts        idiomas, nav, sidebars
 ├── public/
 │   ├── openapi.{en,pt-BR,es,fr}.json   uma spec por idioma
-│   ├── preview.png                     imagem da página inicial (também usada acima)
+│   ├── preview.png                     screenshot usado acima
+│   ├── preview-{1080,1761}.webp        a mesma imagem nas páginas iniciais
 │   └── favicon.svg, logo-{light,dark}.svg
 ├── en/ pt/ es/ fr/      intro, authentication, rate-limits, examples, pagination, errors, api-reference
 └── index.md             redirecionamento de idioma
@@ -68,8 +69,8 @@ docs/
 
 1. Substitua `docs/public/openapi.*.json` pelas suas specs (uma por idioma, ou aponte todos os idiomas para o mesmo arquivo em `SPEC_BY_LANG`, dentro de `ScalarApi.vue`).
 2. Reescreva os guias em `docs/<lang>/` e ajuste as sidebars em `docs/.vitepress/config.ts`.
-3. Troque o bloco de marca em `docs/.vitepress/theme/theme.css` e os logos em `docs/public/`.
-4. Gere um novo `docs/public/preview.png` (a página inicial mostra a imagem dentro de um MacBook: print em 1440×932 composto na área da tela).
+3. Troque o bloco de marca em `docs/.vitepress/theme/style.css` e os logos em `docs/public/`.
+4. Troque o `docs/public/preview.png` e os dois `preview-*.webp` das páginas iniciais (1761×1075, um notebook com um print de 1440×932 composto na tela).
 5. Publique em qualquer host estático. A demo roda no Cloudflare Workers Static Assets: `pnpm run deploy` gera o site e roda `wrangler deploy` (configuração em `wrangler.jsonc`).
 
 ## Contribuindo
diff --git a/docs/.vitepress/components/ApiCard.vue b/docs/.vitepress/components/ApiCard.vue
index 268d357..c347941 100644
--- a/docs/.vitepress/components/ApiCard.vue
+++ b/docs/.vitepress/components/ApiCard.vue
@@ -1,199 +1,74 @@
+<script setup lang="ts">
+defineProps<{
+  title?: string
+  items: { key: string; description: string }[]
+}>()
+</script>
+
 <template>
-  <div class="api-macos-window">
-    <div class="api-macos-header">
-      <div class="macos-buttons">
-        <div class="macos-btn macos-btn-red"></div>
-        <div class="macos-btn macos-btn-yellow"></div>
-        <div class="macos-btn macos-btn-green"></div>
+  <figure class="api-card">
+    <figcaption v-if="title" class="api-card-title">{{ title }}</figcaption>
+    <dl>
+      <div v-for="item in items" :key="item.key" class="api-card-row">
+        <dt>{{ item.key }}</dt>
+        <!-- Descriptions are authored in the docs and may contain <code>. -->
+        <dd v-html="item.description" />
       </div>
-      <span class="api-macos-title">{{ title }}</span>
-    </div>
-    <div class="api-macos-content">
-      <div
-        v-for="(item, index) in items"
-        :key="index"
-        class="api-macos-row"
-      >
-        <span class="api-macos-key" :class="item.color">{{ item.key }}</span>
-        <span class="api-macos-value" v-html="item.description"></span>
-      </div>
-    </div>
-  </div>
+    </dl>
+  </figure>
 </template>
 
-<script setup lang="ts">
-interface ApiCardItem {
-  key: string
-  description: string
-  color?: string
-}
-
-withDefaults(defineProps<{ title?: string; items: ApiCardItem[] }>(), {
-  title: 'request.headers'
-})
-</script>
-
 <style scoped>
-.api-macos-window {
-  background: var(--api-macos-bg, rgba(255,255,255,0.7));
-  border-radius: 14px;
-  box-shadow: 0 6px 32px 0 rgba(28,28,28,0.16), 0 1.5px 3px 0 rgba(28,28,30,0.05);
-  overflow: hidden;
-  backdrop-filter: blur(24px) saturate(160%);
-  -webkit-backdrop-filter: blur(24px) saturate(160%);
-  margin: 1.5rem 0;
-  animation: fadeUp 0.5s cubic-bezier(.42,0,.58,1);
-  transition: box-shadow 0.2s cubic-bezier(.42,0,.58,1);
+.api-card {
+  margin: 16px 0;
+  border-radius: 8px;
+  box-shadow: var(--ring);
+  overflow: clip;
+}
+
+.api-card-title {
+  padding: 10px 16px;
+  border-bottom: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-soft);
+  font-family: var(--vp-font-family-mono);
+  font-size: 13px;
+  color: var(--vp-c-text-2);
 }
 
-.api-macos-window:hover {
-  box-shadow: 0 12px 36px 0 rgba(28,28,28,0.24), 0 2px 8px 0 rgba(28,28,30,0.09);
+dl {
+  margin: 0;
 }
 
-.api-macos-header {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  padding: 18px 24px 14px 18px;
-  background: linear-gradient(
-    120deg,
-    rgba(240,241,246,0.60) 0%,
-    rgba(255,255,255,0.35) 100%
-  );
-  position: relative;
-  z-index: 1;
-  box-shadow: 0 1px 0 0 rgba(28,28,30,0.03);
-  backdrop-filter: blur(12px);
-  -webkit-backdrop-filter: blur(12px);
+.api-card-row {
+  display: grid;
+  grid-template-columns: minmax(0, 11rem) minmax(0, 1fr);
+  gap: 4px 24px;
+  padding: 12px 16px;
 }
 
-.macos-buttons {
-  display: flex;
-  gap: 8px;
-  margin-right: 8px;
+.api-card-row + .api-card-row {
+  border-top: 1px solid var(--vp-c-divider);
 }
 
-.macos-btn {
-  width: 11px;
-  height: 11px;
-  border-radius: 50%;
-  box-shadow: 0 0.5px 1.5px rgba(0,0,0,0.07);
-  border: 0.5px solid rgba(0,0,0,0.04);
-  transition: transform 0.13s cubic-bezier(.42,0,.58,1);
-  position: relative;
-  cursor: default;
-}
-.macos-btn:hover {
-  transform: scale(1.11);
-}
-.macos-btn-red    { background: linear-gradient(120deg,#fd594b 60%,#ea3323 100%);}
-.macos-btn-yellow { background: linear-gradient(120deg,#fdbd41 60%,#f8e36b 100%);}
-.macos-btn-green  { background: linear-gradient(120deg,#31c150 60%,#28b846 100%);}
-
-.api-macos-title {
+dt {
+  font-family: var(--vp-font-family-mono);
   font-size: 14px;
-  color: var(--vp-c-text-1, #222);
-  font-family: -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;
-  font-weight: 500;
-  letter-spacing: -0.01em;
-  margin-left: 8px;
-  opacity: 0.75;
-  text-shadow: 0 1px 1.5px rgba(255,255,255,0.18);
-  user-select: text;
-  transition: color 0.15s;
-}
-
-.api-macos-content {
-  font-family: ui-monospace, SFMono-Regular, "SF Mono", Consolas, "Liberation Mono", Menlo, monospace;
-  font-size: 14px;
-  background: transparent;
-}
-
-.api-macos-row {
-  display: flex;
-  gap: 18px;
-  padding: 14px 22px 14px 22px;
-  align-items: flex-start;
-  border-bottom: 1px solid rgba(40,40,50,0.05);
-  transition: background 0.2s, transform 0.18s cubic-bezier(.42,0,.58,1);
-  position: relative;
-  min-height: 36px;
-}
-
-.api-macos-row:last-child {
-  border-bottom: none;
-}
-
-.api-macos-row:hover {
-  background: rgba(120,140,255,0.04);
-  transform: translateY(-1.5px) scale(1.01);
-}
-
-.api-macos-key {
   font-weight: 600;
-  min-width: 135px;
-  flex-shrink: 0;
-  font-size: 13px;
-  letter-spacing: -0.01em;
-  user-select: text;
-  font-family: inherit;
+  color: var(--vp-c-text-1);
+  overflow-wrap: anywhere;
 }
-.api-macos-key.blue    { color: #006fff; }
-.api-macos-key.purple  { color: #7158e2; }
-.api-macos-key.pink    { color: #ff2d92; }
-.api-macos-key.red     { color: #ff3b30; }
-.api-macos-key.green   { color: #28b846; }
 
-.api-macos-value {
-  color: var(--vp-c-text-2, #444);
+dd {
+  margin: 0;
+  font-size: 15px;
   line-height: 1.6;
-  font-size: 13px;
-  user-select: text;
-  font-family: inherit;
+  color: var(--vp-c-text-2);
+  text-wrap: pretty;
 }
 
-@keyframes fadeUp {
-  from {
-    opacity: 0;
-    transform: translateY(20px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
+@media (max-width: 640px) {
+  .api-card-row {
+    grid-template-columns: minmax(0, 1fr);
   }
 }
-
-/* Dark mode */
-:root.dark .api-macos-window {
-  --api-macos-bg: rgba(32,34,38,0.72);
-  background: var(--api-macos-bg);
-  box-shadow: 0 8px 34px 0 rgba(20,20,22,0.28), 0 2px 8px 0 rgba(20,20,24,0.18);
-}
-:root.dark .api-macos-header {
-  background: linear-gradient(120deg,rgba(38,41,49,0.82) 0%,rgba(26,27,32,0.56) 100%);
-  box-shadow: 0 1px 0 0 rgba(190,190,200,0.035);
-}
-:root.dark .api-macos-title {
-  color: #eee;
-  text-shadow: 0 1px 2px rgba(0,0,0,0.22);
-}
-:root.dark .api-macos-row {
-  border-bottom: 1px solid rgba(220,220,230,0.04);
-}
-:root.dark .api-macos-row:hover {
-  background: rgba(60,80,140,0.06);
-}
-:root.dark .api-macos-key.blue    { color: #0a84ff; }
-:root.dark .api-macos-key.purple  { color: #5e5ce6; }
-:root.dark .api-macos-key.pink    { color: #ff375f; }
-:root.dark .api-macos-key.red     { color: #ff453a; }
-:root.dark .api-macos-key.green   { color: #28cd41; }
-
-/* Responsive */
-@media (max-width: 768px) {
-  .api-macos-window { margin: 1rem 0; border-radius: 9px; }
-  .api-macos-header { padding: 13px 12px 10px 13px; }
-  .api-macos-row { padding: 12px 13px; flex-direction: column; gap: 5px; }
-  .api-macos-key { min-width: auto; }
-}
 </style>
diff --git a/docs/.vitepress/components/HeroSection.vue b/docs/.vitepress/components/HeroSection.vue
deleted file mode 100644
index e008393..0000000
--- a/docs/.vitepress/components/HeroSection.vue
+++ /dev/null
@@ -1,408 +0,0 @@
-<script setup lang="ts">
-import { computed, onMounted, ref } from 'vue'
-import { withBase, useData } from 'vitepress'
-import SpotlightBackground from './SpotlightBackground.vue'
-
-const HEADLINE = 'API Documentation Starter'
-const GITHUB_URL = 'https://github.com/rafactx/api-docs-starter'
-
-const translations = {
-  pt: {
-    subtitle: 'Um portal de documentação de API multilíngue com VitePress e Scalar.\nEsta demonstração documenta a Shelfline Field API, uma API fictícia de execução no varejo.',
-    primaryButtonText: 'Conheça a API',
-    primaryButtonLink: '/pt/intro',
-    imageAltText: 'Preview da documentação API Documentation Starter'
-  },
-  en: {
-    subtitle: 'A multilingual API documentation portal built with VitePress and Scalar.\nThis demo documents the Shelfline Field API, a fictional retail field-execution API.',
-    primaryButtonText: 'Explore the API',
-    primaryButtonLink: '/en/intro',
-    imageAltText: 'Preview of the API Documentation Starter'
-  },
-  es: {
-    subtitle: 'Un portal de documentación de API multilingüe con VitePress y Scalar.\nEsta demo documenta la Shelfline Field API, una API ficticia de ejecución en el punto de venta.',
-    primaryButtonText: 'Explora la API',
-    primaryButtonLink: '/es/intro',
-    imageAltText: 'Vista previa de la documentación API Documentation Starter'
-  },
-  fr: {
-    subtitle: "Un portail de documentation d'API multilingue construit avec VitePress et Scalar.\nCette démo documente la Shelfline Field API, une API fictive d'exécution terrain en magasin.",
-    primaryButtonText: "Découvrez l'API",
-    primaryButtonLink: '/fr/intro',
-    imageAltText: "Aperçu de la documentation API Documentation Starter"
-  }
-}
-
-const { lang } = useData()
-const t = computed(() => translations[lang.value as keyof typeof translations] || translations.en)
-
-const props = withDefaults(defineProps<{ imageSrc?: string; animationDelay?: number }>(), {
-  imageSrc: '/preview.png',
-  animationDelay: 100
-})
-
-const headlineWords = HEADLINE.split(' ')
-const animationStarted = ref(false)
-const isImageLoading = ref(true)
-const image = ref<HTMLImageElement | null>(null)
-
-onMounted(() => {
-  requestAnimationFrame(() => (animationStarted.value = true))
-  // The image may finish loading before hydration attaches the load listener.
-  if (image.value?.complete) isImageLoading.value = false
-})
-</script>
-
-<template>
-  <SpotlightBackground>
-    <div class="hero-container">
-      <section class="main-content">
-        <h1 class="headline">
-          <span
-            v-for="(word, idx) in headlineWords"
-            :key="idx"
-            class="word-span"
-            :class="{ 'is-visible': animationStarted }"
-            :style="{ transitionDelay: `${idx * props.animationDelay}ms` }"
-          >
-            {{ word }}
-          </span>
-        </h1>
-
-        <p class="subtitle" :class="{ 'is-visible': animationStarted }">
-          {{ t.subtitle }}
-        </p>
-
-        <div class="buttons-container" :class="{ 'is-visible': animationStarted }">
-          <a
-            :href="withBase(t.primaryButtonLink)"
-            class="button button--primary"
-          >
-            <span class="button__text">{{ t.primaryButtonText }}</span>
-            <span class="button__icon" aria-hidden="true">→</span>
-          </a>
-          <a
-            :href="GITHUB_URL"
-            class="button button--secondary"
-            target="_blank"
-            rel="noopener noreferrer"
-          >
-            <span class="button__text">GitHub</span>
-          </a>
-        </div>
-
-        <div class="image-preview" :class="{ 'is-visible': animationStarted }">
-          <div class="image-container">
-            <img
-              ref="image"
-              class="preview-image"
-              :src="withBase(props.imageSrc)"
-              :alt="t.imageAltText"
-              loading="eager"
-              decoding="async"
-              @load="isImageLoading = false"
-              @error="isImageLoading = false"
-            />
-            <div v-if="isImageLoading" class="image-skeleton" aria-hidden="true" />
-          </div>
-        </div>
-      </section>
-    </div>
-  </SpotlightBackground>
-</template>
-
-<style scoped>
-.hero-container {
-  margin: 2.5rem auto;
-  padding: 0 1rem;
-  display: flex;
-  max-width: 1280px;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-}
-
-.main-content {
-  padding: 2.5rem 1rem;
-  text-align: center;
-  position: relative;
-  z-index: 10;
-  width: 100%;
-}
-
-.headline {
-  margin: 0 auto 1rem;
-  max-width: 56rem;
-  font-size: clamp(2rem, 4vw, 4.5rem);
-  font-weight: 700;
-  color: var(--vp-c-text-1);
-  line-height: 1.1;
-}
-
-.word-span {
-  display: inline-block;
-  margin-right: 0.5rem;
-  opacity: 0;
-  transform: translateY(10px);
-  filter: blur(4px);
-  transition:
-    transform 0.35s cubic-bezier(.42,0,.58,1),
-    filter 0.35s cubic-bezier(.42,0,.58,1),
-    opacity 0.35s cubic-bezier(.42,0,.58,1);
-  will-change: transform, opacity, filter;
-}
-.word-span.is-visible {
-  opacity: 1;
-  transform: translateY(0);
-  filter: blur(0);
-}
-
-.subtitle {
-  margin: 0 auto;
-  padding: 1.25rem 0;
-  max-width: 44rem;
-  font-size: clamp(1rem, 2.2vw, 1.25rem);
-  font-weight: 400;
-  line-height: 1.75;
-  text-align: center;
-  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
-  white-space: normal;
-  opacity: 0;
-  transition: opacity 0.4s ease-in-out 0.8s;
-  will-change: opacity;
-}
-
-.buttons-container {
-  margin-top: var(--vp-space-xl);
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  justify-content: center;
-  gap: var(--vp-space-md);
-  opacity: 0;
-  transition: opacity var(--vp-transition-timing-slower) var(--vp-ease-out) 1s;
-  will-change: opacity;
-}
-
-.button {
-  position: relative;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  gap: var(--vp-space-sm);
-  padding: var(--vp-space-sm) var(--vp-space-lg);
-  font-weight: 600;
-  font-size: var(--vp-font-size-base);
-  text-decoration: none;
-  border-radius: var(--vp-radius-lg);
-  border: none;
-  cursor: pointer;
-  user-select: none;
-  -webkit-tap-highlight-color: transparent;
-  transition: all var(--vp-transition-timing-base) var(--vp-ease-out);
-  transform: translateZ(0);
-  backface-visibility: hidden;
-}
-
-.button--primary {
-  background: linear-gradient(135deg, var(--vp-hero-primary-color) 0%, var(--vp-c-brand-2) 100%);
-  color: #ffffff;
-  box-shadow: var(--vp-shadow-2);
-  overflow: hidden;
-}
-
-.button--primary::before {
-  content: '';
-  position: absolute;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  background: linear-gradient(135deg, var(--vp-c-brand-1) 0%, var(--vp-c-brand-dark) 100%);
-  opacity: 0;
-  transition: opacity var(--vp-transition-timing-base) var(--vp-ease-out);
-  border-radius: inherit;
-}
-
-.button--primary:hover::before {
-  opacity: 1;
-}
-
-.button--primary:hover {
-  transform: translateY(-1px) scale(1.02);
-  box-shadow: var(--vp-shadow-3);
-}
-
-.button--primary:active {
-  transform: translateY(0) scale(0.98);
-  box-shadow: var(--vp-shadow-1);
-  transition: all var(--vp-transition-timing-fast) var(--vp-ease-in);
-}
-
-.button--primary:focus-visible {
-  outline: 2px solid var(--vp-hero-primary-color);
-  outline-offset: 2px;
-  box-shadow: var(--vp-shadow-3), 0 0 0 4px rgba(var(--vp-hero-primary-rgb), 0.2);
-}
-
-.button--primary .button__text,
-.button--primary .button__icon {
-  position: relative;
-  z-index: 1;
-}
-
-.button--primary .button__icon {
-  transition: transform var(--vp-transition-timing-base) var(--vp-ease-bounce);
-}
-
-.button--primary:hover .button__icon {
-  transform: translateX(4px);
-}
-
-.button--secondary {
-  background: var(--vp-c-bg);
-  backdrop-filter: var(--vp-backdrop-blur-sm);
-  border: 1px solid var(--vp-c-border);
-  color: var(--vp-c-text-1);
-  box-shadow: var(--vp-shadow-1);
-  overflow: hidden;
-}
-
-.button--secondary::before {
-  content: '';
-  position: absolute;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  background: var(--vp-c-bg-soft);
-  opacity: 0;
-  transition: opacity var(--vp-transition-timing-base) var(--vp-ease-out);
-  border-radius: inherit;
-}
-
-.button--secondary:hover::before {
-  opacity: 1;
-}
-
-.button--secondary:hover {
-  border-color: var(--vp-c-brand);
-  transform: translateY(-1px) scale(1.02);
-  box-shadow: var(--vp-shadow-2);
-}
-
-.button--secondary:active {
-  transform: translateY(0) scale(0.98);
-  box-shadow: var(--vp-shadow-1);
-  transition: all var(--vp-transition-timing-fast) var(--vp-ease-in);
-}
-
-.button--secondary:focus-visible {
-  outline: 2px solid var(--vp-c-brand);
-  outline-offset: 2px;
-  box-shadow: var(--vp-shadow-2), 0 0 0 4px var(--vp-c-brand-soft);
-}
-
-.button--secondary .button__text {
-  position: relative;
-  z-index: 1;
-}
-
-.image-preview {
-  margin-top: 5rem;
-  opacity: 0;
-  transform: translateY(10px);
-  transition: opacity 0.4s ease-in-out 1.2s, transform 0.4s ease-in-out 1.2s;
-  will-change: opacity, transform;
-}
-
-.image-container {
-  position: relative;
-  overflow: visible;
-  border-radius: 0.75rem;
-}
-
-.preview-image {
-  display: block;
-  width: 100%;
-  height: auto;
-  aspect-ratio: 16 / 9;
-  object-fit: contain;
-  transition: transform 0.3s ease;
-}
-.image-preview:hover .preview-image {
-  transform: scale(1.02);
-}
-
-.image-skeleton {
-  position: absolute;
-  inset: 0;
-  background: linear-gradient(90deg,
-    var(--vp-c-bg-soft) 25%,
-    var(--vp-c-bg-mute) 50%,
-    var(--vp-c-bg-soft) 75%);
-  background-size: 200% 100%;
-  animation: skeleton-loading 1.5s infinite;
-}
-
-.is-visible {
-  opacity: 1;
-}
-
-@keyframes skeleton-loading {
-  0% { background-position: 200% 0; }
-  100% { background-position: -200% 0; }
-}
-
-@media (max-width: 768px) {
-  .hero-container { margin: var(--vp-space-md) auto; }
-  .main-content { padding: var(--vp-space-md); }
-  .buttons-container {
-    flex-direction: column;
-    width: 100%;
-    gap: var(--vp-space-sm);
-  }
-  .button {
-    width: 100%;
-    padding: var(--vp-space-md) var(--vp-space-lg);
-    font-size: var(--vp-font-size-lg);
-  }
-  .button:hover {
-    transform: translateY(-0.5px) scale(1.01);
-  }
-  .image-preview { margin-top: var(--vp-space-2xl); }
-}
-@media (max-width: 480px) {
-  .headline { font-size: var(--vp-font-size-4xl); }
-  .subtitle { font-size: var(--vp-font-size-base); }
-  .button {
-    padding: var(--vp-space-md) var(--vp-space-xl);
-  }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .word-span,
-  .subtitle,
-  .buttons-container,
-  .image-preview,
-  .button,
-  .button--primary::before,
-  .button--secondary::before,
-  .button__icon,
-  .preview-image {
-    transition: none !important;
-    animation: none !important;
-    transform: none !important;
-  }
-
-  .button:hover,
-  .button:active {
-    transform: none !important;
-  }
-}
-@media (prefers-contrast: high) {
-  .button--primary, .button--secondary {
-    border: 2px solid currentColor;
-  }
-}
-</style>
diff --git a/docs/.vitepress/components/HomeSpotlight.vue b/docs/.vitepress/components/HomeSpotlight.vue
new file mode 100644
index 0000000..f066080
--- /dev/null
+++ b/docs/.vitepress/components/HomeSpotlight.vue
@@ -0,0 +1,108 @@
+<script setup lang="ts">
+import { onMounted, onUnmounted, ref } from 'vue'
+
+// A soft brand-colored glow behind the home hero that follows the pointer.
+// The gradient is painted once; moving it is a transform, so pointer moves
+// never trigger a repaint. Touch screens and reduced motion get a still glow.
+
+const root = ref<HTMLElement | null>(null)
+const glow = ref<HTMLElement | null>(null)
+const active = ref(false)
+
+let frame = 0
+let stop: (() => void) | undefined
+
+function moveTo(clientX: number, clientY: number) {
+  const box = root.value?.getBoundingClientRect()
+  if (!box || !glow.value) return
+  const inside = clientY >= box.top && clientY <= box.bottom
+  active.value = inside
+  if (!inside) return
+  glow.value.style.translate = `${clientX - box.left}px ${clientY - box.top}px`
+}
+
+onMounted(() => {
+  const canFollow = matchMedia('(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)')
+  if (!canFollow.matches) return
+
+  const onMove = (e: PointerEvent) => {
+    cancelAnimationFrame(frame)
+    frame = requestAnimationFrame(() => moveTo(e.clientX, e.clientY))
+  }
+  const onLeave = () => (active.value = false)
+
+  window.addEventListener('pointermove', onMove, { passive: true })
+  document.documentElement.addEventListener('pointerleave', onLeave)
+  stop = () => {
+    cancelAnimationFrame(frame)
+    window.removeEventListener('pointermove', onMove)
+    document.documentElement.removeEventListener('pointerleave', onLeave)
+  }
+})
+
+onUnmounted(() => stop?.())
+</script>
+
+<template>
+  <div ref="root" class="spotlight" aria-hidden="true">
+    <div ref="glow" class="spotlight-glow" :class="{ 'is-active': active }" />
+  </div>
+</template>
+
+<style scoped>
+.spotlight {
+  position: absolute;
+  inset: 0;
+  overflow: clip;
+  /* Fade out toward the footer so the glow never ends on a hard edge. */
+  mask-image: linear-gradient(to bottom, #000 60%, transparent);
+  pointer-events: none;
+  z-index: -1;
+}
+
+.spotlight-glow {
+  --size: 1100px;
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--size);
+  height: var(--size);
+  margin: calc(var(--size) / -2) 0 0 calc(var(--size) / -2);
+  /* Resting spot: centered over the headline, before the pointer arrives. */
+  translate: 50vw 260px;
+  border-radius: 50%;
+  /* Brand-tinted so the glow follows a re-skin; a touch of violet at the rim. */
+  background: radial-gradient(
+    closest-side,
+    color-mix(in oklch, var(--vp-c-brand-3) 38%, transparent),
+    color-mix(in oklch, var(--vp-c-brand-3) 20%, transparent) 35%,
+    color-mix(in oklch, var(--vp-c-brand-3) 10%, rgb(147 51 234 / 0.1)) 65%,
+    transparent
+  );
+  opacity: 0.6;
+  transition:
+    translate 500ms cubic-bezier(0.22, 1, 0.36, 1),
+    opacity 400ms ease;
+}
+
+.spotlight-glow.is-active {
+  opacity: 1;
+}
+
+.dark .spotlight-glow {
+  background: radial-gradient(
+    closest-side,
+    color-mix(in oklch, var(--vp-c-brand-2) 22%, transparent),
+    color-mix(in oklch, var(--vp-c-brand-3) 12%, transparent) 35%,
+    color-mix(in oklch, var(--vp-c-brand-3) 7%, rgb(147 51 234 / 0.07)) 65%,
+    transparent
+  );
+}
+
+@media (max-width: 768px) {
+  .spotlight-glow {
+    --size: 700px;
+    translate: 50vw 200px;
+  }
+}
+</style>
diff --git a/docs/.vitepress/components/ScalarApi.vue b/docs/.vitepress/components/ScalarApi.vue
index 8bad8d8..1f2f5f3 100644
--- a/docs/.vitepress/components/ScalarApi.vue
+++ b/docs/.vitepress/components/ScalarApi.vue
@@ -1,20 +1,11 @@
-<template>
-  <div v-if="isMounted" class="scalar-api-container">
-    <ApiReference :key="`${themeKey}-${resolvedSpecUrl}`" :configuration="scalarConfig" />
-  </div>
-  <div v-else class="scalar-api-status">
-    <div class="scalar-api-spinner"></div>
-    <p>{{ messages.loading }}</p>
-  </div>
-</template>
-
 <script setup lang="ts">
 import { useData } from 'vitepress'
-import { computed, defineAsyncComponent, h, onMounted, ref } from 'vue'
+import { computed, defineAsyncComponent, h } from 'vue'
 
+// Keyed by the locale `lang` in config.ts.
 const MESSAGES: Record<string, { loading: string; error: string }> = {
-  en: { loading: 'Loading API reference…', error: 'Could not load the API reference. Please reload the page.' },
-  pt: { loading: 'Carregando a referência da API…', error: 'Não foi possível carregar a referência da API. Recarregue a página.' },
+  en: { loading: 'Loading API reference…', error: 'Could not load the API reference. Reload the page to try again.' },
+  'pt-BR': { loading: 'Carregando a referência da API…', error: 'Não foi possível carregar a referência da API. Recarregue a página.' },
   es: { loading: 'Cargando la referencia de la API…', error: 'No se pudo cargar la referencia de la API. Recarga la página.' },
   fr: { loading: "Chargement de la référence de l'API…", error: "Impossible de charger la référence de l'API. Rechargez la page." }
 }
@@ -22,112 +13,65 @@ const MESSAGES: Record<string, { loading: string; error: string }> = {
 const { isDark, lang } = useData()
 const messages = computed(() => MESSAGES[lang.value] ?? MESSAGES.en)
 
-// Scalar is large, so it is loaded only on the API reference page.
-// Loading and error states use render functions: the runtime-only Vue build cannot compile `template` strings.
-// Their styles are global (below) because scoped styles do not reach these child components.
+const status = (key: 'loading' | 'error') => () => h('p', { class: 'scalar-status' }, messages.value[key])
+
+// Scalar is large; load it only on the reference page.
 const ApiReference = defineAsyncComponent({
-  loader: () => import('@scalar/api-reference').then((module) => module.ApiReference),
-  loadingComponent: {
-    render: () =>
-      h('div', { class: 'scalar-api-status' }, [h('div', { class: 'scalar-api-spinner' }), h('p', messages.value.loading)])
-  },
-  errorComponent: {
-    render: () => h('div', { class: 'scalar-api-status' }, h('p', messages.value.error))
-  },
-  delay: 200,
-  timeout: 10000
+  loader: () =>
+    Promise.all([
+      import('@scalar/api-reference'),
+      import('@scalar/api-reference/style.css')
+    ]).then(([m]) => m.ApiReference),
+  loadingComponent: status('loading'),
+  errorComponent: status('error'),
+  timeout: 15000
 })
 
-const props = defineProps({
-  // Override to point at any spec. By default the spec follows the page language.
-  specUrl: {
-    type: String,
-    default: ''
-  }
-})
+const props = defineProps<{
+  /** Overrides the spec. By default it follows the page language. */
+  specUrl?: string
+}>()
 
 // One spec per locale, produced by the openapi-fixer pipeline (see README).
 const SPEC_BY_LANG: Record<string, string> = {
   en: '/openapi.en.json',
-  pt: '/openapi.pt-BR.json',
+  'pt-BR': '/openapi.pt-BR.json',
   es: '/openapi.es.json',
   fr: '/openapi.fr.json'
 }
 
-const resolvedSpecUrl = computed(() => props.specUrl || SPEC_BY_LANG[lang.value] || SPEC_BY_LANG.en)
-
-// Scalar reads its configuration once, so the component is recreated when the theme changes.
-const themeKey = computed(() => (isDark.value ? 'dark' : 'light'))
+const specUrl = computed(() => props.specUrl || SPEC_BY_LANG[lang.value] || SPEC_BY_LANG.en)
 
-const scalarConfig = computed(() => ({
-  spec: {
-    url: resolvedSpecUrl.value
-  },
-  // 'none' disables Scalar's built-in themes; the <style> block below maps its variables onto VitePress's.
+const configuration = computed(() => ({
+  spec: { url: specUrl.value },
+  // Scalar's own themes and fonts are off; the variables below map it onto VitePress.
   theme: 'none' as const,
-  darkMode: isDark.value,
   withDefaultFonts: false,
-  // VitePress already has a theme switch.
-  hideDarkModeButton: true,
-  layout: 'modern' as const,
-  showSidebar: true,
-  searchHotKey: 'k' as const,
+  // VitePress owns the appearance switch.
+  hideDarkModeToggle: true,
+  forceDarkModeState: (isDark.value ? 'dark' : 'light') as 'dark' | 'light',
   metaData: {
     title: 'Shelfline Field API Reference',
     description: 'Interactive reference for the fictional Shelfline Field API'
   }
 }))
-
-// Render Scalar only on the client, after the page is idle.
-const isMounted = ref(false)
-onMounted(() => {
-  const show = () => (isMounted.value = true)
-  if ('requestIdleCallback' in window) window.requestIdleCallback(show)
-  else setTimeout(show, 0)
-})
 </script>
 
-<style>
-.scalar-api-container {
-  display: flex;
-  flex-direction: column;
-  width: 100%;
-  height: 100vh;
-  margin: 0;
-  padding: 0;
-}
+<template>
+  <!-- Remount on theme or spec change: Scalar reads both only at startup. -->
+  <ApiReference :key="`${isDark}-${specUrl}`" :configuration="configuration" />
+</template>
 
-.scalar-api-status {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  height: 80vh;
-  gap: 1rem;
-  font-size: 1.2rem;
+<style>
+.scalar-status {
+  padding: 96px 24px;
+  text-align: center;
   color: var(--vp-c-text-2);
 }
 
-.scalar-api-spinner {
-  width: 40px;
-  height: 40px;
-  border: 3px solid var(--vp-c-bg-mute);
-  border-top: 3px solid var(--vp-c-brand-1);
-  border-radius: 50%;
-  animation: scalar-api-spin 1s cubic-bezier(0.68, -0.55, 0.265, 1.55) infinite;
-  box-shadow: var(--vp-shadow-1);
-}
-
-@keyframes scalar-api-spin {
-  0% { transform: rotate(0deg); }
-  100% { transform: rotate(360deg); }
-}
-
-/* Map Scalar's theme variables onto VitePress's. */
 .scalar-api-reference {
-  --scalar-font: var(--vp-font-family-body, 'Poppins', sans-serif);
-  --scalar-font-code: var(--vp-font-family-mono, monospace);
-  --scalar-heading-font: var(--vp-font-family-heading, 'Hepta Slab', serif);
+  --scalar-font: var(--vp-font-family-base);
+  --scalar-font-code: var(--vp-font-family-mono);
 
   --scalar-color-1: var(--vp-c-text-1);
   --scalar-color-2: var(--vp-c-text-2);
@@ -139,85 +83,32 @@ onMounted(() => {
   --scalar-background-3: var(--vp-c-bg-soft);
   --scalar-background-accent: var(--vp-c-brand-soft);
 
-  --scalar-border-color: var(--vp-c-border);
-  --scalar-border-radius: var(--vp-radius-md);
-  --scalar-border-radius-lg: var(--vp-radius-lg);
+  --scalar-border-color: var(--vp-c-divider);
+  --scalar-radius: 6px;
+  --scalar-radius-lg: 8px;
 
-  --scalar-shadow-1: var(--vp-shadow-1);
-  --scalar-shadow-2: var(--vp-shadow-2);
-  --scalar-shadow-3: var(--vp-shadow-3);
-
-  /* HTTP method colors */
-  --scalar-color-green: #34c759;
-  --scalar-color-red: #ff3b30;
-  --scalar-color-orange: #ff9500;
-  --scalar-color-blue: #007aff;
-  --scalar-color-purple: #af52de;
-  --scalar-color-yellow: #ffcc00;
+  --scalar-color-green: var(--vp-c-green-1);
+  --scalar-color-red: var(--vp-c-red-1);
+  --scalar-color-orange: var(--vp-c-yellow-1);
+  --scalar-color-yellow: var(--vp-c-yellow-1);
+  --scalar-color-blue: var(--vp-c-indigo-1);
+  --scalar-color-purple: var(--vp-c-purple-1);
+}
 
-  --scalar-sidebar-background-1: var(--vp-c-bg-alt);
+/*
+ * Scalar re-declares its sidebar palette on `.light-mode .t-doc__sidebar` in a
+ * stylesheet that loads after this one, so this selector needs one more step.
+ */
+.scalar-api-reference .t-doc__sidebar.t-doc__sidebar {
+  --scalar-sidebar-background-1: var(--vp-c-bg);
   --scalar-sidebar-border-color: var(--vp-c-divider);
   --scalar-sidebar-color-1: var(--vp-c-text-1);
   --scalar-sidebar-color-2: var(--vp-c-text-2);
   --scalar-sidebar-color-active: var(--vp-c-brand-1);
-  --scalar-sidebar-item-hover-background: var(--vp-c-brand-soft);
+  --scalar-sidebar-item-hover-background: var(--vp-c-default-soft);
   --scalar-sidebar-item-active-background: var(--vp-c-brand-soft);
-  --scalar-sidebar-search-background: var(--vp-c-bg-soft);
-  --scalar-sidebar-search-border-color: var(--vp-c-border);
+  --scalar-sidebar-search-background: var(--vp-c-bg);
+  --scalar-sidebar-search-border-color: var(--vp-c-divider);
   --scalar-sidebar-search-color: var(--vp-c-text-2);
 }
-
-.scalar-api-reference .scalar-heading {
-  font-family: var(--scalar-heading-font);
-}
-
-/* Buttons */
-.scalar-api-reference .scalar-button {
-  border-radius: var(--vp-radius-md) !important;
-  font-weight: 500 !important;
-  box-shadow: var(--vp-shadow-1) !important;
-  transition: all 150ms var(--vp-ease-out) !important;
-  will-change: transform, box-shadow;
-}
-.scalar-api-reference .scalar-button:hover {
-  transform: translateY(-1px);
-  box-shadow: var(--vp-shadow-2) !important;
-}
-.scalar-api-reference .scalar-button:active {
-  transform: translateY(0);
-}
-
-/* Cards */
-.scalar-api-reference .scalar-card {
-  border-radius: var(--vp-radius-lg) !important;
-  box-shadow: var(--vp-shadow-1) !important;
-  transition: all 250ms var(--vp-ease-out) !important;
-  will-change: transform, box-shadow;
-}
-.scalar-api-reference .scalar-card:hover {
-  transform: translateY(-2px);
-  box-shadow: var(--vp-shadow-2) !important;
-}
-
-/* Code blocks */
-.scalar-api-reference .scalar-code-block,
-.scalar-api-reference .scalar-code-block pre {
-  border-radius: var(--vp-radius-md) !important;
-}
-
-/* Scrollbar */
-.scalar-api-reference ::-webkit-scrollbar {
-  width: 8px;
-  height: 8px;
-}
-.scalar-api-reference ::-webkit-scrollbar-track {
-  background: var(--vp-c-bg-soft);
-}
-.scalar-api-reference ::-webkit-scrollbar-thumb {
-  background: var(--vp-c-text-3);
-  border-radius: var(--vp-radius-sm);
-}
-.scalar-api-reference ::-webkit-scrollbar-thumb:hover {
-  background: var(--vp-c-text-2);
-}
 </style>
diff --git a/docs/.vitepress/components/SpotlightBackground.vue b/docs/.vitepress/components/SpotlightBackground.vue
deleted file mode 100644
index 27f3b30..0000000
--- a/docs/.vitepress/components/SpotlightBackground.vue
+++ /dev/null
@@ -1,255 +0,0 @@
-<template>
-  <div
-    ref="containerRef"
-    class="spotlight-container"
-    :class="{ 'spotlight-active': isActive }"
-  >
-    <div class="spotlight-glow" :style="spotlightStyle" />
-    <div class="spotlight-overlay" />
-    <slot />
-  </div>
-</template>
-
-<script setup lang="ts">
-import { computed, onMounted, onUnmounted, ref } from 'vue'
-
-const containerRef = ref<HTMLElement | null>(null)
-const isActive = ref(false)
-// Pointer position as a percentage of the container.
-const mousePosition = ref({ x: 50, y: 50 })
-
-const spotlightStyle = computed(() => ({
-  '--mouse-x': `${mousePosition.value.x}%`,
-  '--mouse-y': `${mousePosition.value.y}%`
-}))
-
-const clamp = (n: number) => Math.max(0, Math.min(100, n))
-
-let cleanup: (() => void) | undefined
-
-onMounted(() => {
-  const container = containerRef.value
-  if (!container) return
-
-  const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)')
-  let rafId = 0
-
-  const moveTo = (clientX: number, clientY: number) => {
-    if (reducedMotion.matches) return
-    cancelAnimationFrame(rafId)
-    rafId = requestAnimationFrame(() => {
-      const rect = container.getBoundingClientRect()
-      mousePosition.value = {
-        x: clamp(((clientX - rect.left) / rect.width) * 100),
-        y: clamp(((clientY - rect.top) / rect.height) * 100)
-      }
-    })
-  }
-
-  const onMouseMove = (e: MouseEvent) => moveTo(e.clientX, e.clientY)
-  const onTouchMove = (e: TouchEvent) => {
-    const touch = e.touches[0]
-    if (touch) moveTo(touch.clientX, touch.clientY)
-  }
-  const onMouseEnter = () => (isActive.value = true)
-  const onMouseLeave = () => {
-    isActive.value = false
-    if (!reducedMotion.matches) mousePosition.value = { x: 50, y: 50 }
-  }
-
-  const addListeners = () => {
-    container.addEventListener('mouseenter', onMouseEnter, { passive: true })
-    container.addEventListener('mouseleave', onMouseLeave, { passive: true })
-    window.addEventListener('mousemove', onMouseMove, { passive: true })
-    window.addEventListener('touchmove', onTouchMove, { passive: true })
-  }
-  const removeListeners = () => {
-    container.removeEventListener('mouseenter', onMouseEnter)
-    container.removeEventListener('mouseleave', onMouseLeave)
-    window.removeEventListener('mousemove', onMouseMove)
-    window.removeEventListener('touchmove', onTouchMove)
-  }
-
-  addListeners()
-
-  // Turn the spotlight on if the hero is already in view once layout settles.
-  const initialCheck = setTimeout(() => {
-    const rect = container.getBoundingClientRect()
-    if (rect.top < window.innerHeight && rect.bottom > 0) isActive.value = true
-  }, 100)
-
-  // Stop tracking the pointer while the hero is off screen.
-  const observer = new IntersectionObserver(
-    ([entry]) => {
-      if (entry.isIntersecting) {
-        addListeners()
-      } else {
-        removeListeners()
-        isActive.value = false
-      }
-    },
-    { threshold: 0.1, rootMargin: '50px' }
-  )
-  observer.observe(container)
-
-  cleanup = () => {
-    clearTimeout(initialCheck)
-    cancelAnimationFrame(rafId)
-    observer.disconnect()
-    removeListeners()
-  }
-})
-
-onUnmounted(() => cleanup?.())
-</script>
-
-<style scoped>
-.spotlight-container {
-  position: relative;
-  min-height: 100vh;
-  background: var(--vp-c-bg);
-  overflow: hidden;
-  transform: translateZ(0);
-  --mouse-x: 50%;
-  --mouse-y: 50%;
-}
-
-.spotlight-glow {
-  position: absolute;
-  inset: 0;
-  pointer-events: none;
-  z-index: 1;
-  opacity: 0.6;
-  background: radial-gradient(
-    600px circle at var(--mouse-x) var(--mouse-y),
-    rgba(79, 70, 229, 0.45) 0%,
-    rgba(79, 70, 229, 0.25) 18%,
-    rgba(147, 51, 234, 0.15) 50%,
-    transparent 85%
-  );
-  filter: blur(28px);
-  transition:
-    opacity var(--vp-transition-timing-base) var(--vp-ease-out),
-    background var(--vp-transition-timing-fast) var(--vp-ease-out),
-    filter var(--vp-transition-timing-fast) var(--vp-ease-out);
-  transform: translateZ(0);
-  will-change: background, opacity;
-}
-
-.spotlight-container.spotlight-active .spotlight-glow {
-  opacity: 0.9;
-}
-
-.spotlight-overlay {
-  position: absolute;
-  inset: 0;
-  background: linear-gradient(
-    135deg,
-    rgba(79, 70, 229, 0.03) 0%,
-    transparent 60%,
-    rgba(147, 51, 234, 0.04) 100%
-  );
-  z-index: 0;
-  pointer-events: none;
-  transition: opacity var(--vp-transition-timing-base) var(--vp-ease-out);
-}
-
-.dark .spotlight-glow {
-  opacity: 0.5;
-  background: radial-gradient(
-    720px circle at var(--mouse-x) var(--mouse-y),
-    rgba(79, 70, 229, 0.2) 0%,
-    rgba(147, 51, 234, 0.15) 50%,
-    transparent 85%
-  );
-  filter: blur(24px);
-}
-
-.dark .spotlight-container.spotlight-active .spotlight-glow {
-  opacity: 0.8;
-}
-
-.dark .spotlight-overlay {
-  background: linear-gradient(
-    135deg,
-    rgba(79, 70, 229, 0.12) 0%,
-    transparent 60%,
-    rgba(147, 51, 234, 0.15) 100%
-  );
-}
-
-/* Without JavaScript, keep a centered glow. */
-@media (scripting: none) {
-  .spotlight-glow {
-    opacity: 0.7 !important;
-    background: radial-gradient(
-      600px circle at 50% 50%,
-      rgba(79, 70, 229, 0.4) 0%,
-      rgba(147, 51, 234, 0.2) 50%,
-      transparent 85%
-    ) !important;
-  }
-
-  .dark .spotlight-glow {
-    opacity: 0.5 !important;
-    background: radial-gradient(
-      700px circle at 50% 50%,
-      rgba(79, 70, 229, 0.15) 0%,
-      rgba(147, 51, 234, 0.1) 50%,
-      transparent 85%
-    ) !important;
-  }
-}
-
-@media (max-width: 768px) {
-  .spotlight-glow {
-    filter: blur(24px);
-  }
-
-  .dark .spotlight-glow {
-    filter: blur(18px);
-  }
-}
-
-@media (max-width: 480px) {
-  .spotlight-glow {
-    filter: blur(16px);
-  }
-
-  .dark .spotlight-glow {
-    filter: blur(12px);
-  }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .spotlight-glow {
-    transition: none;
-    opacity: 0.5;
-    background: radial-gradient(
-      800px circle at 50% 50%,
-      rgba(79, 70, 229, 0.15) 0%,
-      rgba(147, 51, 234, 0.08) 50%,
-      transparent 85%
-    );
-  }
-
-  .spotlight-container.spotlight-active .spotlight-glow {
-    opacity: 0.3;
-  }
-}
-
-@media (prefers-contrast: high) {
-  .spotlight-glow {
-    opacity: 0.2;
-  }
-
-  .spotlight-overlay {
-    opacity: 0.1;
-  }
-}
-
-.spotlight-container > :slotted(*) {
-  position: relative;
-  z-index: 2;
-}
-</style>
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 2ddf5fe..49d2876 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -1,258 +1,194 @@
-import { defineConfig } from 'vitepress'
+import { BookOpen, Gauge, KeyRound, ListOrdered, SquareCode, TriangleAlert } from 'lucide-static'
+import { defineConfig, type DefaultTheme, type LocaleSpecificConfig } from 'vitepress'
 
-// Theme options that are the same in every locale.
-const shared = {
-  siteTitle: false as const,
-  logo: {
-    light: '/logo-light.svg',
-    dark: '/logo-dark.svg',
-    alt: 'API Docs Starter Logo'
+// Every string that changes per language. Adding a locale means adding an
+// entry here, its docs/<code>/ pages and docs/public/openapi.<lang>.json.
+const LOCALES = {
+  en: {
+    label: 'English',
+    lang: 'en',
+    description: 'Multilingual API documentation portal with VitePress and Scalar',
+    nav: { home: 'Home', guide: 'API guide', reference: 'API reference' },
+    sidebar: {
+      guide: 'API guide',
+      intro: 'Introduction',
+      auth: 'Authentication',
+      limits: 'Rate limits',
+      examples: 'Examples',
+      reference: 'Reference',
+      pagination: 'Pagination & links',
+      errors: 'Errors'
+    },
+    outline: 'On this page',
+    prev: 'Previous page',
+    next: 'Next page',
+    search: null
   },
-  footer: {
-    copyright: `
-    API Docs Starter © 2025 · by
-    <a href="https://github.com/rafactx" target="_blank" rel="noopener noreferrer" style="display: inline-flex; align-items: center; gap: 4px;">
-    <span>rafactx</span>
-      <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 24 24" style="vertical-align: text-bottom;">
-        <path d="M12 .5C5.73.5.5 5.73.5 12c0 5.09 3.29 9.4 7.86 10.94.58.1.79-.25.79-.56v-2.15c-3.2.7-3.88-1.54-3.88-1.54-.53-1.35-1.3-1.71-1.3-1.71-1.06-.73.08-.72.08-.72 1.18.08 1.8 1.22 1.8 1.22 1.04 1.78 2.72 1.27 3.38.97.1-.75.41-1.27.75-1.56-2.56-.29-5.26-1.28-5.26-5.7 0-1.26.45-2.29 1.2-3.1-.12-.3-.52-1.5.11-3.12 0 0 .98-.31 3.2 1.19a11.1 11.1 0 0 1 5.82 0c2.22-1.5 3.2-1.19 3.2-1.19.63 1.62.23 2.82.11 3.12.75.81 1.2 1.84 1.2 3.1 0 4.43-2.7 5.41-5.28 5.69.42.36.8 1.08.8 2.18v3.23c0 .31.21.67.8.56A10.5 10.5 0 0 0 23.5 12C23.5 5.73 18.27.5 12 .5Z"/>
-      </svg>
-    </a>`
+  pt: {
+    label: 'Português (Brasil)',
+    lang: 'pt-BR',
+    description: 'Portal de documentação de API multilíngue com VitePress e Scalar',
+    nav: { home: 'Início', guide: 'Guia da API', reference: 'Referência da API' },
+    sidebar: {
+      guide: 'Guia da API',
+      intro: 'Introdução',
+      auth: 'Autenticação',
+      limits: 'Limites',
+      examples: 'Exemplos',
+      reference: 'Referência',
+      pagination: 'Paginação e links',
+      errors: 'Erros'
+    },
+    outline: 'Nesta página',
+    prev: 'Página anterior',
+    next: 'Próxima página',
+    search: ['Buscar', 'Nenhum resultado para', 'Limpar busca', 'selecionar', 'navegar', 'fechar']
   },
-  socialLinks: [{ icon: 'github' as const, link: 'https://github.com/rafactx/api-docs-starter' }]
+  es: {
+    label: 'Español',
+    lang: 'es',
+    description: 'Portal de documentación de API multilingüe con VitePress y Scalar',
+    nav: { home: 'Inicio', guide: 'Guía de la API', reference: 'Referencia de la API' },
+    sidebar: {
+      guide: 'Guía de la API',
+      intro: 'Introducción',
+      auth: 'Autenticación',
+      limits: 'Límites',
+      examples: 'Ejemplos',
+      reference: 'Referencia',
+      pagination: 'Paginación y enlaces',
+      errors: 'Errores'
+    },
+    outline: 'En esta página',
+    prev: 'Página anterior',
+    next: 'Página siguiente',
+    search: ['Buscar', 'Sin resultados para', 'Borrar búsqueda', 'seleccionar', 'navegar', 'cerrar']
+  },
+  fr: {
+    label: 'Français',
+    lang: 'fr',
+    description: "Portail de documentation d'API multilingue avec VitePress et Scalar",
+    nav: { home: 'Accueil', guide: "Guide de l'API", reference: "Référence de l'API" },
+    sidebar: {
+      guide: "Guide de l'API",
+      intro: 'Introduction',
+      auth: 'Authentification',
+      limits: 'Limites',
+      examples: 'Exemples',
+      reference: 'Référence',
+      pagination: 'Pagination et liens',
+      errors: 'Erreurs'
+    },
+    outline: 'Sur cette page',
+    prev: 'Page précédente',
+    next: 'Page suivante',
+    search: ['Rechercher', 'Aucun résultat pour', 'Effacer la recherche', 'sélectionner', 'naviguer', 'fermer']
+  }
+} as const
+
+type Strings = (typeof LOCALES)[keyof typeof LOCALES]
+
+// Icons are inlined into the sidebar labels; style.css sizes them.
+const icon = (svg: string) => svg.replace('<svg', '<svg aria-hidden="true"')
+
+function sidebar(code: string, t: Strings['sidebar']): DefaultTheme.SidebarItem[] {
+  const item = (svg: string, text: string, page: string) => ({
+    text: `${icon(svg)}<span>${text}</span>`,
+    docFooterText: text,
+    link: `/${code}/${page}`
+  })
+
+  return [
+    {
+      text: t.guide,
+      collapsed: false,
+      items: [
+        item(BookOpen, t.intro, 'intro'),
+        item(KeyRound, t.auth, 'authentication'),
+        item(Gauge, t.limits, 'rate-limits'),
+        item(SquareCode, t.examples, 'examples')
+      ]
+    },
+    {
+      text: t.reference,
+      collapsed: false,
+      items: [
+        item(ListOrdered, t.pagination, 'pagination'),
+        item(TriangleAlert, t.errors, 'errors')
+      ]
+    }
+  ]
+}
+
+function locale(code: string, s: Strings): LocaleSpecificConfig<DefaultTheme.Config> & { label: string; link: string } {
+  return {
+    label: s.label,
+    lang: s.lang,
+    link: `/${code}/`,
+    description: s.description,
+    themeConfig: {
+      nav: [
+        { text: s.nav.home, link: `/${code}/` },
+        // Active on every guide page, not only the first one.
+        { text: s.nav.guide, link: `/${code}/intro`, activeMatch: `^/${code}/(?!api-reference)[^/]+` },
+        { text: s.nav.reference, link: `/${code}/api-reference` }
+      ],
+      sidebar: sidebar(code, s.sidebar),
+      outline: { level: [2, 3], label: s.outline },
+      docFooter: { prev: s.prev, next: s.next }
+    }
+  }
+}
+
+function searchLocale([button, noResults, reset, select, navigate, close]: readonly string[]) {
+  return {
+    translations: {
+      button: { buttonText: button, buttonAriaLabel: button },
+      modal: {
+        noResultsText: noResults,
+        resetButtonTitle: reset,
+        footer: { selectText: select, navigateText: navigate, closeText: close }
+      }
+    }
+  }
 }
 
+const entries = Object.entries(LOCALES)
+
 export default defineConfig({
+  title: 'API Documentation Starter',
+  description: LOCALES.en.description,
+  lang: 'en',
   cleanUrls: true,
 
   head: [
-    ['meta', { name: 'theme-color', content: '#646cff' }],
-    ['link', { rel: 'icon', href: '/favicon.svg' }]
+    ['meta', { name: 'theme-color', content: '#4f46e5' }],
+    ['link', { rel: 'icon', href: '/logo-light.svg', type: 'image/svg+xml' }],
+    ['link', { rel: 'preload', href: '/fonts/Poppins-Regular.woff2', as: 'font', type: 'font/woff2', crossorigin: '' }],
+    ['link', { rel: 'preload', href: '/fonts/HeptaSlab-SemiBold.woff2', as: 'font', type: 'font/woff2', crossorigin: '' }]
   ],
 
-  // VitePress enables local search only from the root themeConfig; per-locale strings go in options.locales.
   themeConfig: {
+    siteTitle: false,
+    logo: { light: '/logo-light.svg', dark: '/logo-dark.svg', alt: 'API Docs Starter' },
+    socialLinks: [{ icon: 'github', link: 'https://github.com/rafactx/api-docs-starter' }],
+    // Shown only on pages without a sidebar, which here means the home pages.
+    footer: { message: 'MIT License · <a href="https://github.com/rafactx">rafactx</a>' },
     search: {
       provider: 'local',
       options: {
-        locales: {
-          pt: {
-            translations: {
-              button: { buttonText: 'Buscar documentos', buttonAriaLabel: 'Buscar documentos' },
-              modal: {
-                noResultsText: 'Nenhum resultado encontrado',
-                resetButtonTitle: 'Limpar busca',
-                footer: { selectText: 'para selecionar', navigateText: 'para navegar', closeText: 'para fechar' }
-              }
-            }
-          },
-          es: {
-            translations: {
-              button: { buttonText: 'Buscar en la documentación', buttonAriaLabel: 'Buscar en la documentación' },
-              modal: {
-                noResultsText: 'No se encontraron resultados',
-                resetButtonTitle: 'Borrar búsqueda',
-                footer: { selectText: 'para seleccionar', navigateText: 'para navegar', closeText: 'para cerrar' }
-              }
-            }
-          },
-          fr: {
-            translations: {
-              button: { buttonText: 'Rechercher dans la documentation', buttonAriaLabel: 'Rechercher dans la documentation' },
-              modal: {
-                noResultsText: 'Aucun résultat',
-                resetButtonTitle: 'Effacer la recherche',
-                footer: { selectText: 'pour sélectionner', navigateText: 'pour naviguer', closeText: 'pour fermer' }
-              }
-            }
-          }
-        }
+        locales: Object.fromEntries(
+          entries.filter(([, s]) => s.search).map(([code, s]) => [code, searchLocale(s.search!)])
+        )
       }
     }
   },
 
-  locales: {
-    pt: {
-      label: 'Português (Brasil)',
-      lang: 'pt',
-      title: 'API Documentation Starter',
-      description: 'Portal de documentação de API multilíngue com VitePress e Scalar',
-      link: '/pt/',
-      themeConfig: {
-        ...shared,
-        nav: [
-          { text: 'Início', link: '/pt/' },
-          { text: 'Guia da API', link: '/pt/intro' },
-          { text: 'Referência da API', link: '/pt/api-reference' }
-        ],
-        sidebar: [
-          {
-            text: 'Guia da API',
-            items: [
-              { text: 'Introdução', link: '/pt/intro' },
-              { text: 'Autenticação', link: '/pt/authentication' },
-              { text: 'Limites', link: '/pt/rate-limits' },
-              { text: 'Exemplos', link: '/pt/examples' }
-            ]
-          },
-          {
-            text: 'Referência',
-            items: [
-              { text: 'Paginação e links', link: '/pt/pagination' },
-              { text: 'Erros', link: '/pt/errors' }
-            ]
-          }
-        ],
-        outline: {
-          level: [2, 3],
-          label: 'Nesta página'
-        },
-        docFooter: {
-          prev: 'Página anterior',
-          next: 'Próxima página'
-        }
-      }
-    },
-
-    en: {
-      label: 'English',
-      lang: 'en',
-      title: 'API Documentation Starter',
-      description: 'Multilingual API documentation portal built with VitePress and Scalar',
-      link: '/en/',
-      themeConfig: {
-        ...shared,
-        nav: [
-          { text: 'Home', link: '/en/' },
-          { text: 'API Guide', link: '/en/intro' },
-          { text: 'API Reference', link: '/en/api-reference' }
-        ],
-        sidebar: [
-          {
-            text: 'API Guide',
-            items: [
-              { text: 'Introduction', link: '/en/intro' },
-              { text: 'Authentication', link: '/en/authentication' },
-              { text: 'Rate Limits', link: '/en/rate-limits' },
-              { text: 'Examples', link: '/en/examples' }
-            ]
-          },
-          {
-            text: 'Reference',
-            items: [
-              { text: 'Pagination & links', link: '/en/pagination' },
-              { text: 'Errors', link: '/en/errors' }
-            ]
-          }
-        ],
-        outline: {
-          level: [2, 3],
-          label: 'On this page'
-        },
-        docFooter: {
-          prev: 'Previous page',
-          next: 'Next page'
-        }
-      }
-    },
-
-    es: {
-      label: 'Español',
-      lang: 'es',
-      title: 'API Documentation Starter',
-      description: 'Portal de documentación de API multilingüe con VitePress y Scalar',
-      link: '/es/',
-      themeConfig: {
-        ...shared,
-        nav: [
-          { text: 'Inicio', link: '/es/' },
-          { text: 'Guía de la API', link: '/es/intro' },
-          { text: 'Referencia API', link: '/es/api-reference' }
-        ],
-        sidebar: [
-          {
-            text: 'Guía de la API',
-            items: [
-              { text: 'Introducción', link: '/es/intro' },
-              { text: 'Autenticación', link: '/es/authentication' },
-              { text: 'Límites', link: '/es/rate-limits' },
-              { text: 'Ejemplos', link: '/es/examples' }
-            ]
-          },
-          {
-            text: 'Referencia',
-            items: [
-              { text: 'Paginación y enlaces', link: '/es/pagination' },
-              { text: 'Errores', link: '/es/errors' }
-            ]
-          }
-        ],
-        outline: {
-          level: [2, 3],
-          label: 'En esta página'
-        },
-        docFooter: {
-          prev: 'Página anterior',
-          next: 'Siguiente página'
-        }
-      }
-    },
-
-    fr: {
-      label: 'Français',
-      lang: 'fr',
-      title: 'API Documentation Starter',
-      description: "Portail de documentation d'API multilingue avec VitePress et Scalar",
-      link: '/fr/',
-      themeConfig: {
-        ...shared,
-        nav: [
-          { text: 'Accueil', link: '/fr/' },
-          { text: "Guide de l'API", link: '/fr/intro' },
-          { text: "Référence API", link: '/fr/api-reference' }
-        ],
-        sidebar: [
-          {
-            text: "Guide de l'API",
-            items: [
-              { text: 'Introduction', link: '/fr/intro' },
-              { text: 'Authentification', link: '/fr/authentication' },
-              { text: 'Limites', link: '/fr/rate-limits' },
-              { text: 'Exemples', link: '/fr/examples' }
-            ]
-          },
-          {
-            text: 'Référence',
-            items: [
-              { text: 'Pagination et liens', link: '/fr/pagination' },
-              { text: 'Erreurs', link: '/fr/errors' }
-            ]
-          }
-        ],
-        outline: {
-          level: [2, 3],
-          label: 'Sur cette page'
-        },
-        docFooter: {
-          prev: 'Page précédente',
-          next: 'Page suivante'
-        }
-      }
-    }
-  },
+  locales: Object.fromEntries(entries.map(([code, s]) => [code, locale(code, s)])),
 
   vite: {
     ssr: {
       noExternal: ['@scalar/api-reference']
-    },
-    build: {
-      chunkSizeWarningLimit: 1000,
-      minify: 'terser',
-      terserOptions: {
-        compress: {
-          drop_console: true,
-          drop_debugger: true
-        }
-      }
     }
   }
 })
diff --git a/docs/.vitepress/theme/api-docs-responsive.css b/docs/.vitepress/theme/api-docs-responsive.css
deleted file mode 100644
index 3df0a72..0000000
--- a/docs/.vitepress/theme/api-docs-responsive.css
+++ /dev/null
@@ -1,258 +0,0 @@
-/* Styles for VitePress content and for classes Scalar renders (.badge, .breadcrumb, .endpoint-method). */
-
-/* Callouts */
-.custom-block {
-  margin: 1rem 0;
-  border-left: 4px solid transparent;
-  border-radius: var(--vp-radius-lg);
-  padding: 1rem 1.25rem;
-  line-height: 1.6;
-  font-size: clamp(0.875rem, 2.5vw, 1rem);
-  backdrop-filter: var(--vp-backdrop-blur-sm);
-  box-shadow: var(--vp-shadow-1);
-  transition: all var(--vp-transition-timing-base) var(--vp-ease-out);
-}
-
-.custom-block:hover {
-  transform: translateY(-1px);
-  box-shadow: var(--vp-shadow-2);
-}
-
-.custom-block.tip {
-  background: rgba(var(--vp-hero-primary-rgb), 0.1);
-  border-left-color: var(--vp-hero-primary-color);
-}
-
-.custom-block.info {
-  background: rgba(79, 70, 229, 0.08);
-  border-left-color: #4F46E5;
-}
-
-.custom-block.warning {
-  background: rgba(255, 149, 0, 0.1);
-  border-left-color: #ff9500;
-}
-
-.custom-block.danger {
-  background: rgba(255, 59, 48, 0.1);
-  border-left-color: #ff3b30;
-}
-
-.custom-block-title {
-  font-weight: 600;
-  margin-bottom: 0.5rem;
-  font-size: clamp(0.875rem, 2.5vw, 1rem);
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-}
-
-/* Lists */
-.VPDoc ul,
-.VPDoc ol {
-  padding-left: 1.25rem;
-  margin: 1rem 0;
-}
-
-.VPDoc li {
-  margin: 0.5rem 0;
-  line-height: 1.6;
-  font-size: clamp(0.875rem, 2.5vw, 1rem);
-}
-
-.VPDoc li::marker {
-  color: var(--vp-c-brand);
-}
-
-/* Nested list */
-.VPDoc li ul,
-.VPDoc li ol {
-  margin: 0.5rem 0;
-  padding-left: 1rem;
-}
-
-/* Links */
-.VPDoc a {
-  color: var(--vp-c-brand);
-  text-decoration: none;
-  font-weight: 500;
-  transition: all var(--vp-transition-timing-base) var(--vp-ease-out);
-  border-radius: var(--vp-radius-sm);
-  padding: 0.125rem 0.25rem;
-  margin: -0.125rem -0.25rem;
-}
-
-.VPDoc a:hover {
-  background: var(--vp-c-brand-soft);
-  color: var(--vp-c-brand-1);
-  transform: translateY(-1px);
-}
-
-.VPDoc a:focus-visible {
-  outline: 2px solid var(--vp-c-brand);
-  outline-offset: 2px;
-}
-
-/* External links with icon */
-.VPDoc a[target="_blank"]::after {
-  content: "↗";
-  margin-left: 0.25rem;
-  font-size: 0.8em;
-  opacity: 0.7;
-}
-
-/* Breadcrumbs */
-.breadcrumb {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  gap: 0.5rem;
-  margin: 1rem 0;
-  padding: 0.75rem 1rem;
-  background: var(--vp-c-bg-soft);
-  border-radius: var(--vp-radius-md);
-  font-size: clamp(0.75rem, 2vw, 0.875rem);
-}
-
-/* Badges */
-.badge {
-  display: inline-flex;
-  align-items: center;
-  padding: 0.25rem 0.75rem;
-  font-size: clamp(0.7rem, 1.8vw, 0.8rem);
-  font-weight: 500;
-  border-radius: var(--vp-radius-xl);
-  background: var(--vp-c-bg-soft);
-  color: var(--vp-c-text-1);
-  border: 1px solid var(--vp-c-border);
-  margin: 0.125rem;
-  line-height: 1.3;
-}
-
-.badge.primary {
-  background: var(--vp-c-brand-soft);
-  color: var(--vp-c-brand);
-  border-color: var(--vp-c-brand);
-}
-
-.badge.success {
-  background: rgba(52, 199, 89, 0.1);
-  color: #34c759;
-  border-color: #34c759;
-}
-
-.badge.warning {
-  background: rgba(255, 149, 0, 0.1);
-  color: #ff9500;
-  border-color: #ff9500;
-}
-
-.badge.danger {
-  background: rgba(255, 59, 48, 0.1);
-  color: #ff3b30;
-  border-color: #ff3b30;
-}
-
-/* Code blocks */
-.VPDoc pre {
-  position: relative;
-  margin: 1.5rem 0;
-  border-radius: var(--vp-radius-lg);
-  overflow-x: auto;
-  background: var(--vp-c-bg-alt);
-  border: 1px solid var(--vp-c-border);
-  box-shadow: var(--vp-shadow-1);
-}
-
-.VPDoc pre code {
-  display: block;
-  padding: 1rem 1.25rem;
-  font-size: clamp(0.75rem, 2vw, 0.875rem);
-  line-height: 1.5;
-  color: var(--vp-c-text-1);
-  font-family: var(--vp-font-family-mono);
-  background: none;
-  border: none;
-}
-
-/* Horizontal rules */
-.VPDoc hr {
-  margin: 2rem 0;
-  border: none;
-  height: 1px;
-  background: linear-gradient(
-    90deg,
-    transparent,
-    var(--vp-c-divider) 20%,
-    var(--vp-c-divider) 80%,
-    transparent
-  );
-}
-
-.endpoint-method {
-  padding: 0.25rem 0.75rem;
-  border-radius: var(--vp-radius-sm);
-  font-weight: 600;
-  font-size: 0.8rem;
-  text-transform: uppercase;
-  letter-spacing: 0.5px;
-}
-
-.endpoint-method.get {
-  background: rgba(52, 199, 89, 0.15);
-  color: #34c759;
-}
-
-.endpoint-method.post {
-  background: rgba(79, 70, 229, 0.15);
-  color: #4F46E5;
-}
-
-.endpoint-method.put {
-  background: rgba(255, 149, 0, 0.15);
-  color: #ff9500;
-}
-
-.endpoint-method.delete {
-  background: rgba(255, 59, 48, 0.15);
-  color: #ff3b30;
-}
-
-@media (min-width: 768px) {
-  .custom-block {
-    margin: 1.5rem 0;
-    padding: 1.25rem 1.5rem;
-  }
-
-  .VPDoc ul,
-  .VPDoc ol {
-    padding-left: 1.5rem;
-  }
-
-  .breadcrumb {
-    padding: 1rem 1.25rem;
-  }
-}
-
-@media (min-width: 1024px) {
-  .custom-block {
-    margin: 2rem 0;
-    padding: 1.5rem 2rem;
-  }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .custom-block,
-  .VPDoc a {
-    transition: none !important;
-    transform: none !important;
-  }
-}
-
-@media print {
-  .custom-block {
-    break-inside: avoid;
-    box-shadow: none !important;
-    border: 1px solid #ccc !important;
-  }
-}
diff --git a/docs/.vitepress/theme/fonts.css b/docs/.vitepress/theme/fonts.css
index b6bce60..cba9964 100644
--- a/docs/.vitepress/theme/fonts.css
+++ b/docs/.vitepress/theme/fonts.css
@@ -1,26 +1,22 @@
-/* Hepta Slab - Headings */
+/* Self-hosted. Headings ship in one weight (600); see style.css. */
+
 @font-face {
   font-family: 'Hepta Slab';
   src: url('/fonts/HeptaSlab-SemiBold.woff2') format('woff2');
   font-weight: 600;
-  font-style: normal;
   font-display: swap;
 }
 
-/* Poppins - Base text */
 @font-face {
   font-family: 'Poppins';
   src: url('/fonts/Poppins-Regular.woff2') format('woff2');
   font-weight: 400;
-  font-style: normal;
   font-display: swap;
 }
 
-/* Poppins - Semibold (buttons and light emphasis) */
 @font-face {
   font-family: 'Poppins';
   src: url('/fonts/Poppins-SemiBold.woff2') format('woff2');
   font-weight: 600;
-  font-style: normal;
   font-display: swap;
 }
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
index 3e5d1ac..8c02f8c 100644
--- a/docs/.vitepress/theme/index.ts
+++ b/docs/.vitepress/theme/index.ts
@@ -1,23 +1,19 @@
-import '@scalar/api-reference/style.css'
 import type { Theme } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
+import { h } from 'vue'
 
 import ApiCard from '../components/ApiCard.vue'
-import HeroSection from '../components/HeroSection.vue'
+import HomeSpotlight from '../components/HomeSpotlight.vue'
 import ScalarApi from '../components/ScalarApi.vue'
 
-import './api-docs-responsive.css'
 import './fonts.css'
-import './sidebar.css'
 import './style.css'
 
-const theme: Theme = {
+export default {
   extends: DefaultTheme,
+  Layout: () => h(DefaultTheme.Layout, null, { 'home-hero-before': () => h(HomeSpotlight) }),
   enhanceApp({ app }) {
-    app.component('HeroSection', HeroSection)
-    app.component('ScalarApi', ScalarApi)
     app.component('ApiCard', ApiCard)
+    app.component('ScalarApi', ScalarApi)
   }
-}
-
-export default theme
+} satisfies Theme
diff --git a/docs/.vitepress/theme/sidebar.css b/docs/.vitepress/theme/sidebar.css
deleted file mode 100644
index 916d895..0000000
--- a/docs/.vitepress/theme/sidebar.css
+++ /dev/null
@@ -1,117 +0,0 @@
-.VPSidebar {
-  padding: 1.25rem 1.25rem 1.5rem;
-  background-color: var(--vp-c-bg-alt);
-  border-right: 1px solid var(--vp-c-divider);
-  min-width: 240px;
-  max-width: 320px;
-  box-sizing: border-box;
-  transition: background-color 0.25s, border-color 0.22s;
-}
-
-/* Group titles */
-.VPSidebar .group h2 {
-  font-family: 'Hepta Slab', serif;
-  font-size: 0.97rem;
-  font-weight: 600;
-  color: var(--vp-c-text-1);
-  margin: 0 0 0.7rem 0.22rem;
-  padding: 0;
-  border: none;
-  background: none;
-  cursor: default;
-  pointer-events: none;
-  text-transform: uppercase;
-  letter-spacing: 0.7px;
-  opacity: 0.56;
-  user-select: none;
-  transition: color 0.18s, opacity 0.18s;
-}
-
-.VPSidebar .group {
-  margin-bottom: 2.1rem;
-}
-
-/* Separator between groups */
-.VPSidebar .group + .group {
-  border-top: 1px solid var(--vp-c-divider);
-  padding-top: 1.1rem;
-}
-
-/* Links */
-.VPSidebar .item:is(a) {
-  font-family: 'Poppins', sans-serif;
-  font-size: 0.92rem;
-  font-weight: 400;
-  color: var(--vp-c-text-2);
-  padding: 0.32rem 0.75rem 0.32rem 0.9rem;
-  margin-left: 0.06rem;
-  border-radius: 0.55rem;
-  display: flex;
-  align-items: center;
-  gap: 0.56rem;
-  transition:
-    background-color 0.18s cubic-bezier(.42,0,.58,1),
-    color 0.18s cubic-bezier(.42,0,.58,1),
-    font-weight 0.16s;
-  position: relative;
-  outline: none;
-}
-
-.VPSidebar .item:is(a):hover:not(.active),
-.VPSidebar .item:is(a):focus-visible:not(.active) {
-  background-color: rgba(var(--vp-hero-primary-rgb), 0.08);
-  color: var(--vp-c-text-1);
-  text-shadow: 0 1px 3px rgba(120,140,180,0.04);
-}
-
-.VPSidebar .item:is(a).active {
-  color: var(--vp-c-brand);
-  background-color: rgba(var(--vp-hero-primary-rgb), 0.15);
-  font-weight: 600;
-  box-shadow: 0 1.5px 8px 0 rgba(32,94,255,0.03);
-}
-
-/* Dot before the hovered or active link */
-.VPSidebar .item:is(a)::before {
-  content: '';
-  width: 6px;
-  height: 6px;
-  border-radius: 50%;
-  background: var(--vp-c-brand);
-  opacity: 0;
-  margin-right: 0.44rem;
-  transition: opacity 0.25s cubic-bezier(.42,0,.58,1), margin 0.17s;
-  box-shadow: 0 0.5px 2.5px 0 rgba(32,94,255,0.12);
-  flex-shrink: 0;
-}
-
-.VPSidebar .item:is(a):hover::before,
-.VPSidebar .item:is(a).active::before {
-  opacity: 1;
-  margin-right: 0.5rem;
-}
-
-/* Dark mode */
-:root.dark .VPSidebar {
-  background-color: var(--vp-c-bg-alt);
-  border-right-color: var(--vp-c-divider);
-}
-:root.dark .VPSidebar .group h2 {
-  color: var(--vp-c-text-2);
-  opacity: 0.64;
-}
-
-@media (max-width: 900px) {
-  .VPSidebar {
-    padding-left: 0.7rem;
-    padding-right: 0.7rem;
-    min-width: 0;
-    max-width: 100vw;
-  }
-}
-
-.VPSidebar .item:is(a):focus-visible {
-  outline: 2px solid var(--vp-c-brand);
-  outline-offset: 1px;
-  z-index: 1;
-}
diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.css
index 01127d1..ad6b946 100644
--- a/docs/.vitepress/theme/style.css
+++ b/docs/.vitepress/theme/style.css
@@ -1,306 +1,301 @@
-@import './theme.css';
+/*
+ * Thin layer over the VitePress default theme: brand color, fonts and a
+ * handful of surfaces. Layout, spacing and type scale stay VitePress's.
+ * To re-skin the portal, change the brand block.
+ */
 
 :root {
-  --vp-font-family-body: 'Poppins', sans-serif;
-  --vp-font-family-heading: 'Hepta Slab', serif;
-}
-
-body {
-  font-family: var(--vp-font-family-body);
+  /* Brand */
+  --vp-c-brand-1: #4f46e5;
+  --vp-c-brand-2: #4338ca;
+  --vp-c-brand-3: #4f46e5;
+  --vp-c-brand-soft: rgb(79 70 229 / 0.12);
+
+  --vp-font-family-base: 'Poppins', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif;
+  --vp-font-family-heading: 'Hepta Slab', ui-serif, Georgia, serif;
+
+  --vp-home-hero-name-color: var(--vp-c-text-1);
+  --vp-sidebar-bg-color: var(--vp-c-bg);
+
+  /* Callouts: a quiet surface with a hairline edge; the title says what kind it is. */
+  --vp-custom-block-info-bg: var(--vp-c-bg-soft);
+  --vp-custom-block-info-border: var(--vp-c-divider);
+  --vp-custom-block-tip-bg: var(--vp-c-bg-soft);
+  --vp-custom-block-tip-border: var(--vp-c-divider);
+
+  /*
+   * Home rhythm on an 8pt grid, each step double the last:
+   *   --home-gap-xs  title → tagline
+   *   --home-gap-s   tagline → buttons
+   *   --home-gap-l   between blocks (nav → hero, buttons → device → credit → end)
+   */
+  --home-gap-xs: 16px;
+  --home-gap-s: 32px;
+  --home-gap-l: 64px;
+}
+
+.dark {
+  --vp-c-brand-1: #a5b4fc;
+  --vp-c-brand-2: #818cf8;
+  --vp-c-brand-soft: rgb(129 140 248 / 0.16);
+}
+
+@media (max-width: 640px) {
+  :root {
+    --home-gap-l: 48px;
+  }
 }
 
-h1, h2, h3, h4, h5, h6,
-.VPDoc h1, .VPDoc h2, .VPDoc h3 {
+/* Only Hepta Slab SemiBold ships, so every heading uses 600 (no faux bold). */
+.vp-doc h1,
+.vp-doc h2,
+.vp-doc h3,
+.VPHero .name,
+.VPHero .text {
   font-family: var(--vp-font-family-heading);
+  font-weight: 600;
+  text-wrap: balance;
 }
 
-.subtitle {
-  font-size: 1.25rem;
-  line-height: 1.6;
-  color: var(--vp-c-text-2);
-  white-space: pre-line;
-  margin-top: var(--vp-space-md);
-}
-/* Animate color changes when switching between light and dark mode. */
-*,
-*::before,
-*::after {
-  transition:
-    background-color var(--vp-transition-timing-base) var(--vp-ease-out),
-    color var(--vp-transition-timing-base) var(--vp-ease-out),
-    border-color var(--vp-transition-timing-base) var(--vp-ease-out),
-    box-shadow var(--vp-transition-timing-base) var(--vp-ease-out),
-    opacity var(--vp-transition-timing-base) var(--vp-ease-out);
-}
-
-@media (prefers-reduced-motion: reduce) {
-  *,
-  *::before,
-  *::after {
-    animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
-    scroll-behavior: auto !important;
-  }
+.vp-doc p,
+.vp-doc li {
+  text-wrap: pretty;
 }
 
-/* Doc layout, mobile first */
-.VPDoc .content {
-  max-width: 100%;
-  padding: 0 1rem;
+.vp-doc .custom-block a {
+  color: var(--vp-c-brand-1);
 }
 
-.VPDoc .container {
-  max-width: 1280px;
-  padding: 0;
-  margin: 0 auto;
-}
+/* Home ---------------------------------------------------------------- */
 
-.VPDoc .content-container {
-  padding: 1rem;
+/* A stacking context so the spotlight can sit behind the hero (z-index: -1). */
+.VPHome {
+  position: relative;
+  isolation: isolate;
 }
 
-.VPDoc h1 {
-  font-size: clamp(1.75rem, 4vw, 3rem);
-  line-height: 1.2;
-  margin: 1.5rem 0 1rem;
-  font-weight: 700;
+.VPContent.is-home .VPHome {
+  margin-bottom: 0;
+  padding-bottom: var(--home-gap-l);
 }
 
-.VPDoc h2 {
-  font-size: clamp(1.5rem, 3.5vw, 2.25rem);
-  line-height: 1.3;
-  margin: 2rem 0 1rem;
-  font-weight: 600;
+.VPContent.is-home .VPHero {
+  padding-top: calc(var(--vp-nav-height) + var(--vp-layout-top-height, 0px) + var(--home-gap-l));
+  padding-bottom: 0;
 }
 
-.VPDoc h3 {
-  font-size: clamp(1.25rem, 3vw, 1.75rem);
-  line-height: 1.4;
-  margin: 1.5rem 0 0.75rem;
-  font-weight: 600;
+.VPHero .main {
+  margin-inline: auto;
+  text-align: center;
 }
 
-.VPDoc p {
-  font-size: clamp(0.875rem, 2.5vw, 1rem);
-  line-height: 1.7;
-  margin: 1rem 0;
-  color: var(--vp-c-text-1);
+.VPHero .heading {
+  align-items: center;
 }
 
-.VPDoc code:not([class]) {
-  font-size: clamp(0.75rem, 2.2vw, 0.875rem);
-  padding: 0.125rem 0.375rem;
-  background: var(--vp-c-code-bg);
-  color: var(--vp-c-text-code);
-  border-radius: var(--vp-radius-sm);
-  border: 1px solid var(--vp-c-border);
-  font-family: var(--vp-font-family-mono, 'Menlo', 'Monaco', 'Consolas', 'Liberation Mono', 'Courier New', monospace);
+.VPHero .name {
+  max-width: none;
+  letter-spacing: -0.02em;
 }
 
-.VPDoc .vp-code-group,
-.VPDoc div[class*="language-"] {
-  margin: 1.5rem 0;
-  border-radius: var(--vp-radius-lg);
-  overflow: hidden;
-  box-shadow: var(--vp-shadow-1);
+.VPHero .tagline {
+  max-width: 40rem;
+  margin-inline: auto;
+  padding-top: var(--home-gap-xs);
 }
 
-.VPDoc div[class*="language-"] pre {
-  padding: 1rem;
-  font-size: clamp(0.75rem, 2vw, 0.875rem);
-  line-height: 1.5;
-  overflow-x: auto;
-  scrollbar-width: thin;
-  scrollbar-color: var(--vp-c-text-3) transparent;
+.VPHero .actions {
+  justify-content: center;
+  padding-top: var(--home-gap-s);
 }
 
-/* Previous/next page links */
-.VPDoc .prev-next {
-  padding: 1.5rem 0;
-  border-top: 1px solid var(--vp-c-divider);
-  margin-top: 2rem;
+.VPContent.is-home .vp-doc.container {
+  padding-top: 0;
+  margin-top: 0;
 }
 
-.VPDoc .prev-next .pager-link {
+.home-preview {
   display: block;
-  padding: 0.75rem 1rem;
-  margin: 0.5rem 0;
-  border-radius: var(--vp-radius-md);
-  background: var(--vp-c-bg-soft);
-  border: 1px solid var(--vp-c-border);
-  transition: all var(--vp-transition-timing-base) var(--vp-ease-out);
+  width: 100%;
+  max-width: 1080px;
+  height: auto;
+  margin: var(--home-gap-l) auto 0;
 }
 
-/* Appearance toggle */
-.VPNavBarAppearance {
-  transition:
-    opacity var(--vp-transition-timing-base) var(--vp-ease-out),
-    transform var(--vp-transition-timing-fast) var(--vp-ease-out);
-  border-radius: var(--vp-radius-md);
+/* The footer only renders on pages without a sidebar: a credit line, not a band. */
+.VPFooter {
+  border-top: 0;
+  padding-top: 0;
+  padding-bottom: var(--home-gap-l);
+  background-color: transparent;
 }
 
-.VPNavBarAppearance:hover {
-  opacity: 0.8;
-  transform: scale(1.05);
+.VPFooter .message {
+  line-height: 20px;
+  color: var(--vp-c-text-3);
 }
 
-.VPNavBarAppearance:active {
-  transform: scale(0.95);
+.VPFooter .message a {
+  color: inherit;
+  text-underline-offset: 3px;
+  transition: color 150ms ease;
 }
 
-/* Scrollbar */
-::-webkit-scrollbar {
-  width: 8px;
-  height: 8px;
+@media (hover: hover) {
+  .VPFooter .message a:hover {
+    color: var(--vp-c-text-1);
+  }
 }
 
-::-webkit-scrollbar-track {
-  background: var(--vp-c-bg-soft);
-  border-radius: var(--vp-radius-sm);
+/* Header -------------------------------------------------------------- */
+
+/* One opaque bar with a hairline, the same on every page. */
+.VPNav {
+  border-bottom: 1px solid var(--vp-c-divider);
+  background-color: var(--vp-nav-bg-color);
 }
 
-::-webkit-scrollbar-thumb {
-  background: var(--vp-c-text-3);
-  border-radius: var(--vp-radius-sm);
-  transition: background var(--vp-transition-timing-base) var(--vp-ease-out);
+.VPNav .VPNavBarTitle.has-sidebar .title {
+  border-bottom-color: transparent;
 }
 
-::-webkit-scrollbar-thumb:hover {
-  background: var(--vp-c-text-2);
+.VPNavBar .divider {
+  display: none;
 }
 
-/* Text selection */
-::selection {
-  background: rgba(var(--vp-hero-primary-rgb), 0.3);
-  color: var(--vp-c-text-1);
+/*
+ * Above 1440px VitePress pads the docs header from 100vw, which includes the
+ * scrollbar, while the home header and the logo use 100%. The menu shifted by
+ * half a scrollbar between pages; measuring from 100% lines them up.
+ */
+@media (min-width: 1440px) {
+  .VPNav .VPNavBar.has-sidebar .content {
+    padding-right: calc((100% - var(--vp-layout-max-width)) / 2 + 32px);
+  }
 }
 
-::-moz-selection {
-  background: rgba(var(--vp-hero-primary-rgb), 0.3);
-  color: var(--vp-c-text-1);
+/* Sidebar -------------------------------------------------------------- */
+
+/*
+ * No panel, no edge. Group titles lead, items hang off a hairline guide, and
+ * the active page marks that guide in the brand color.
+ */
+.VPSidebar {
+  --guide-inset: 6px;
 }
 
-/* Form fields */
-input,
-textarea,
-select {
-  background: var(--vp-c-bg);
-  border: 1px solid var(--vp-c-border);
-  border-radius: var(--vp-radius-md);
-  padding: var(--vp-space-sm) var(--vp-space-md);
-  color: var(--vp-c-text-1);
-  font-size: var(--vp-font-size-base);
-  transition:
-    border-color var(--vp-transition-timing-base) var(--vp-ease-out),
-    box-shadow var(--vp-transition-timing-base) var(--vp-ease-out);
+.VPSidebar .group + .group {
+  border-top: 0;
+  padding-top: 8px;
 }
 
-input:focus,
-textarea:focus,
-select:focus {
-  outline: none;
-  border-color: var(--vp-hero-primary-color);
-  box-shadow: 0 0 0 3px rgba(var(--vp-hero-primary-rgb), 0.1);
+.VPSidebar .VPSidebarItem.level-0 {
+  padding-bottom: 0;
 }
 
-@media (min-width: 768px) {
-  .VPDoc .content {
-    padding: 0 2rem;
-  }
+.VPSidebar .VPSidebarItem.level-0 > .item {
+  min-height: 32px;
+  padding: 0;
+  align-items: center;
+}
 
-  .VPDoc .content-container {
-    padding: 1.5rem 2rem;
-  }
+.VPSidebar .VPSidebarItem.level-0 > .item > .text {
+  padding: 6px 0;
+  font-weight: 600;
+  line-height: 20px;
+}
 
-  .VPDoc .prev-next {
-    display: flex;
-    justify-content: space-between;
-    gap: 1rem;
-  }
+.VPSidebar .VPSidebarItem.level-0 > .item > .caret {
+  width: 32px;
+  height: 32px;
+  margin-right: -8px;
+  color: var(--vp-c-text-3);
+}
 
-  .VPDoc .prev-next .pager-link {
-    flex: 1;
-    margin: 0;
-  }
+.VPSidebar .VPSidebarItem.level-0 > .items {
+  margin-left: 10px;
+  border-left: 1px solid var(--vp-c-divider);
 }
 
-@media (min-width: 1024px) {
-  .VPDoc .content {
-    padding: 0 3rem;
-  }
+.VPSidebar .VPSidebarItem.level-1 {
+  margin-left: -1px;
+  padding-left: var(--guide-inset);
+}
 
-  .VPDoc .content-container {
-    padding: 2rem 3rem;
-  }
+.VPSidebar .VPSidebarItem.level-1 > .item {
+  padding: 0;
 }
 
-@media (min-width: 1280px) {
-  .VPDoc .content {
-    padding: 0 4rem;
-  }
+.VPSidebar .VPSidebarItem.level-1 > .item > .indicator {
+  display: none;
+}
 
-  .VPDoc .content-container {
-    max-width: 1200px;
-    margin: 0 auto;
-    padding: 2.5rem 0;
-  }
+.VPSidebar .VPSidebarItem.level-1 > .item > .link {
+  position: relative;
+  flex: 1;
+  padding: 6px 10px;
+  border-radius: 6px;
+  transition: background-color 150ms ease;
 }
 
-@media (prefers-contrast: high) {
-  :root {
-    --vp-c-border: #000000;
-    --vp-c-divider: #000000;
-  }
+.VPSidebar .VPSidebarItem.level-1 .text {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 0;
+  line-height: 20px;
+  transition: color 150ms ease;
+}
+
+.VPSidebar .VPSidebarItem.level-1 .text svg {
+  flex: none;
+  width: 20px;
+  height: 20px;
+  stroke-width: 1.75;
+}
 
-  .dark {
-    --vp-c-border: #ffffff;
-    --vp-c-divider: #ffffff;
+@media (hover: hover) {
+  .VPSidebar .VPSidebarItem.level-1 > .item > .link:hover {
+    background-color: var(--vp-c-default-soft);
   }
 
-  input,
-  textarea,
-  select {
-    border-width: 2px;
+  .VPSidebar .VPSidebarItem.level-1:not(.is-active) > .item > .link:hover .text {
+    color: var(--vp-c-text-1);
   }
 }
 
-.VPNavBarAppearance,
-input:focus,
-textarea:focus,
-select:focus {
-  will-change: transform, box-shadow;
+.VPSidebar .VPSidebarItem.level-1.is-active > .item > .link::after {
+  content: '';
+  position: absolute;
+  top: 2px;
+  bottom: 2px;
+  left: calc(-1 * var(--guide-inset));
+  width: 1px;
+  background-color: var(--vp-c-brand-1);
 }
 
-@media print {
-  * {
-    background: white !important;
-    color: black !important;
-    box-shadow: none !important;
-  }
+/* Outline -------------------------------------------------------------- */
 
-  .VPDoc .content {
-    padding: 0 !important;
-  }
+/* Title and links on the sidebar's 32px rows, no rail. */
+.VPDocAsideOutline .content {
+  border-left: 0;
+  padding-left: 0;
 }
 
-.VPContent.has-sidebar .content {
-  padding-left: 0;
-  padding-right: 0;
+.VPDocAsideOutline .outline-marker {
+  display: none;
 }
 
-@media (max-width: 768px) {
-  .VPSidebar {
-    width: 100vw !important;
-    max-width: none !important;
-  }
+.VPDocAsideOutline .outline-title {
+  padding-bottom: 4px;
+  line-height: 20px;
 }
 
-/* 44px touch targets on mobile. Links stay inline so they do not break up paragraphs. */
-@media (max-width: 768px) {
-  button {
-    min-height: 44px;
-    display: flex;
-    align-items: center;
-  }
+.VPDocAsideOutline .outline-link {
+  padding: 6px 0;
+  line-height: 20px;
+}
+
+.VPDocAsideOutline .outline-link.active {
+  color: var(--vp-c-brand-1);
 }
diff --git a/docs/.vitepress/theme/theme.css b/docs/.vitepress/theme/theme.css
deleted file mode 100644
index ad3e843..0000000
--- a/docs/.vitepress/theme/theme.css
+++ /dev/null
@@ -1,106 +0,0 @@
-/* Palette and design tokens. Change the Brand block to re-skin the portal. */
-
-:root {
-  /* === Brand === */
-  --vp-c-brand: #4F46E5;
-  --vp-c-brand-1: #4F46E5;
-  --vp-c-brand-2: #6366F1;
-  --vp-c-brand-3: #4338CA;
-  --vp-c-brand-dark: #4338CA;
-  --vp-c-brand-soft: rgba(79, 70, 229, 0.08);
-
-  /* === Hero === */
-  --vp-hero-primary-color: #4F46E5;
-  --vp-hero-primary-rgb: 79, 70, 229;
-
-  /* === Backgrounds === */
-  --vp-c-bg: #ffffff;
-  --vp-c-bg-alt: #f6f6f6;
-  --vp-c-bg-elv: #ffffff;
-  --vp-c-bg-soft: #f6f6f6;
-  --vp-c-bg-mute: #f1f1f1;
-
-  /* === Text === */
-  --vp-c-text-1: #213547;
-  --vp-c-text-2: #476582;
-  --vp-c-text-3: #8f9198;
-  --vp-c-text-code: #476582;
-
-  /* === Code === */
-  --vp-c-code: #f1f1f1;
-  --vp-c-code-bg: #f1f1f1;
-
-  /* === Borders === */
-  --vp-c-border: #e2e2e2;
-  --vp-c-divider: #e2e2e2;
-  --vp-c-gutter: #f6f6f6;
-
-  /* === Shadows === */
-  --vp-shadow-1: 0 1.5px 5px 0 rgba(28,28,30,0.07), 0 0.5px 2px -1px rgba(28,28,30,0.10);
-  --vp-shadow-2: 0 6px 18px -2px rgba(28,28,30,0.10), 0 2px 8px -2px rgba(28,28,30,0.09);
-  --vp-shadow-3: 0 14px 28px -5px rgba(28,28,30,0.12), 0 4px 12px -4px rgba(28,28,30,0.11);
-
-  /* === Border Radius === */
-  --vp-radius-sm: 0.375rem;
-  --vp-radius-md: 0.5rem;
-  --vp-radius-lg: 0.75rem;
-  --vp-radius-xl: 1rem;
-
-  /* === Spacing === */
-  --vp-space-sm: 0.5rem;
-  --vp-space-md: 1rem;
-  --vp-space-lg: 1.5rem;
-  --vp-space-xl: 2rem;
-  --vp-space-2xl: 3rem;
-
-  /* === Typography === */
-  --vp-font-size-base: 1rem;
-  --vp-font-size-lg: 1.125rem;
-  --vp-font-size-4xl: 2.25rem;
-
-  /* === Transitions === */
-  --vp-transition-timing-fast: 150ms;
-  --vp-transition-timing-base: 250ms;
-  --vp-transition-timing-slow: 350ms;
-  --vp-transition-timing-slower: 500ms;
-
-  --vp-ease-out: cubic-bezier(0.4, 0, 0.2, 1);
-  --vp-ease-in: cubic-bezier(0.4, 0, 1, 1);
-  --vp-ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
-
-  /* === Backdrop blur === */
-  --vp-backdrop-blur: blur(20px);
-  --vp-backdrop-blur-sm: blur(10px);
-}
-
-.dark {
-  /* === Background and text === */
-  --vp-c-bg: #1d1d1f;
-  --vp-c-bg-alt: #222226;
-  --vp-c-bg-elv: #232326;
-  --vp-c-bg-soft: #232326;
-  --vp-c-bg-mute: #19191a;
-
-  --vp-c-text-1: #f6f6fa;
-  --vp-c-text-2: #a1a1a6;
-  --vp-c-text-3: #6e6e73;
-  --vp-c-text-code: #c7d2fe;
-
-  --vp-c-border: #2c2c31;
-  --vp-c-divider: #262629;
-  --vp-c-gutter: #232326;
-  --vp-c-code: #222226;
-  --vp-c-code-bg: #232326;
-
-  /* === Brand === */
-  --vp-c-brand: #818CF8;
-  --vp-c-brand-1: #818CF8;
-  --vp-c-brand-2: #6366F1;
-  --vp-c-brand-3: #4F46E5;
-  --vp-c-brand-soft: rgba(79, 70, 229, 0.16);
-
-  /* === Shadows === */
-  --vp-shadow-1: 0 1.5px 6px 0 rgba(16,16,20,0.19), 0 1.5px 3px -1px rgba(12,12,14,0.10);
-  --vp-shadow-2: 0 6px 18px -2px rgba(20,20,24,0.18), 0 2px 8px -2px rgba(20,20,24,0.13);
-  --vp-shadow-3: 0 14px 28px -5px rgba(20,20,24,0.20), 0 4px 12px -4px rgba(20,20,24,0.17);
-}
diff --git a/docs/en/authentication.md b/docs/en/authentication.md
index 766948c..67ff4ec 100644
--- a/docs/en/authentication.md
+++ b/docs/en/authentication.md
@@ -12,9 +12,9 @@ The API uses **HTTP Basic authentication** over HTTPS. Create an *integration us
 <ApiCard
   title="request.headers"
   :items="[
-    { key: 'Authorization', description: '<code>Basic base64(username:password)</code>. Required on every request.', color: 'blue' },
-    { key: 'X-Client-Name', description: 'Name of your integration, such as <code>erp-sync</code>. Shown in audit logs and used for rate limiting. Required.', color: 'purple' },
-    { key: 'Api-Version', description: 'Release date of the v3 contract you were built against, such as <code>2025-01-15</code>. v3 only.', color: 'pink' }
+    { key: 'Authorization', description: '<code>Basic base64(username:password)</code>. Required on every request.' },
+    { key: 'X-Client-Name', description: 'Name of your integration, such as <code>erp-sync</code>. Shown in audit logs and used for rate limiting. Required.' },
+    { key: 'Api-Version', description: 'Release date of the v3 contract you were built against, such as <code>2025-01-15</code>. v3 only.' }
   ]"
 />
 
diff --git a/docs/en/errors.md b/docs/en/errors.md
index 086e270..c3bbaef 100644
--- a/docs/en/errors.md
+++ b/docs/en/errors.md
@@ -7,12 +7,12 @@ description: Status codes and error bodies returned by the Shelfline Field API.
 
 <script setup>
 const statusTable = [
-  { key: '200 / 201 / 204', description: 'Success. 201 when something was created, 204 when there is no body.', color: 'green' },
-  { key: '400', description: '<code>Bad Request</code>: malformed request or invalid field.', color: 'red' },
-  { key: '401', description: '<code>Unauthorized</code>: missing or invalid credentials.', color: 'red' },
-  { key: '404', description: '<code>Not Found</code>: the resource does not exist in this workspace.', color: 'purple' },
-  { key: '429', description: '<code>Too Many Requests</code>: wait for <code>Retry-After</code> seconds.', color: 'yellow' },
-  { key: '5xx', description: 'Server error. Safe to retry idempotent requests with backoff.', color: 'pink' }
+  { key: '200 / 201 / 204', description: 'Success. 201 when something was created, 204 when there is no body.' },
+  { key: '400', description: '<code>Bad Request</code>: malformed request or invalid field.' },
+  { key: '401', description: '<code>Unauthorized</code>: missing or invalid credentials.' },
+  { key: '404', description: '<code>Not Found</code>: the resource does not exist in this workspace.' },
+  { key: '429', description: '<code>Too Many Requests</code>: wait for <code>Retry-After</code> seconds.' },
+  { key: '5xx', description: 'Server error. Safe to retry idempotent requests with backoff.' }
 ]
 </script>
 
diff --git a/docs/en/index.md b/docs/en/index.md
index 32911dd..f122134 100644
--- a/docs/en/index.md
+++ b/docs/en/index.md
@@ -1,7 +1,25 @@
 ---
-layout: page
-sidebar: false
-aside: false
+layout: home
+
+hero:
+  name: API Documentation Starter
+  tagline: "A multilingual API documentation portal built with VitePress and Scalar. This demo documents the Shelfline Field API, a fictional retail field-execution API."
+  actions:
+    - theme: brand
+      text: "Read the guide"
+      link: /en/intro
+    - theme: alt
+      text: "API reference"
+      link: /en/api-reference
 ---
 
-<HeroSection />
+<img
+  class="home-preview"
+  src="/preview-1080.webp"
+  srcset="/preview-1080.webp 1080w, /preview-1761.webp 1761w"
+  sizes="(min-width: 1144px) 1080px, calc(100vw - 48px)"
+  alt="The portal on a laptop: the Shelfline API reference with its endpoint list, parameters and a cURL example."
+  width="1761"
+  height="1075"
+  decoding="async"
+/>
diff --git a/docs/en/rate-limits.md b/docs/en/rate-limits.md
index 5dbc45c..f27a84b 100644
--- a/docs/en/rate-limits.md
+++ b/docs/en/rate-limits.md
@@ -10,9 +10,9 @@ Limits are applied per workspace and per `X-Client-Name`:
 <ApiCard
   title="limits"
   :items="[
-    { key: 'Sustained', description: '60 requests per minute', color: 'blue' },
-    { key: 'Burst', description: 'up to 20 requests in one second', color: 'purple' },
-    { key: 'Over the limit', description: '<code>429 Too Many Requests</code> with a <code>Retry-After</code> header', color: 'yellow' }
+    { key: 'Sustained', description: '60 requests per minute' },
+    { key: 'Burst', description: 'up to 20 requests in one second' },
+    { key: 'Over the limit', description: '<code>429 Too Many Requests</code> with a <code>Retry-After</code> header' }
   ]"
 />
 
@@ -28,11 +28,11 @@ Limits are applied per workspace and per `X-Client-Name`:
 
 <script setup>
 const methodsTable = [
-  { key: 'GET', description: 'Read', color: 'blue' },
-  { key: 'POST', description: 'Create', color: 'green' },
-  { key: 'PUT', description: 'Replace (v1)', color: 'purple' },
-  { key: 'PATCH', description: 'Update only the fields you send (v3)', color: 'yellow' },
-  { key: 'DELETE', description: 'Delete. Never takes a body; IDs go in the path or query string.', color: 'red' }
+  { key: 'GET', description: 'Read' },
+  { key: 'POST', description: 'Create' },
+  { key: 'PUT', description: 'Replace (v1)' },
+  { key: 'PATCH', description: 'Update only the fields you send (v3)' },
+  { key: 'DELETE', description: 'Delete. Never takes a body; IDs go in the path or query string.' }
 ]
 </script>
 
diff --git a/docs/es/authentication.md b/docs/es/authentication.md
index 978da6a..107df03 100644
--- a/docs/es/authentication.md
+++ b/docs/es/authentication.md
@@ -12,9 +12,9 @@ La API usa **autenticación HTTP Basic** sobre HTTPS. Crea un *usuario de integr
 <ApiCard
   title="request.headers"
   :items="[
-    { key: 'Authorization', description: '<code>Basic base64(username:password)</code>. Obligatorio en cada solicitud.', color: 'blue' },
-    { key: 'X-Client-Name', description: 'Nombre de tu integración, por ejemplo <code>erp-sync</code>. Aparece en los registros de auditoría y se usa para el límite de solicitudes. Obligatorio.', color: 'purple' },
-    { key: 'Api-Version', description: 'Fecha de lanzamiento del contrato v3 con el que desarrollaste tu integración, por ejemplo <code>2025-01-15</code>. Solo v3.', color: 'pink' }
+    { key: 'Authorization', description: '<code>Basic base64(username:password)</code>. Obligatorio en cada solicitud.' },
+    { key: 'X-Client-Name', description: 'Nombre de tu integración, por ejemplo <code>erp-sync</code>. Aparece en los registros de auditoría y se usa para el límite de solicitudes. Obligatorio.' },
+    { key: 'Api-Version', description: 'Fecha de lanzamiento del contrato v3 con el que desarrollaste tu integración, por ejemplo <code>2025-01-15</code>. Solo v3.' }
   ]"
 />
 
diff --git a/docs/es/errors.md b/docs/es/errors.md
index d8b4b16..b687baa 100644
--- a/docs/es/errors.md
+++ b/docs/es/errors.md
@@ -7,12 +7,12 @@ description: Códigos de estado y cuerpos de error que devuelve la Shelfline Fie
 
 <script setup>
 const statusTable = [
-  { key: '200 / 201 / 204', description: 'Éxito. 201 cuando se creó algo, 204 cuando no hay cuerpo.', color: 'green' },
-  { key: '400', description: '<code>Bad Request</code>: solicitud mal formada o campo no válido.', color: 'red' },
-  { key: '401', description: '<code>Unauthorized</code>: credenciales ausentes o no válidas.', color: 'red' },
-  { key: '404', description: '<code>Not Found</code>: el recurso no existe en este workspace.', color: 'purple' },
-  { key: '429', description: '<code>Too Many Requests</code>: espera los segundos indicados en <code>Retry-After</code>.', color: 'yellow' },
-  { key: '5xx', description: 'Error del servidor. Es seguro reintentar las solicitudes idempotentes con retroceso exponencial.', color: 'pink' }
+  { key: '200 / 201 / 204', description: 'Éxito. 201 cuando se creó algo, 204 cuando no hay cuerpo.' },
+  { key: '400', description: '<code>Bad Request</code>: solicitud mal formada o campo no válido.' },
+  { key: '401', description: '<code>Unauthorized</code>: credenciales ausentes o no válidas.' },
+  { key: '404', description: '<code>Not Found</code>: el recurso no existe en este workspace.' },
+  { key: '429', description: '<code>Too Many Requests</code>: espera los segundos indicados en <code>Retry-After</code>.' },
+  { key: '5xx', description: 'Error del servidor. Es seguro reintentar las solicitudes idempotentes con retroceso exponencial.' }
 ]
 </script>
 
diff --git a/docs/es/index.md b/docs/es/index.md
index 32911dd..edb63f9 100644
--- a/docs/es/index.md
+++ b/docs/es/index.md
@@ -1,7 +1,25 @@
 ---
-layout: page
-sidebar: false
-aside: false
+layout: home
+
+hero:
+  name: API Documentation Starter
+  tagline: "Un portal de documentación de API multilingüe con VitePress y Scalar. Esta demo documenta la Shelfline Field API, una API ficticia de ejecución en el punto de venta."
+  actions:
+    - theme: brand
+      text: "Leer la guía"
+      link: /es/intro
+    - theme: alt
+      text: "Referencia de la API"
+      link: /es/api-reference
 ---
 
-<HeroSection />
+<img
+  class="home-preview"
+  src="/preview-1080.webp"
+  srcset="/preview-1080.webp 1080w, /preview-1761.webp 1761w"
+  sizes="(min-width: 1144px) 1080px, calc(100vw - 48px)"
+  alt="El portal en un portátil: la referencia de la API Shelfline con la lista de endpoints, los parámetros y un ejemplo en cURL."
+  width="1761"
+  height="1075"
+  decoding="async"
+/>
diff --git a/docs/es/rate-limits.md b/docs/es/rate-limits.md
index 0ac36bf..b6a0f0f 100644
--- a/docs/es/rate-limits.md
+++ b/docs/es/rate-limits.md
@@ -10,9 +10,9 @@ Los límites se aplican por workspace y por `X-Client-Name`:
 <ApiCard
   title="límites"
   :items="[
-    { key: 'Sustained', description: '60 solicitudes por minuto', color: 'blue' },
-    { key: 'Burst', description: 'hasta 20 solicitudes en un segundo', color: 'purple' },
-    { key: 'Over the limit', description: '<code>429 Too Many Requests</code> con un encabezado <code>Retry-After</code>', color: 'yellow' }
+    { key: 'Sustained', description: '60 solicitudes por minuto' },
+    { key: 'Burst', description: 'hasta 20 solicitudes en un segundo' },
+    { key: 'Over the limit', description: '<code>429 Too Many Requests</code> con un encabezado <code>Retry-After</code>' }
   ]"
 />
 
@@ -28,11 +28,11 @@ Los límites se aplican por workspace y por `X-Client-Name`:
 
 <script setup>
 const methodsTable = [
-  { key: 'GET', description: 'Leer', color: 'blue' },
-  { key: 'POST', description: 'Crear', color: 'green' },
-  { key: 'PUT', description: 'Reemplazar (v1)', color: 'purple' },
-  { key: 'PATCH', description: 'Actualizar solo los campos que envías (v3)', color: 'yellow' },
-  { key: 'DELETE', description: 'Eliminar. Nunca lleva cuerpo; los ID van en la ruta o en la cadena de consulta.', color: 'red' }
+  { key: 'GET', description: 'Leer' },
+  { key: 'POST', description: 'Crear' },
+  { key: 'PUT', description: 'Reemplazar (v1)' },
+  { key: 'PATCH', description: 'Actualizar solo los campos que envías (v3)' },
+  { key: 'DELETE', description: 'Eliminar. Nunca lleva cuerpo; los ID van en la ruta o en la cadena de consulta.' }
 ]
 </script>
 
diff --git a/docs/fr/authentication.md b/docs/fr/authentication.md
index 670d7f6..1078f1a 100644
--- a/docs/fr/authentication.md
+++ b/docs/fr/authentication.md
@@ -12,9 +12,9 @@ L’API utilise l’**authentification HTTP Basic** via HTTPS. Créez un *utilis
 <ApiCard
   title="request.headers"
   :items="[
-    { key: 'Authorization', description: '<code>Basic base64(username:password)</code>. Requis pour chaque requête.', color: 'blue' },
-    { key: 'X-Client-Name', description: 'Nom de votre intégration, par exemple <code>erp-sync</code>. Affiché dans les journaux d’audit et utilisé pour la limitation de débit. Requis.', color: 'purple' },
-    { key: 'Api-Version', description: 'Date de publication du contrat v3 pour lequel votre intégration a été développée, par exemple <code>2025-01-15</code>. v3 uniquement.', color: 'pink' }
+    { key: 'Authorization', description: '<code>Basic base64(username:password)</code>. Requis pour chaque requête.' },
+    { key: 'X-Client-Name', description: 'Nom de votre intégration, par exemple <code>erp-sync</code>. Affiché dans les journaux d’audit et utilisé pour la limitation de débit. Requis.' },
+    { key: 'Api-Version', description: 'Date de publication du contrat v3 pour lequel votre intégration a été développée, par exemple <code>2025-01-15</code>. v3 uniquement.' }
   ]"
 />
 
diff --git a/docs/fr/errors.md b/docs/fr/errors.md
index 85678a2..4671d9d 100644
--- a/docs/fr/errors.md
+++ b/docs/fr/errors.md
@@ -7,12 +7,12 @@ description: "Codes de statut et corps d’erreur renvoyés par l’API Shelflin
 
 <script setup>
 const statusTable = [
-  { key: '200 / 201 / 204', description: 'Succès. 201 quand une ressource a été créée, 204 quand il n’y a pas de corps.', color: 'green' },
-  { key: '400', description: '<code>Bad Request</code> : requête mal formée ou champ invalide.', color: 'red' },
-  { key: '401', description: '<code>Unauthorized</code> : identifiants manquants ou invalides.', color: 'red' },
-  { key: '404', description: '<code>Not Found</code> : la ressource n’existe pas dans ce workspace.', color: 'purple' },
-  { key: '429', description: '<code>Too Many Requests</code> : attendez <code>Retry-After</code> secondes.', color: 'yellow' },
-  { key: '5xx', description: 'Erreur serveur. Vous pouvez réessayer sans risque les requêtes idempotentes avec un backoff.', color: 'pink' }
+  { key: '200 / 201 / 204', description: 'Succès. 201 quand une ressource a été créée, 204 quand il n’y a pas de corps.' },
+  { key: '400', description: '<code>Bad Request</code> : requête mal formée ou champ invalide.' },
+  { key: '401', description: '<code>Unauthorized</code> : identifiants manquants ou invalides.' },
+  { key: '404', description: '<code>Not Found</code> : la ressource n’existe pas dans ce workspace.' },
+  { key: '429', description: '<code>Too Many Requests</code> : attendez <code>Retry-After</code> secondes.' },
+  { key: '5xx', description: 'Erreur serveur. Vous pouvez réessayer sans risque les requêtes idempotentes avec un backoff.' }
 ]
 </script>
 
diff --git a/docs/fr/index.md b/docs/fr/index.md
index 32911dd..eb35d87 100644
--- a/docs/fr/index.md
+++ b/docs/fr/index.md
@@ -1,7 +1,25 @@
 ---
-layout: page
-sidebar: false
-aside: false
+layout: home
+
+hero:
+  name: API Documentation Starter
+  tagline: "Un portail de documentation d’API multilingue construit avec VitePress et Scalar. Cette démo documente la Shelfline Field API, une API fictive d’exécution terrain en magasin."
+  actions:
+    - theme: brand
+      text: "Lire le guide"
+      link: /fr/intro
+    - theme: alt
+      text: "Référence de l’API"
+      link: /fr/api-reference
 ---
 
-<HeroSection />
+<img
+  class="home-preview"
+  src="/preview-1080.webp"
+  srcset="/preview-1080.webp 1080w, /preview-1761.webp 1761w"
+  sizes="(min-width: 1144px) 1080px, calc(100vw - 48px)"
+  alt="Le portail sur un ordinateur portable : la référence de l’API Shelfline avec la liste des endpoints, les paramètres et un exemple cURL."
+  width="1761"
+  height="1075"
+  decoding="async"
+/>
diff --git a/docs/fr/rate-limits.md b/docs/fr/rate-limits.md
index 2c46429..82fea38 100644
--- a/docs/fr/rate-limits.md
+++ b/docs/fr/rate-limits.md
@@ -10,9 +10,9 @@ Les limites s’appliquent par workspace et par `X-Client-Name` :
 <ApiCard
   title="limites"
   :items="[
-    { key: 'Soutenu', description: '60 requêtes par minute', color: 'blue' },
-    { key: 'Rafale', description: 'jusqu’à 20 requêtes en une seconde', color: 'purple' },
-    { key: 'Limite dépassée', description: '<code>429 Too Many Requests</code> avec un en-tête <code>Retry-After</code>', color: 'yellow' }
+    { key: 'Soutenu', description: '60 requêtes par minute' },
+    { key: 'Rafale', description: 'jusqu’à 20 requêtes en une seconde' },
+    { key: 'Limite dépassée', description: '<code>429 Too Many Requests</code> avec un en-tête <code>Retry-After</code>' }
   ]"
 />
 
@@ -28,11 +28,11 @@ Les limites s’appliquent par workspace et par `X-Client-Name` :
 
 <script setup>
 const methodsTable = [
-  { key: 'GET', description: 'Lecture', color: 'blue' },
-  { key: 'POST', description: 'Création', color: 'green' },
-  { key: 'PUT', description: 'Remplacement (v1)', color: 'purple' },
-  { key: 'PATCH', description: 'Met à jour uniquement les champs envoyés (v3)', color: 'yellow' },
-  { key: 'DELETE', description: 'Suppression. N’accepte jamais de corps ; les ID vont dans le chemin ou la query string.', color: 'red' }
+  { key: 'GET', description: 'Lecture' },
+  { key: 'POST', description: 'Création' },
+  { key: 'PUT', description: 'Remplacement (v1)' },
+  { key: 'PATCH', description: 'Met à jour uniquement les champs envoyés (v3)' },
+  { key: 'DELETE', description: 'Suppression. N’accepte jamais de corps ; les ID vont dans le chemin ou la query string.' }
 ]
 </script>
 
diff --git a/docs/pt/authentication.md b/docs/pt/authentication.md
index ad1ce11..13adbe4 100644
--- a/docs/pt/authentication.md
+++ b/docs/pt/authentication.md
@@ -12,9 +12,9 @@ A API usa **autenticação HTTP Basic** sobre HTTPS. Crie um *usuário de integr
 <ApiCard
   title="request.headers"
   :items="[
-    { key: 'Authorization', description: '<code>Basic base64(username:password)</code>. Obrigatório em toda requisição.', color: 'blue' },
-    { key: 'X-Client-Name', description: 'Nome da sua integração, como <code>erp-sync</code>. Aparece nos logs de auditoria e é usado no controle de limite de requisições. Obrigatório.', color: 'purple' },
-    { key: 'Api-Version', description: 'Data de lançamento do contrato v3 para o qual você desenvolveu, como <code>2025-01-15</code>. Somente v3.', color: 'pink' }
+    { key: 'Authorization', description: '<code>Basic base64(username:password)</code>. Obrigatório em toda requisição.' },
+    { key: 'X-Client-Name', description: 'Nome da sua integração, como <code>erp-sync</code>. Aparece nos logs de auditoria e é usado no controle de limite de requisições. Obrigatório.' },
+    { key: 'Api-Version', description: 'Data de lançamento do contrato v3 para o qual você desenvolveu, como <code>2025-01-15</code>. Somente v3.' }
   ]"
 />
 
diff --git a/docs/pt/errors.md b/docs/pt/errors.md
index 92a8bb5..892bfc7 100644
--- a/docs/pt/errors.md
+++ b/docs/pt/errors.md
@@ -7,12 +7,12 @@ description: Códigos de status e corpos de erro retornados pela Shelfline Field
 
 <script setup>
 const statusTable = [
-  { key: '200 / 201 / 204', description: 'Sucesso. 201 quando algo foi criado, 204 quando não há corpo.', color: 'green' },
-  { key: '400', description: '<code>Bad Request</code>: requisição malformada ou campo inválido.', color: 'red' },
-  { key: '401', description: '<code>Unauthorized</code>: credenciais ausentes ou inválidas.', color: 'red' },
-  { key: '404', description: '<code>Not Found</code>: o recurso não existe neste workspace.', color: 'purple' },
-  { key: '429', description: '<code>Too Many Requests</code>: aguarde o número de segundos indicado em <code>Retry-After</code>.', color: 'yellow' },
-  { key: '5xx', description: 'Erro do servidor. É seguro repetir requisições idempotentes com backoff.', color: 'pink' }
+  { key: '200 / 201 / 204', description: 'Sucesso. 201 quando algo foi criado, 204 quando não há corpo.' },
+  { key: '400', description: '<code>Bad Request</code>: requisição malformada ou campo inválido.' },
+  { key: '401', description: '<code>Unauthorized</code>: credenciais ausentes ou inválidas.' },
+  { key: '404', description: '<code>Not Found</code>: o recurso não existe neste workspace.' },
+  { key: '429', description: '<code>Too Many Requests</code>: aguarde o número de segundos indicado em <code>Retry-After</code>.' },
+  { key: '5xx', description: 'Erro do servidor. É seguro repetir requisições idempotentes com backoff.' }
 ]
 </script>
 
diff --git a/docs/pt/index.md b/docs/pt/index.md
index 32911dd..dc20b59 100644
--- a/docs/pt/index.md
+++ b/docs/pt/index.md
@@ -1,7 +1,25 @@
 ---
-layout: page
-sidebar: false
-aside: false
+layout: home
+
+hero:
+  name: API Documentation Starter
+  tagline: "Um portal de documentação de API multilíngue com VitePress e Scalar. Esta demonstração documenta a Shelfline Field API, uma API fictícia de execução no varejo."
+  actions:
+    - theme: brand
+      text: "Ler o guia"
+      link: /pt/intro
+    - theme: alt
+      text: "Referência da API"
+      link: /pt/api-reference
 ---
 
-<HeroSection />
+<img
+  class="home-preview"
+  src="/preview-1080.webp"
+  srcset="/preview-1080.webp 1080w, /preview-1761.webp 1761w"
+  sizes="(min-width: 1144px) 1080px, calc(100vw - 48px)"
+  alt="O portal em um notebook: a referência da API Shelfline com a lista de endpoints, os parâmetros e um exemplo em cURL."
+  width="1761"
+  height="1075"
+  decoding="async"
+/>
diff --git a/docs/pt/rate-limits.md b/docs/pt/rate-limits.md
index 1bde3cd..b6d164b 100644
--- a/docs/pt/rate-limits.md
+++ b/docs/pt/rate-limits.md
@@ -10,9 +10,9 @@ Os limites são aplicados por workspace e por `X-Client-Name`:
 <ApiCard
   title="limites"
   :items="[
-    { key: 'Sustained', description: '60 requisições por minuto', color: 'blue' },
-    { key: 'Burst', description: 'até 20 requisições em um segundo', color: 'purple' },
-    { key: 'Over the limit', description: '<code>429 Too Many Requests</code> com o cabeçalho <code>Retry-After</code>', color: 'yellow' }
+    { key: 'Sustained', description: '60 requisições por minuto' },
+    { key: 'Burst', description: 'até 20 requisições em um segundo' },
+    { key: 'Over the limit', description: '<code>429 Too Many Requests</code> com o cabeçalho <code>Retry-After</code>' }
   ]"
 />
 
@@ -28,11 +28,11 @@ Os limites são aplicados por workspace e por `X-Client-Name`:
 
 <script setup>
 const methodsTable = [
-  { key: 'GET', description: 'Leitura', color: 'blue' },
-  { key: 'POST', description: 'Criação', color: 'green' },
-  { key: 'PUT', description: 'Substituição (v1)', color: 'purple' },
-  { key: 'PATCH', description: 'Atualiza somente os campos enviados (v3)', color: 'yellow' },
-  { key: 'DELETE', description: 'Exclusão. Nunca recebe corpo; os IDs vão no caminho ou na query string.', color: 'red' }
+  { key: 'GET', description: 'Leitura' },
+  { key: 'POST', description: 'Criação' },
+  { key: 'PUT', description: 'Substituição (v1)' },
+  { key: 'PATCH', description: 'Atualiza somente os campos enviados (v3)' },
+  { key: 'DELETE', description: 'Exclusão. Nunca recebe corpo; os IDs vão no caminho ou na query string.' }
 ]
 </script>
 
diff --git a/docs/public/preview-1080.webp b/docs/public/preview-1080.webp
new file mode 100644
index 0000000..521738b
Binary files /dev/null and b/docs/public/preview-1080.webp differ
diff --git a/docs/public/preview-1761.webp b/docs/public/preview-1761.webp
new file mode 100644
index 0000000..5300966
Binary files /dev/null and b/docs/public/preview-1761.webp differ
diff --git a/package.json b/package.json
index bfb6aba..0744aa5 100644
--- a/package.json
+++ b/package.json
@@ -42,7 +42,7 @@
   "devDependencies": {
     "@scalar/api-reference": "~1.31.18",
     "@types/node": "^24.0.3",
-    "terser": "^5.44.0",
+    "lucide-static": "^1.69.0",
     "typescript": "^5.8.3",
     "vitepress": "^1.6.3",
     "vue-tsc": "^3.3.14",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f612e66..d7048dc 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -21,9 +21,9 @@ importers:
       '@types/node':
         specifier: ^24.0.3
         version: 24.19.2
-      terser:
-        specifier: ^5.44.0
-        version: 5.51.2
+      lucide-static:
+        specifier: ^1.69.0
+        version: 1.70.0
       typescript:
         specifier: ^5.8.3
         version: 5.9.3
@@ -1681,6 +1681,9 @@ packages:
   lowlight@3.3.0:
     resolution: {integrity: sha512-0JNhgFoPvP6U6lE/UdVsSq99tn6DhjjpAj5MxG49ewd2mOBVtwWYIT8ClyABhq198aXXODMU6Ox8DrGy/CpTZQ==}
 
+  lucide-static@1.70.0:
+    resolution: {integrity: sha512-A9UgY98g94IuHQY7rl7/AFwHX7T1qNpzryim+Kw5CGhdV2STobtBY+ib/Z44ohyqXEJB88gvXFAeJ87uOOHKLw==}
+
   magic-string@0.30.21:
     resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
 
@@ -2889,6 +2892,7 @@ snapshots:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.6.0
       '@jridgewell/trace-mapping': 0.3.31
+    optional: true
 
   '@jridgewell/resolve-uri@3.1.2': {}
 
@@ -2896,6 +2900,7 @@ snapshots:
     dependencies:
       '@jridgewell/gen-mapping': 0.3.13
       '@jridgewell/trace-mapping': 0.3.31
+    optional: true
 
   '@jridgewell/sourcemap-codec@1.6.0': {}
 
@@ -2903,6 +2908,7 @@ snapshots:
     dependencies:
       '@jridgewell/resolve-uri': 3.1.2
       '@jridgewell/sourcemap-codec': 1.6.0
+    optional: true
 
   '@jridgewell/trace-mapping@0.3.9':
     dependencies:
@@ -3653,7 +3659,8 @@ snapshots:
     transitivePeerDependencies:
       - typescript
 
-  acorn@8.19.0: {}
+  acorn@8.19.0:
+    optional: true
 
   ajv-draft-04@1.0.0(ajv@8.20.0):
     optionalDependencies:
@@ -3699,7 +3706,8 @@ snapshots:
 
   blake3-wasm@2.1.5: {}
 
-  buffer-from@1.1.2: {}
+  buffer-from@1.1.2:
+    optional: true
 
   ccount@2.0.1: {}
 
@@ -3725,7 +3733,8 @@ snapshots:
 
   comma-separated-tokens@2.0.3: {}
 
-  commander@2.20.3: {}
+  commander@2.20.3:
+    optional: true
 
   content-type@1.0.5: {}
 
@@ -4031,6 +4040,8 @@ snapshots:
       devlop: 1.1.0
       highlight.js: 11.11.2
 
+  lucide-static@1.70.0: {}
+
   magic-string@0.30.21:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.6.0
@@ -4615,8 +4626,10 @@ snapshots:
     dependencies:
       buffer-from: 1.1.2
       source-map: 0.6.1
+    optional: true
 
-  source-map@0.6.1: {}
+  source-map@0.6.1:
+    optional: true
 
   space-separated-tokens@2.0.2: {}
 
@@ -4653,6 +4666,7 @@ snapshots:
       acorn: 8.19.0
       commander: 2.20.3
       source-map-support: 0.5.21
+    optional: true
 
   tinyglobby@0.2.17:
     dependencies: