diff --git a/biome.jsonc b/biome.jsonc
index ebab497..f252a5d 100644
--- a/biome.jsonc
+++ b/biome.jsonc
@@ -6,7 +6,7 @@
     "useIgnoreFile": false
   },
   "files": {
-    "includes": ["**", "!dist"],
+    "includes": ["**", "!dist", "!.astro"],
     "ignoreUnknown": false
   },
   "formatter": {
@@ -26,7 +26,8 @@
       },
       "correctness": {
         "noUnusedImports": "off"
-      }
+      },
+      "a11y": "off" // TODO: Enable a11y rules for astro
     }
   },
   "html": {
diff --git a/src/components/DocsPageSidebar.astro b/src/components/DocsPageSidebar.astro
index c46cc08..4f3c21d 100644
--- a/src/components/DocsPageSidebar.astro
+++ b/src/components/DocsPageSidebar.astro
@@ -3,13 +3,11 @@ import TableOfContents from '@astrojs/starlight/components/TableOfContents.astro
 ---
 
 {Astro.locals.starlightRoute.toc && (
-    <>
       <div class="right-sidebar-panel sl-hidden lg:sl-block">
         <div class="sl-container">
           <TableOfContents />
         </div>
       </div>
-    </>
   )}
 
 <style>
diff --git a/src/components/XahauAbout.astro b/src/components/XahauAbout.astro
index 8f01695..4fc8f52 100644
--- a/src/components/XahauAbout.astro
+++ b/src/components/XahauAbout.astro
@@ -153,9 +153,11 @@ const t = aboutTranslations[locale]
 </section>
 
 <style>
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Design tokens — mirrors XahauFeatures exactly
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Design tokens
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   .xabout {
     --ink: #0f2328;
     --dim: #2d3e44;
@@ -180,9 +182,11 @@ const t = aboutTranslations[locale]
     box-sizing: border-box;
   }
 
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Page header
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Page header
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   .xa-head {
     display: flex;
     justify-content: space-between;
@@ -222,9 +226,11 @@ const t = aboutTranslations[locale]
     letter-spacing: 0.03em;
   }
 
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Acts
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Acts
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   .xa-act {
     padding-top: 52px;
   }
@@ -258,9 +264,11 @@ const t = aboutTranslations[locale]
     background: var(--vlt2);
   }
 
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Labels
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Labels
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   .xa-lbl {
     display: inline-block;
     font-family: ui-monospace, monospace;
@@ -285,9 +293,11 @@ const t = aboutTranslations[locale]
     background: rgba(78, 24, 184, 0.1);
   }
 
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Statement sections
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Statement sections
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   .xa-statement {
     display: flex;
     align-items: center;
@@ -351,9 +361,11 @@ const t = aboutTranslations[locale]
     margin-bottom: 0;
   }
 
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Video section
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Video section
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   .xa-video-section {
     padding: 20px 28px 52px;
   }
@@ -379,9 +391,12 @@ const t = aboutTranslations[locale]
     display: block;
   }
 
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Responsive
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Responsive
+   * ══════════════════════════════════════════════════════════════════════════
+   */
+
   @media (max-width: 900px) {
     .xa-statement {
       flex-direction: column;
diff --git a/src/components/XahauEcosystem.astro b/src/components/XahauEcosystem.astro
index 198c584..ac1f9d1 100644
--- a/src/components/XahauEcosystem.astro
+++ b/src/components/XahauEcosystem.astro
@@ -64,13 +64,13 @@ const sections = ecosystemData.sections.map((section) =>
     <div class="xe-head-title">
       <h2>Ecosystem</h2>
       <p class="xe-sub">
-        {sections.map(s => s.label['en']).join(', ')}
+        {sections.map(s => s.label.en).join(', ')}
         built on or around Xahau
       </p>
     </div>
     <div class="xe-chips">
       {sections.map(s => (
-        <span class="xe-chip">{s.items.length} {s.label['en']}</span>
+        <span class="xe-chip">{s.items.length} {s.label.en}</span>
       ))}
     </div>
   </header>
diff --git a/src/components/XahauFeatures.astro b/src/components/XahauFeatures.astro
index fbc907e..b2b0cd6 100644
--- a/src/components/XahauFeatures.astro
+++ b/src/components/XahauFeatures.astro
@@ -197,9 +197,11 @@ const t = featuresTranslations[locale] ?? featuresTranslations['en']
 </section>
 
 <style>
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Design tokens
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Design tokens
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   .xfeat {
     --ink: #0f2328;
     --dim: #2d3e44;
@@ -224,9 +226,10 @@ const t = featuresTranslations[locale] ?? featuresTranslations['en']
     box-sizing: border-box;
   }
 
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Page header
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * Page header
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   .xf-head {
     display: flex;
     justify-content: space-between;
@@ -266,9 +269,11 @@ const t = featuresTranslations[locale] ?? featuresTranslations['en']
     letter-spacing: 0.03em;
   }
 
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Acts
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Acts
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   .xf-act {
     padding-top: 52px;
   }
@@ -302,9 +307,11 @@ const t = featuresTranslations[locale] ?? featuresTranslations['en']
     background: var(--vlt2);
   }
 
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Labels
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Labels
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   .xf-lbl {
     display: inline-block;
     font-family: ui-monospace, monospace;
@@ -329,9 +336,11 @@ const t = featuresTranslations[locale] ?? featuresTranslations['en']
     background: rgba(91, 30, 200, 0.1);
   }
 
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Statement sections
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Statement sections
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   .xf-statement {
     display: flex;
     align-items: center;
@@ -394,9 +403,11 @@ const t = featuresTranslations[locale] ?? featuresTranslations['en']
     margin-bottom: 0;
   }
 
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Detail sections — pairs and trios
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Detail sections — pairs and trios
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   .xf-pair,
   .xf-trio {
     display: grid;
@@ -445,9 +456,11 @@ const t = featuresTranslations[locale] ?? featuresTranslations['en']
     margin-bottom: 0;
   }
 
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Solo wide section
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Solo wide section
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   .xf-solo {
     padding: 52px 0 52px 28px;
   }
@@ -471,9 +484,11 @@ const t = featuresTranslations[locale] ?? featuresTranslations['en']
     margin: 0;
   }
 
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Closing section
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Closing section
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   .xf-closing {
     padding: 52px 0 52px 28px;
   }
@@ -497,9 +512,11 @@ const t = featuresTranslations[locale] ?? featuresTranslations['en']
     margin-bottom: 0;
   }
 
-  /* ══════════════════════════════════════════════════════════════════════════
-                     Responsive
-                  ══════════════════════════════════════════════════════════════════════════ */
+  /**
+   * ══════════════════════════════════════════════════════════════════════════
+   * Responsive
+   * ══════════════════════════════════════════════════════════════════════════
+   */
   @media (max-width: 900px) {
     .xf-statement {
       flex-direction: column;
diff --git a/src/components/XahauRoadmap.astro b/src/components/XahauRoadmap.astro
index 9d7d7e0..165ac3e 100644
--- a/src/components/XahauRoadmap.astro
+++ b/src/components/XahauRoadmap.astro
@@ -291,12 +291,13 @@ const fmtItemPeriod = (item: RoadmapItem): string => {
 
 <style>
   .xroadmap {
-    /* Xahau palette (aligned with site tokens):
-                         xahau-gray  #0f2328  — dark panel background
-                         xahau-green #5de48c  — bright accent
-                         xahau-green-dark #007b3d — darker accent
-                         xahau-secondary #fad7ae — warm secondary
-                      */
+    /**
+     *  Xahau palette (aligned with site tokens):
+     *    xahau-gray:       #0f2328 — dark panel background
+     *    xahau-green:      #5de48c — bright accent
+     *    xahau-green-dark: #007b3d — darker accent
+     *    xahau-secondary:  #fad7ae — warm secondary
+     */
     --bg: #0a1619;
     --panel: #0f2328;
     --ink: #e9edf1;
@@ -322,10 +323,13 @@ const fmtItemPeriod = (item: RoadmapItem): string => {
     box-shadow: var(--section-shadow);
   }
 
-  /* === Light theme override ==================================================
-                       Activate by rendering <XahauRoadmap theme="light" />. Rollback is a one-word
-                       prop change in src/pages/roadmap.astro (or remove the prop for the default
-                       "dark"). */
+  /**
+   * Light theme override
+   * ══════════════════════════════════════════════════════════════════════════
+   * Activate by rendering <XahauRoadmap theme="light" />. Rollback is a one-word
+   * prop change in src/pages/roadmap.astro (or remove the prop for the default
+   * "dark").
+   */
   .xroadmap.theme-light {
     /* Panel is a warm off-white so cards don't dissolve into the page bg. */
     --bg: #eef2f1;
@@ -338,8 +342,10 @@ const fmtItemPeriod = (item: RoadmapItem): string => {
     --section-bg: linear-gradient(180deg, #fbfbf9, #f3f6f4);
     --section-shadow: 0 22px 56px -28px rgba(15, 35, 40, 0.28);
   }
-  /* Feature cards: near-white surface + chunky left accent, matching rollouts.
-                       Keeps green as an accent colour instead of a pastel wash. */
+  /**
+   * Feature cards: near-white surface + chunky left accent, matching rollouts.
+   *  Keeps green as an accent colour instead of a pastel wash.
+   */
   .xroadmap.theme-light .xr-feat {
     background: #ffffff;
     border: 1px solid var(--line);
@@ -349,8 +355,10 @@ const fmtItemPeriod = (item: RoadmapItem): string => {
   .xroadmap.theme-light .xr-feat.is-span {
     background: #ffffff;
   }
-  /* Bump tags up a touch — 9px text was fragile on white. Colour stays
-                       per-card-type so status colours (live/pilot/partnership/launch) still apply. */
+  /**
+   * Bump tags up a touch — 9px text was fragile on white. Colour stays
+   * per-card-type so status colours (live/pilot/partnership/launch) still apply.
+   */
   .xroadmap.theme-light .xr-feat .k,
   .xroadmap.theme-light .xr-roll .k {
     font-size: 10px;
@@ -395,8 +403,10 @@ const fmtItemPeriod = (item: RoadmapItem): string => {
   .xroadmap.theme-light .xr-roll.status-launch {
     border-left-color: var(--teal);
   }
-  /* Deepen the status accent colours so tag text and pegs read cleanly on white.
-                       The bright dark-theme palette (teal/violet/rose/green) washes out at small sizes. */
+  /**
+   * Deepen the status accent colours so tag text and pegs read cleanly on white.
+   * The bright dark-theme palette (teal/violet/rose/green) washes out at small sizes.
+   */
   .xroadmap.theme-light .xr-roll.status-live .k {
     color: #2fa84f;
   }
@@ -986,8 +996,10 @@ const fmtItemPeriod = (item: RoadmapItem): string => {
     color: var(--ink-mute);
   }
 
-  /* Per-card quarter badge — hidden on desktop (timeline carries this info)
-                       and shown on mobile where the horizontal arrow is collapsed. */
+  /**
+   * Per-card quarter badge — hidden on desktop (timeline carries this info)
+   * and shown on mobile where the horizontal arrow is collapsed.
+   */
   .xr-q-badge {
     display: none;
   }
@@ -1023,11 +1035,13 @@ const fmtItemPeriod = (item: RoadmapItem): string => {
     }
   }
 
-  /* === Mobile (≤640px) ======================================================
-                       The horizontal timeline metaphor does not survive narrow viewports, so at
-                       phone widths we flip to a linear, stacked card list. The quarter header
-                       row, arrow and column dividers are hidden; every card instead shows its
-                       own period via the .xr-q-badge (populated at build time). */
+  /**
+   * === Mobile (≤640px) ======================================================
+   * The horizontal timeline metaphor does not survive narrow viewports, so at
+   * phone widths we flip to a linear, stacked card list. The quarter header
+   * row, arrow and column dividers are hidden; every card instead shows its
+   * own period via the .xr-q-badge (populated at build time).
+   */
   @media (max-width: 640px) {
     .xroadmap {
       padding: 20px 16px 18px;
@@ -1088,8 +1102,10 @@ const fmtItemPeriod = (item: RoadmapItem): string => {
       display: none !important;
     }
 
-    /* Lanes collapse to a simple block list with a section heading derived
-                         from the existing aria-label (so no extra markup is needed). */
+    /**
+     * Lanes collapse to a simple block list with a section heading derived
+     * from the existing aria-label (so no extra markup is needed).
+     */
     .xr-lane {
       display: block;
       padding: 0 !important;
@@ -1112,8 +1128,11 @@ const fmtItemPeriod = (item: RoadmapItem): string => {
       margin-bottom: 10px;
     }
 
-    /* Cards become full-width blocks; drop peg/open-ended/clip glyphs that
-                         only make sense against a horizontal timeline. */
+    /**
+     * Cards become full-width blocks; drop peg/open-ended/clip glyphs that
+     * only make sense against a horizontal timeline.
+     */
+    upstream/main
     .xr-feat,
     .xr-roll {
       display: block !important;
diff --git a/src/plugins/remarkGlobalReferences.ts b/src/plugins/remarkGlobalReferences.ts
index 04fe936..2c44b6d 100644
--- a/src/plugins/remarkGlobalReferences.ts
+++ b/src/plugins/remarkGlobalReferences.ts
@@ -75,6 +75,7 @@ export function remarkGlobalReferences() {
       }
 
       return globalRefs
+      // biome-ignore lint/suspicious/noExplicitAny: allowed
     } catch (error: any) {
       console.warn('Could not load global.md references:', error.message)
       globalRefs = {}
@@ -84,6 +85,7 @@ export function remarkGlobalReferences() {
 
   const NON_ROOT_LOCALES = ['es', 'ja']
 
+  // biome-ignore lint/suspicious/noExplicitAny: allowed
   return function transformer(tree: any, vfile: any) {
     const refs = loadGlobalReferences()