diff --git a/docs/source/_static/comet-ux.js b/docs/source/_static/comet-ux.js
new file mode 100644
index 0000000000..635a5867f9
--- /dev/null
+++ b/docs/source/_static/comet-ux.js
@@ -0,0 +1,254 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/*
+ * Comet docs UX enhancements layered on top of pydata_sphinx_theme:
+ *   - "Home" tab injected at the start of the top navbar (toctree can't
+ *     self-reference, so the landing page link lives here)
+ *   - Click-to-toggle expand/collapse arrows on sidebar nav groups
+ *   - In-sidebar search filter with character highlighting (replaces the
+ *     default Sphinx redirect-to-/search.html flow)
+ *   - Verbose "Comet X.Y.Z User Guide" breadcrumb labels trimmed to "X.Y.Z"
+ *   - Right-side TOC auto-hidden on pages with too few headings to navigate
+ *
+ * All behaviour is additive — pydata's existing keyboard navigation, theme
+ * switcher, search index, and toctree generation continue to work unchanged.
+ */
+
+(function () {
+  'use strict';
+
+  // ── Sidebar collapse/expand toggle buttons ─────────────────────────
+  // Pydata's toctree renders a flat <ul> tree with no toggles. We inject a
+  // real <button> for every nav item that has children so the user can
+  // expand/collapse sections independently of which page they're on.
+  function initSidebarToggle() {
+    // Match any toctree item with children, not just L1/L2 — Older Versions
+    // contains nested version groups (0.15.x, 0.14.x) at L3 that need their
+    // own expand/collapse arrows.
+    var items = document.querySelectorAll('.bd-links li[class*="toctree-l"]');
+    items.forEach(function (li) {
+      var ul = li.querySelector(':scope > ul');
+      var link = li.querySelector(':scope > a');
+      if (!ul || !link) return;
+      if (li.querySelector(':scope > .comet-toggle')) return;
+
+      // Auto-expand the section that contains the current page so the
+      // active page is always visible without an extra click.
+      if (li.classList.contains('current')) {
+        li.classList.add('comet-expanded');
+      }
+
+      var btn = document.createElement('button');
+      btn.type = 'button';
+      btn.className = 'comet-toggle';
+      btn.setAttribute('aria-label', 'Toggle section');
+      btn.setAttribute(
+        'aria-expanded',
+        li.classList.contains('comet-expanded') ? 'true' : 'false'
+      );
+      btn.addEventListener('click', function (e) {
+        e.preventDefault();
+        e.stopPropagation();
+        var expanded = li.classList.toggle('comet-expanded');
+        btn.setAttribute('aria-expanded', expanded ? 'true' : 'false');
+      });
+      link.parentNode.insertBefore(btn, link.nextSibling);
+    });
+  }
+
+  // ── In-sidebar search filter ────────────────────────────────────────
+  // Replaces Sphinx's "submit form → land on /search.html" flow with a
+  // live filter that hides non-matching nav items and highlights the
+  // matched characters in-place. Search of full document content still
+  // works via the regular Sphinx search page (pressing Enter is just
+  // suppressed here so the form doesn't navigate away).
+  function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+  function escapeHtml(s) {
+    var map = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+    return s.replace(/[&<>"']/g, function (c) { return map[c]; });
+  }
+
+  function initSidebarSearch() {
+    var input = document.querySelector(
+      '.bd-sidebar form.bd-search input[type="search"], ' +
+      '.bd-sidebar form.bd-search input.form-control'
+    );
+    var form = document.querySelector('.bd-sidebar form.bd-search');
+    var nav = document.querySelector('.bd-links');
+    if (!input || !nav) return;
+
+    if (form) {
+      form.addEventListener('submit', function (e) { e.preventDefault(); });
+    }
+
+    // Cache the original text so we can restore it (and re-highlight on
+    // every keystroke) without losing nav item labels.
+    var allLinks = Array.from(nav.querySelectorAll('a.reference'));
+    allLinks.forEach(function (a) {
+      if (!a.dataset.cometOrigText) {
+        a.dataset.cometOrigText = a.textContent;
+      }
+    });
+    var allListItems = Array.from(nav.querySelectorAll('li'));
+
+    function applyFilter(query) {
+      query = (query || '').trim();
+
+      if (!query) {
+        // Clear filter: restore original text, drop filter classes.
+        allLinks.forEach(function (a) {
+          a.innerHTML = escapeHtml(a.dataset.cometOrigText);
+        });
+        allListItems.forEach(function (li) {
+          li.classList.remove(
+            'comet-filter-hidden',
+            'comet-filter-match',
+            'comet-filter-expanded'
+          );
+        });
+        nav.classList.remove('comet-filtering');
+        return;
+      }
+
+      nav.classList.add('comet-filtering');
+      var re = new RegExp('(' + escapeRegex(query) + ')', 'ig');
+
+      allListItems.forEach(function (li) {
+        li.classList.add('comet-filter-hidden');
+        li.classList.remove('comet-filter-match', 'comet-filter-expanded');
+      });
+
+      allLinks.forEach(function (a) {
+        var orig = a.dataset.cometOrigText;
+        if (re.test(orig)) {
+          re.lastIndex = 0;
+          a.innerHTML = escapeHtml(orig).replace(
+            re,
+            '<mark class="comet-hl">$1</mark>'
+          );
+          // Reveal this item and every ancestor li so the match is reachable.
+          var li = a.closest('li');
+          while (li && nav.contains(li)) {
+            li.classList.remove('comet-filter-hidden');
+            li.classList.add('comet-filter-match', 'comet-filter-expanded');
+            li = li.parentElement.closest('li');
+          }
+        } else {
+          a.innerHTML = escapeHtml(orig);
+        }
+      });
+    }
+
+    var debounceTimer;
+    input.addEventListener('input', function () {
+      clearTimeout(debounceTimer);
+      var q = input.value;
+      debounceTimer = setTimeout(function () { applyFilter(q); }, 80);
+    });
+
+    input.addEventListener('keydown', function (e) {
+      if (e.key === 'Escape') {
+        input.value = '';
+        applyFilter('');
+      } else if (e.key === 'Enter') {
+        e.preventDefault();
+      }
+    });
+  }
+
+  // ── Inject "Home" link into the top navbar ─────────────────────────
+  // The toctree can't self-reference, so we add the Home tab via JS.
+  // It's prepended to the desktop nav AND the mobile drawer. The link
+  // is computed from the navbar logo's href so it stays correct at any
+  // page depth.
+  function initHomeNavLink() {
+    var logo = document.querySelector('a.navbar-brand');
+    var homeHref = logo ? logo.getAttribute('href') : null;
+    if (!homeHref) return;
+
+    var isHomePage = !!document.querySelector('.comet-hero');
+
+    document
+      .querySelectorAll('.bd-navbar-elements.navbar-nav')
+      .forEach(function (nav) {
+        if (nav.querySelector('.comet-home-nav-item')) return;
+
+        var li = document.createElement('li');
+        li.className = 'nav-item comet-home-nav-item';
+        if (isHomePage) li.classList.add('active', 'current');
+
+        var a = document.createElement('a');
+        a.className = 'nav-link nav-internal';
+        a.setAttribute('href', homeHref);
+        if (isHomePage) a.setAttribute('aria-current', 'page');
+        a.textContent = 'Home';
+
+        li.appendChild(a);
+        nav.insertBefore(li, nav.firstChild);
+      });
+  }
+
+  // ── Breadcrumb trim ────────────────────────────────────────────────
+  // "Comet 0.16.0-SNAPSHOT User Guide" reads as noise in a breadcrumb
+  // when the section is already shown in the top nav. Trim to "0.16.0-
+  // SNAPSHOT" and let the parent breadcrumb item carry the section name.
+  function initBreadcrumbTrim() {
+    document
+      .querySelectorAll('.bd-breadcrumbs .breadcrumb-item a')
+      .forEach(function (a) {
+        var match = a.textContent
+          .trim()
+          .match(/^Comet\s+([\d.x\-A-Za-z]+)\s+User Guide$/);
+        if (match) a.textContent = match[1];
+      });
+  }
+
+  // ── Right-side TOC visibility ──────────────────────────────────────
+  // Reference-style pages (config tables, expression lists) and short
+  // narrative pages don't benefit from an in-page TOC. Hide the rail
+  // when there are fewer than 3 anchors so it doesn't eat real estate
+  // for nothing.
+  function initSecondaryTocVisibility() {
+    var sidebar = document.querySelector('.bd-sidebar-secondary');
+    if (!sidebar) return;
+    var anchors = sidebar.querySelectorAll(
+      'nav.bd-toc a.reference, .page-toc a.reference'
+    );
+    if (anchors.length < 3) {
+      sidebar.classList.add('comet-toc-empty');
+    }
+  }
+
+  function bootstrap() {
+    initHomeNavLink();
+    initSidebarToggle();
+    initSidebarSearch();
+    initSecondaryTocVisibility();
+    initBreadcrumbTrim();
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', bootstrap);
+  } else {
+    bootstrap();
+  }
+})();
diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css
index dd5b374446..a74e870cc2 100644
--- a/docs/source/_static/theme_overrides.css
+++ b/docs/source/_static/theme_overrides.css
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -7,7 +7,7 @@
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
  *
- *     http://www.apache.org/licenses/LICENSE-2.0
+ *   http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
@@ -17,105 +17,2424 @@
  * under the License.
  */
 
+/* ─── Google Fonts ─────────────────────────────────────────────────── */
+/* Fonts are loaded via <link> in _templates/layout.html using the
+   print→all swap pattern so they don't block first paint. The system
+   font stack in --comet-font / --comet-mono is the fallback while the
+   web fonts are still loading. */
 
-/* Customizing with theme CSS variables */
-
+/* ─── Shared tokens ────────────────────────────────────────────────── */
 :root {
-  --pst-color-active-navigation: 215, 70, 51;
-  --pst-color-link-hover: 215, 70, 51;
-  --pst-color-headerlink: 215, 70, 51;
-  /* Use normal text color (like h3, ..) instead of primary color */
-  --pst-color-h1: var(--color-text-base);
-  --pst-color-h2: var(--color-text-base);
-  /* Use softer blue from bootstrap's default info color */
-  --pst-color-info: 23, 162, 184;
-  --pst-content-max-width: 100%; /* center column */
-  --pst-font-size-base: 0.9rem;
-}
-
-/* Scale down the logo in the top navbar */
+  /* Brand orange — SINGLE SOURCE OF TRUTH.
+     --comet-accent-rgb holds the raw channels so every translucent tint
+     (fills, focus rings, link underlines, glows) is composed with
+     rgba(var(--comet-accent-rgb), <alpha>) instead of re-typing the hex.
+     Change the brand color here and every orange on the site follows. */
+  --comet-accent-rgb:  232, 101, 10;
+  --comet-accent:      rgb(var(--comet-accent-rgb));   /* brand orange — buttons, backgrounds, large headings */
+  --comet-accent-lite: #f07830;                        /* hover variant */
+  --comet-accent-text: #a84808;                        /* AA-passing variant for small text on light bg (~5.9:1) — default */
+  --comet-accent-dim:       rgba(var(--comet-accent-rgb), 0.10);  /* translucent fill */
+  --comet-accent-underline: rgba(var(--comet-accent-rgb), 0.30);  /* link underline rest state */
+  --comet-accent-ring:      rgba(var(--comet-accent-rgb), 0.18);  /* focus ring */
+  --comet-accent-tint:      rgba(var(--comet-accent-rgb), 0.05);  /* faint hover wash */
+  --comet-accent-glow:      rgba(var(--comet-accent-rgb), 0.08);  /* card hover shadow */
+
+  /* Surfaces that aren't covered by PST's palette. */
+  --comet-figure-bg:   #ffffff;   /* charts/diagrams assume a white canvas */
+
+  --comet-radius:      6px;
+  --comet-font:        'Inter', system-ui, -apple-system, sans-serif;
+  --comet-mono:        'JetBrains Mono', 'Fira Code', monospace;
+  --comet-sidebar-w:   280px;
+
+  /* ── Code & terminal palette ──────────────────────────────────────
+     Code blocks and the hero terminal use a DARK background in BOTH the
+     light and dark site themes, so their syntax colors must read well on
+     near-black regardless of mode. We define them once here and share
+     them between the Pygments-rendered blocks (.highlight) and the
+     hand-built hero terminal (.comet-terminal) so the two never drift.
+     Every color below clears WCAG AA (≥ 4.5:1) on --comet-code-bg. */
+  --comet-code-bg:       #0e0e0e;   /* code block surface */
+  --comet-code-fg:       #e2e8f0;   /* default text + any untyped token */
+  --comet-code-keyword:  #c792ea;   /* keywords, storage, declarations */
+  --comet-code-string:   #c3e88d;   /* string + char literals */
+  --comet-code-comment:  #8a98a5;   /* comments — was #546e7a (too dim) */
+  --comet-code-func:     #82aaff;   /* function / builtin names */
+  --comet-code-number:   #f78c6c;   /* numeric literals */
+  --comet-code-operator: #89ddff;   /* operators, punctuation accents */
+  --comet-code-class:    #ffcb6b;   /* class / type names */
+  --comet-code-meta:     #9fb0c3;   /* console prompt, output, traceback */
+  --comet-code-prompt:   #f07830;   /* terminal "$" / "scala>" prompt */
+
+  /* Hero terminal chrome — a faintly blue near-black so the framed
+     "terminal app" reads as distinct from inline code blocks. */
+  --comet-terminal-bg:     #0d0f12;
+  --comet-terminal-bar:    #15181c;
+  --comet-terminal-border: #1f242b;
+}
+
+/* In dark mode the lighter orange has plenty of contrast on near-black,
+   so use it as the text variant instead of the darkened light-mode one. */
+html[data-theme="dark"] {
+  --comet-accent-text: #f07830;                       /* 5.1:1 on #0a0a0a */
+  --comet-surface-sunken: #0e0e0e;                    /* alternating-section bg, dark mode only */
+
+  /* In dark mode the page background is near-black (#0a0a0a), so the
+     default code surface (#0e0e0e) sits almost flush with the page and
+     the terminal "disappears." Lift it to a brighter shade here so the
+     code block reads as a raised surface — classic dark-mode elevation.
+     The token also feeds the hero terminal so the lift is consistent. */
+  --comet-code-bg:     #1c1c1c;                       /* raised code surface */
+  --comet-terminal-bg: #1c1c1c;
+}
+
+/* ─── PST overrides — LIGHT ────────────────────────────────────────── */
+html[data-theme="light"] {
+  --pst-color-primary:            #e8650a;
+  --pst-color-secondary:          #e8650a;
+  --pst-color-background:         #ffffff;
+  --pst-color-on-background:      #fafafa;
+  --pst-color-surface:            #f5f5f6;
+  --pst-color-on-surface:         #1a1a1a;
+  --pst-color-text-base:          #333333;
+  --pst-color-text-muted:         #666666;
+  --pst-color-border:             #e2e2e6;
+  --pst-color-border-muted:       #ebebee;
+  --pst-color-heading:            #111111;
+  --pst-color-inline-code:        #a84808;
+  --pst-color-inline-code-links:  #a84808;
+  --pst-color-link:               #a84808;
+  --pst-color-link-hover:         #f07830;
+  --pst-font-family-base:         var(--comet-font);
+  --pst-font-family-monospace:    var(--comet-mono);
+  --pst-font-size-base:           0.95rem;
+  --pst-content-max-width:        100%;
+}
+
+/* ─── PST overrides — DARK ─────────────────────────────────────────── */
+html[data-theme="dark"] {
+  --pst-color-primary:            #e8650a;
+  --pst-color-secondary:          #f07830;
+  --pst-color-background:         #0a0a0a;
+  --pst-color-on-background:      #0f0f0f;
+  --pst-color-surface:            #141414;
+  --pst-color-on-surface:         #f0f0f0;
+  --pst-color-text-base:          #c8c8c8;
+  --pst-color-text-muted:         #888888;
+  --pst-color-border:             #282828;
+  --pst-color-border-muted:       #1e1e1e;
+  --pst-color-heading:            #f0f0f0;
+  --pst-color-inline-code:        #f07830;
+  --pst-color-inline-code-links:  #f07830;
+  --pst-color-link:               #e8650a;
+  --pst-color-link-hover:         #f07830;
+  --pst-color-shadow:             rgba(0, 0, 0, 0.5);
+  --pst-color-table:              #c8c8c8;
+  --pst-color-table-inner-border: #282828;
+  --pst-color-table-outer-border: #282828;
+  --pst-color-table-heading-bg:   #141414;
+  --pst-font-family-base:         var(--comet-font);
+  --pst-font-family-monospace:    var(--comet-mono);
+  --pst-font-size-base:           0.95rem;
+  --pst-content-max-width:        100%;
+}
+
+/* ─── Global base ──────────────────────────────────────────────────── */
+body {
+  font-family: var(--comet-font) !important;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* ─── TOP NAVBAR ───────────────────────────────────────────────────── */
+.bd-header.navbar,
+header.bd-header {
+  min-height: 56px !important;
+  padding: 0 24px !important;
+  box-shadow: none !important;
+  border-bottom: 1px solid var(--pst-color-border) !important;
+}
+
+html[data-theme="dark"] .bd-header.navbar {
+  background: rgba(10, 10, 10, 0.96) !important;
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+}
+
+html[data-theme="light"] .bd-header.navbar {
+  background: rgba(255, 255, 255, 0.96) !important;
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+}
+
+.bd-header__inner.bd-page-width {
+  padding: 0 !important;
+  max-width: none !important;
+  display: flex !important;
+  align-items: center !important;
+  justify-content: space-between !important;
+}
+
+/* Logo */
+.navbar-brand.logo {
+  padding: 0 !important;
+  margin-right: 0 !important;
+}
+
 .bd-header .navbar-brand img.logo__image {
-  height: 40px;
-  width: auto;
-  margin-right: 0.25rem;
+  height: 38px !important;
+  width: auto !important;
+  margin-right: 0 !important;
   vertical-align: middle;
 }
 
-/* --- remove the right (secondary) sidebar entirely --- */
-.bd-sidebar-secondary { display: none !important; }
+/* ── Navbar center: nav links centered ── */
+.col-lg-3.navbar-header-items__start {
+  flex: 0 0 auto !important;
+  width: auto !important;
+}
+
+.col-lg-9.navbar-header-items {
+  flex: 1 !important;
+  display: flex !important;
+  justify-content: center !important;
+}
+
+.navbar-header-items__center {
+  display: flex !important;
+  justify-content: center !important;
+  flex: 1 !important;
+}
+
+.navbar-header-items__end {
+  display: flex !important;
+  align-items: center !important;
+  gap: 4px !important;
+  margin-left: auto !important;
+}
+
+/* Top nav links */
+.bd-navbar-elements.navbar-nav {
+  justify-content: center !important;
+  gap: 4px !important;
+}
+
+.bd-navbar-elements.navbar-nav .nav-item .nav-link {
+  font-size: 14px !important;
+  font-weight: 500 !important;
+  padding: 6px 16px !important;
+  border-radius: 0 !important;
+  color: var(--pst-color-text-muted) !important;
+  transition: color 140ms ease !important;
+  border: none !important;
+  border-bottom: 2px solid transparent !important;
+  background: transparent !important;
+  position: relative !important;
+}
+
+.bd-navbar-elements.navbar-nav .nav-item .nav-link:hover {
+  color: var(--pst-color-on-surface) !important;
+  background: transparent !important;
+}
+
+/* Active tab: orange underline — only .active (single tab), not .current (matches ancestors too) */
+.bd-navbar-elements.navbar-nav .nav-item.active > .nav-link,
+.bd-navbar-elements.navbar-nav .nav-item .nav-link[aria-current="page"] {
+  color: var(--pst-color-on-surface) !important;
+  background: transparent !important;
+  border-bottom-color: var(--comet-accent) !important;
+  font-weight: 600 !important;
+}
+
+/* ── Hide search from navbar — it lives in the sidebar now ── */
+.navbar-persistent--container,
+.navbar-item:has(.search-button-field),
+.navbar-persistent--mobile {
+  display: none !important;
+}
+
+/* Theme switcher & icon buttons */
+.pst-navbar-icon,
+.theme-switch-button {
+  padding: 5px 8px !important;
+  border-radius: 5px !important;
+  color: var(--pst-color-text-muted) !important;
+  transition: color 120ms ease, background 120ms ease !important;
+  border: none !important;
+  background: transparent !important;
+  box-shadow: none !important;
+}
+
+.pst-navbar-icon:hover,
+.theme-switch-button:hover {
+  color: var(--pst-color-on-surface) !important;
+  background: var(--pst-color-surface) !important;
+}
+
+/* ─── SIDEBAR ──────────────────────────────────────────────────────── */
+.bd-sidebar-primary.bd-sidebar {
+  width: var(--comet-sidebar-w) !important;
+  flex: 0 0 var(--comet-sidebar-w) !important;
+  border-right: 1px solid var(--pst-color-border) !important;
+  box-shadow: none !important;
+  padding-top: 0 !important;
+}
+
+html[data-theme="dark"] .bd-sidebar-primary.bd-sidebar {
+  background: #0d0d0d !important;
+}
+
+html[data-theme="light"] .bd-sidebar-primary.bd-sidebar {
+  background: #fafafa !important;
+}
+
+/* ── Sidebar search field — pill style matching screenshot ── */
+.sidebar-primary-items__start {
+  padding: 0 !important;
+}
+
+.bd-sidebar .bd-search,
+.sidebar-primary__section .bd-search {
+  padding: 14px 14px !important;
+  border-bottom: 1px solid var(--pst-color-border) !important;
+  margin: 0 !important;
+  position: relative !important;
+  display: flex !important;
+  align-items: center !important;
+}
+
+/* The pill container — make the whole form the pill */
+.bd-sidebar form.bd-search {
+  border-radius: 24px !important;
+  border: 1px solid var(--pst-color-border) !important;
+  background: var(--pst-color-surface) !important;
+  padding: 0 14px !important;
+  margin: 12px 14px !important;
+  height: 38px !important;
+  display: flex !important;
+  align-items: center !important;
+  gap: 8px !important;
+  transition: border-color 140ms ease !important;
+}
+
+html[data-theme="dark"] .bd-sidebar form.bd-search {
+  background: #1a1a1a !important;
+  border-color: #2e2e2e !important;
+}
+
+.bd-sidebar form.bd-search:focus-within {
+  border-color: var(--comet-accent) !important;
+  outline: none !important;
+  box-shadow: 0 0 0 3px var(--comet-accent-ring) !important;
+}
+
+/* Kill default browser/Bootstrap focus rings on the form + input */
+.bd-sidebar form.bd-search,
+.bd-sidebar form.bd-search:focus,
+.bd-sidebar form.bd-search *:focus,
+.bd-sidebar form.bd-search *:focus-visible {
+  outline: none !important;
+}
+
+/* Icon */
+.bd-sidebar .bd-search i.fa-magnifying-glass,
+.bd-sidebar .bd-search .fa-search {
+  color: var(--pst-color-text-muted) !important;
+  font-size: 13px !important;
+  flex-shrink: 0 !important;
+}
+
+/* Input — no border, transparent, fills space */
+.bd-sidebar .bd-search .form-control,
+.sidebar-primary__section input[type="search"] {
+  font-family: var(--comet-font) !important;
+  font-size: 13.5px !important;
+  border: none !important;
+  background: transparent !important;
+  color: var(--pst-color-on-surface) !important;
+  padding: 0 !important;
+  box-shadow: none !important;
+  flex: 1 !important;
+  min-width: 0 !important;
+  outline: none !important;
+}
+
+.bd-sidebar .bd-search .form-control:focus {
+  box-shadow: none !important;
+  outline: none !important;
+}
+
+.bd-sidebar .bd-search .form-control::placeholder {
+  color: var(--pst-color-text-muted) !important;
+}
+
+/* ⌘K shortcut badge */
+.bd-sidebar .bd-search .search-button__kbd-shortcut {
+  display: flex !important;
+  align-items: center !important;
+  gap: 2px !important;
+  flex-shrink: 0 !important;
+}
+
+.bd-sidebar .bd-search .search-button__kbd-shortcut kbd {
+  font-family: var(--comet-font) !important;
+  font-size: 11px !important;
+  padding: 1px 5px !important;
+  border-radius: 4px !important;
+  border: 1px solid var(--pst-color-border) !important;
+  color: var(--pst-color-text-muted) !important;
+  background: transparent !important;
+  line-height: 1.5 !important;
+}
+
+/* Show ⌘ on Mac; hide "Ctrl+" text visually — use CSS content swap */
+.bd-sidebar .kbd-shortcut__modifier {
+  font-size: 11px !important;
+}
+
+/* ── Sidebar nav section captions (group labels) — hidden since INDEX removed ── */
+.bd-links .caption,
+.bd-toc-item > p.caption {
+  font-size: 11px !important;
+  font-weight: 700 !important;
+  letter-spacing: 0.08em !important;
+  text-transform: uppercase !important;
+  color: var(--pst-color-text-muted) !important;
+  padding: 18px 16px 6px !important;
+  margin: 0 !important;
+}
+
+.bd-toc-item:first-child > p.caption {
+  padding-top: 12px !important;
+}
+
+/* ── Nav items ── */
+.bd-links ul {
+  list-style: none !important;
+  padding: 0 !important;
+  margin: 0 !important;
+}
+
+.bd-links li a.reference {
+  display: block !important;
+  font-size: 14px !important;
+  font-weight: 400 !important;
+  padding: 10px 16px 10px 20px !important;
+  border-left: 2px solid transparent !important;
+  color: var(--pst-color-text-muted) !important;
+  text-decoration: none !important;
+  transition: color 120ms ease, background 120ms ease, border-color 120ms ease !important;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  line-height: 1.5 !important;
+}
+
+/* Spacing between sibling nav items — adds vertical rhythm */
+.bd-links li + li {
+  margin-top: 2px !important;
+}
+
+/* Bigger gap above each top-level section */
+.bd-links .toctree-l1 {
+  margin-top: 16px !important;
+}
+
+.bd-links .toctree-l1:first-child {
+  margin-top: 8px !important;
+}
+
+/* Within a current section, give the version groups (l2 with children)
+   a hairline divider above + breathing room — makes the IA snap visually */
+.bd-links .toctree-l1.current > ul > .toctree-l2:has(> ul) {
+  margin-top: 14px !important;
+  padding-top: 14px !important;
+  border-top: 1px solid var(--pst-color-border-muted) !important;
+}
+
+.bd-links .toctree-l1.current > ul > .toctree-l2:has(> ul):first-child {
+  margin-top: 4px !important;
+  padding-top: 4px !important;
+  border-top: none !important;
+}
+
+/* Leaf l2 items (no children) just get a small gap, no rule */
+.bd-links .toctree-l1.current > ul > .toctree-l2:not(:has(> ul)) {
+  margin-top: 6px !important;
+}
+
+.bd-links .toctree-l1.current > ul > .toctree-l2:not(:has(> ul)):first-child {
+  margin-top: 4px !important;
+}
+
+/* Sub-items (the actual page links) sit closer together for a tight cluster */
+.bd-links .toctree-l3 + .toctree-l3 {
+  margin-top: 0 !important;
+}
+
+.bd-links li a.reference:hover {
+  color: var(--pst-color-on-surface) !important;
+  background: var(--pst-color-surface) !important;
+  border-left-color: var(--pst-color-border) !important;
+}
+
+/* ── Section-scoped sidebar ─────────────────────────────────────────── */
+/* Section scoping is now handled at the template level by docs-sidebar.html
+   (generate_toctree_html with startdepth=1 picks the section's own toctree
+   as the root). No CSS hiding needed — the rendered tree already contains
+   only the current section's contents. The full tree stays stable as the
+   user clicks around within a section; only the .current highlight moves. */
+
+/* L1 items (the section's direct children — e.g. 0.16.x, Dev Snapshot,
+   Older Versions inside User Guide) carry slightly stronger weight when
+   they're containers, to read as group headers. */
+.bd-links:not(.comet-filtering) .toctree-l1:has(> ul) > a.reference {
+  font-weight: 500 !important;
+  color: var(--pst-color-on-surface) !important;
+  font-size: 14px !important;
+  padding-top: 8px !important;
+  padding-bottom: 8px !important;
+}
+
+.bd-links:not(.comet-filtering) .toctree-l1:not(:has(> ul)) > a.reference {
+  font-weight: 400 !important;
+  color: var(--pst-color-text-muted) !important;
+  font-size: 14px !important;
+  padding-top: 8px !important;
+  padding-bottom: 8px !important;
+}
+
+/* ── Collapse: hide children of sections that are not explicitly expanded ── */
+/* Visibility is now controlled by the .comet-expanded class (toggled via JS button) */
+.bd-links .toctree-l1:not(.comet-expanded) > ul,
+.bd-links .toctree-l2:not(.comet-expanded) > ul,
+.bd-links .toctree-l3:not(.comet-expanded) > ul,
+.bd-links .toctree-l4:not(.comet-expanded) > ul {
+  display: none !important;
+}
+
+/* ── In-sidebar search filter ───────────────────────────────────────── */
+.bd-links.comet-filtering li.comet-filter-hidden {
+  display: none !important;
+}
+
+/* While filtering, force-expand any section that contains a match,
+   overriding the collapsed-by-default rule above */
+.bd-links.comet-filtering .toctree-l1.comet-filter-expanded > ul,
+.bd-links.comet-filtering .toctree-l2.comet-filter-expanded > ul {
+  display: block !important;
+}
+
+/* Sync the toggle arrow to the expanded state during filtering */
+.bd-links.comet-filtering li.comet-filter-expanded > .comet-toggle::before {
+  transform: rotate(90deg) !important;
+  background-color: var(--comet-accent) !important;
+}
+
+/* Highlighted matching characters */
+.bd-links mark.comet-hl {
+  background: var(--comet-accent-dim) !important;
+  color: var(--comet-accent-lite) !important;
+  padding: 0 1px !important;
+  border-radius: 2px !important;
+  font-weight: 700 !important;
+}
+
+html[data-theme="light"] .bd-links mark.comet-hl {
+  color: var(--comet-accent-text) !important;
+}
+
+/* ── Toggle button — real <button> injected via JS ── */
+.bd-links li {
+  position: relative !important;
+}
+
+.bd-links li > a.reference {
+  padding-right: 36px !important;
+}
+
+.bd-links .comet-toggle {
+  position: absolute !important;
+  right: 6px !important;
+  top: 4px !important;
+  width: 24px !important;
+  height: 24px !important;
+  border: none !important;
+  background: transparent !important;
+  cursor: pointer !important;
+  display: flex !important;
+  align-items: center !important;
+  justify-content: center !important;
+  padding: 0 !important;
+  border-radius: 4px !important;
+  z-index: 5 !important;
+  transition: background 120ms ease !important;
+}
+
+.bd-links .comet-toggle::before {
+  content: '' !important;
+  width: 14px !important;
+  height: 14px !important;
+  background-color: var(--pst-color-text-muted) !important;
+  -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='9 18 15 12 9 6'%3E%3C/polyline%3E%3C/svg%3E") !important;
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='9 18 15 12 9 6'%3E%3C/polyline%3E%3C/svg%3E") !important;
+  -webkit-mask-repeat: no-repeat !important;
+  mask-repeat: no-repeat !important;
+  -webkit-mask-size: contain !important;
+  mask-size: contain !important;
+  transition: transform 220ms ease, background-color 140ms ease !important;
+}
+
+.bd-links .comet-toggle[aria-expanded="true"]::before {
+  transform: rotate(90deg) !important;
+  background-color: var(--comet-accent) !important;
+}
+
+.bd-links .comet-toggle:hover {
+  background: var(--pst-color-surface) !important;
+}
+
+.bd-links .comet-toggle:hover::before {
+  background-color: var(--pst-color-on-surface) !important;
+}
+
+.bd-links .comet-toggle[aria-expanded="true"]:hover::before {
+  background-color: var(--comet-accent-lite) !important;
+}
+
+/* Adjust button top for l1 items (which have larger padding) */
+.bd-links .toctree-l1 > .comet-toggle {
+  top: 6px !important;
+}
+
+/* ── Top-level nav items act as section headers — bold ── */
+.bd-links .toctree-l1 > a.reference {
+  font-size: 13px !important;
+  font-weight: 700 !important;
+  color: var(--pst-color-on-surface) !important;
+  padding-top: 8px !important;
+  padding-bottom: 8px !important;
+  letter-spacing: 0.01em !important;
+}
+
+/* ── Active state: ONLY the exact current page (innermost li.current) ── */
+/* pydata_sphinx_theme sets class="current" on the <a> of BOTH the active page
+   AND its ancestor sections. :not(:has(li.current)) targets only the deepest
+   li.current — the one with no nested li.current inside it. */
+.bd-links li.current:not(:has(li.current)) > a.current.reference {
+  color: var(--comet-accent-lite) !important;
+  background: var(--comet-accent-dim) !important;
+  border-left-color: var(--comet-accent) !important;
+  font-weight: 600 !important;
+}
+
+html[data-theme="light"] .bd-links li.current:not(:has(li.current)) > a.current.reference {
+  color: var(--comet-accent-text) !important;
+}
+
+/* Ancestor li.current items (parents of the active page) — strip highlight */
+.bd-links li.current:has(li.current) > a.current.reference {
+  background: transparent !important;
+  border-left-color: transparent !important;
+  color: var(--pst-color-text-muted) !important;
+  font-weight: 400 !important;
+}
+
+/* Restore bold + on-surface color for l1 section headers that are ancestors */
+.bd-links .toctree-l1.current:has(li.current) > a.current.reference {
+  color: var(--pst-color-on-surface) !important;
+  font-weight: 700 !important;
+}
+
+/* Nested level 2 */
+.bd-links .toctree-l2 a.reference {
+  padding-left: 32px !important;
+  font-size: 13.5px !important;
+  font-weight: 400 !important;
+}
+
+/* Nested level 3 */
+.bd-links .toctree-l3 a.reference {
+  padding-left: 44px !important;
+  font-size: 13px !important;
+  font-weight: 400 !important;
+}
+
+/* Mobile sidebar nav header */
+.sidebar-header-items {
+  border-bottom: 1px solid var(--pst-color-border) !important;
+  padding: 8px 0 !important;
+}
+
+/* ─── LAYOUT GRID ──────────────────────────────────────────────────── */
+/* Secondary sidebar (right-side in-page TOC) is now enabled.
+   It auto-hides via JS on pages with fewer than 3 H2s (see layout.html). */
+.bd-sidebar-secondary {
+  border-left: 1px solid var(--pst-color-border) !important;
+  padding: 28px 24px !important;
+  width: 240px !important;
+  flex: 0 0 240px !important;
+  background: transparent !important;
+}
+
+/* Hide the right TOC when there are no anchors to navigate.
+   We use visibility: hidden (not display: none) so the empty TOC's
+   column still occupies its 240px of grid space — that keeps the
+   article's left edge in the SAME horizontal position whether the
+   TOC is rendered or not. Without this, the grid collapses on
+   TOC-less pages and the article shifts right to fill the gap. */
+.bd-sidebar-secondary.comet-toc-empty {
+  visibility: hidden !important;
+}
 
-/* Some versions still reserve the grid column for it — collapse it */
 .bd-main {
-  /* left sidebar + content only */
-  grid-template-columns: 20rem minmax(0, 1fr) !important;
+  grid-template-columns: minmax(0, 1fr) !important;
 }
 
-/* --- make the left (primary) sidebar small --- */
-.bd-sidebar-primary {
-  width: 20rem !important;
-  flex: 0 0 20rem !important;
+.bd-container__inner.bd-page-width {
+  max-width: none !important;
+  padding: 0 !important;
 }
 
-/* Optional: make its text a bit tighter */
-.bd-sidebar-primary .bd-sidebar {
-  font-size: 0.9rem;
+/* ── Right-side TOC styling ───────────────────────────────────────── */
+.bd-sidebar-secondary .page-toc,
+.bd-sidebar-secondary .toc-h2,
+.bd-sidebar-secondary .onthispage,
+.bd-sidebar-secondary .page-toc__title {
+  font-family: var(--comet-font) !important;
 }
 
-/* --- let the center content use all remaining width --- */
-.bd-content, .bd-article-container {
-  max-width: none !important;   /* remove internal cap */
+.bd-sidebar-secondary .page-toc__title,
+.bd-sidebar-secondary p.onthispage {
+  font-size: 11px !important;
+  font-weight: 700 !important;
+  text-transform: uppercase !important;
+  letter-spacing: 0.08em !important;
+  color: var(--pst-color-text-muted) !important;
+  margin: 0 0 12px 0 !important;
+  padding: 0 !important;
 }
 
+.bd-sidebar-secondary nav.bd-toc {
+  padding: 0 !important;
+}
 
-code {
-  color: rgb(215, 70, 51);
+.bd-sidebar-secondary ul.visible {
+  list-style: none !important;
+  padding-left: 0 !important;
+  margin: 0 !important;
+  border-left: 1px solid var(--pst-color-border) !important;
 }
 
-.footer {
-  text-align: center;
+.bd-sidebar-secondary nav.bd-toc ul,
+.bd-sidebar-secondary .page-toc ul {
+  list-style: none !important;
+  padding-left: 12px !important;
+  margin: 0 !important;
+}
+
+.bd-sidebar-secondary nav.bd-toc > ul,
+.bd-sidebar-secondary .page-toc > ul {
+  padding-left: 0 !important;
+  border-left: 1px solid var(--pst-color-border) !important;
 }
 
-/* Ensure the logo is properly displayed */
+.bd-sidebar-secondary nav.bd-toc a.reference,
+.bd-sidebar-secondary .page-toc a.reference {
+  display: block !important;
+  font-size: 13px !important;
+  font-weight: 400 !important;
+  line-height: 1.45 !important;
+  padding: 6px 12px !important;
+  margin-left: -1px !important;
+  color: var(--pst-color-text-muted) !important;
+  text-decoration: none !important;
+  border-left: 2px solid transparent !important;
+  transition: color 120ms ease, border-color 120ms ease !important;
+}
 
-.navbar-brand {
-  height: auto;
-  width: auto;
-  padding: 0 2em;
+.bd-sidebar-secondary nav.bd-toc a.reference:hover,
+.bd-sidebar-secondary .page-toc a.reference:hover {
+  color: var(--pst-color-on-surface) !important;
+}
+
+/* Active section in TOC — orange accent */
+.bd-sidebar-secondary nav.bd-toc a.reference.active,
+.bd-sidebar-secondary .page-toc a.reference.active,
+.bd-sidebar-secondary nav.bd-toc li.active > a.reference,
+.bd-sidebar-secondary .page-toc li.active > a.reference {
+  color: var(--comet-accent-text) !important;
+  border-left-color: var(--comet-accent) !important;
+  font-weight: 600 !important;
 }
 
-/* This is the bootstrap CSS style for "table-striped". Since the theme does
-not yet provide an easy way to configure this globally, it easier to simply
-include this snippet here than updating each table in all rst files to
-add ":class: table-striped" */
+/* Nested TOC entries (h3 under h2) — slight indent */
+.bd-sidebar-secondary ul ul a.reference {
+  padding-left: 28px !important;
+  font-size: 12.5px !important;
+}
 
-.table tbody tr:nth-of-type(odd) {
-  background-color: rgba(0, 0, 0, 0.05);
+/* Hide on narrow viewports (sidebar already takes the width) */
+@media (max-width: 1200px) {
+  .bd-sidebar-secondary { display: none !important; }
 }
 
+/* ─── CONTENT ──────────────────────────────────────────────────────── */
+.bd-content { padding: 0 !important; }
 
-/* Limit the max height of the sidebar navigation section. Because in our
-customized template, there is more content above the navigation, i.e.
-larger logo: if we don't decrease the max-height, it will overlap with
-the footer.
-Details: 8rem for search box etc*/
+.bd-article-container {
+  max-width: 860px !important;
+  padding: 44px 60px 88px !important;
+  margin: 0 !important;
+  /* Anchor to the left edge of the grid cell so the article's left
+     position stays stable whether or not the right-side TOC is rendered.
+     Without justify-self:start, pydata's grid centers the container in
+     its cell — which shifts the content right on TOC-less pages. */
+  justify-self: start !important;
+}
 
-@media (min-width:720px) {
-  @supports (position:-webkit-sticky) or (position:sticky) {
-    .bd-links {
-      max-height: calc(100vh - 8rem)
-    }
-  }
+article.bd-article {
+  font-family: var(--comet-font) !important;
 }
 
+/* Headings */
+article h1 {
+  font-size: 2.1rem !important;
+  font-weight: 700 !important;
+  letter-spacing: -0.025em !important;
+  line-height: 1.2 !important;
+  margin-top: 0 !important;
+  margin-bottom: 0.5rem !important;
+  color: var(--pst-color-heading) !important;
+}
 
-/* Fix table text wrapping in RTD theme,
- * see https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html
- */
+article h2 {
+  font-size: 1.35rem !important;
+  font-weight: 600 !important;
+  letter-spacing: -0.01em !important;
+  margin-top: 2.6rem !important;
+  margin-bottom: 0.75rem !important;
+  padding-bottom: 0 !important;
+  border-bottom: none !important;
+  color: var(--pst-color-heading) !important;
+}
+
+article h3 {
+  font-size: 1.05rem !important;
+  font-weight: 600 !important;
+  margin-top: 1.8rem !important;
+  margin-bottom: 0.5rem !important;
+  color: var(--pst-color-heading) !important;
+}
+
+article h4 {
+  font-size: 0.95rem !important;
+  font-weight: 600 !important;
+  color: var(--pst-color-text-base) !important;
+}
+
+/* Anchor links */
+a.headerlink {
+  opacity: 0 !important;
+  transition: opacity 120ms ease !important;
+  font-size: 0.75em !important;
+  margin-left: 4px !important;
+  color: var(--comet-accent-text) !important;
+}
+*:hover > a.headerlink { opacity: 0.45 !important; }
+a.headerlink:hover { opacity: 1 !important; }
+
+article p, article li {
+  color: var(--pst-color-text-base) !important;
+  line-height: 1.75 !important;
+}
+
+/* Content links */
+article a.reference.external,
+article a.reference.internal {
+  color: var(--comet-accent-text) !important;
+  text-decoration: none !important;
+  border-bottom: 1px solid var(--comet-accent-underline) !important;
+  transition: border-color 120ms ease !important;
+}
+
+article a.reference:hover {
+  border-bottom-color: var(--comet-accent) !important;
+}
+
+/* ─── INLINE CODE ──────────────────────────────────────────────────── */
+code.literal,
+p code, li code, td code, th code {
+  font-family: var(--comet-mono) !important;
+  font-size: 13px !important;
+  padding: 1px 5px !important;
+  border-radius: 4px !important;
+  border: 1px solid var(--pst-color-border) !important;
+  color: var(--pst-color-inline-code) !important;
+}
+
+html[data-theme="dark"] code.literal,
+html[data-theme="dark"] p code,
+html[data-theme="dark"] li code,
+html[data-theme="dark"] td code {
+  background: #111111 !important;
+}
+
+html[data-theme="light"] code.literal,
+html[data-theme="light"] p code,
+html[data-theme="light"] li code,
+html[data-theme="light"] td code {
+  background: #f5f5f6 !important;
+}
+
+/* ─── CODE BLOCKS ──────────────────────────────────────────────────── */
+/* Pydata wraps every code block in TWO containers — an outer
+   <div class="highlight-LANG"> and an inner <div class="highlight">. Both
+   selectors are listed here so a code block gets the rounded dark frame
+   whether only one wrapper is present (rare) or both are nested (default).
+   The dark background is set on the wrappers so any sub-pixel gap between
+   wrapper edge and the <pre> inside it reads as part of the same surface
+   (no visible light strip above/below the code). */
+div.highlight,
+div[class*="highlight-"] {
+  border-radius: var(--comet-radius) !important;
+  border: 1px solid var(--pst-color-border) !important;
+  overflow: hidden !important;
+  background: var(--comet-code-bg) !important;
+  margin: 18px 0 !important;
+  padding: 0 !important;
+}
+
+/* When the wrappers nest (the common case), the inner div.highlight must
+   sit flush inside the outer frame — no margin (otherwise its top/bottom
+   margin pushes the <pre> away from the outer border, creating the
+   thin light bands users were seeing) and no redundant border. */
+div[class*="highlight-"] > div.highlight {
+  margin: 0 !important;
+  border: none !important;
+  border-radius: 0 !important;
+  background: transparent !important;
+}
+
+div.highlight pre,
+div[class*="highlight-"] pre {
+  font-family: var(--comet-mono) !important;
+  font-size: 13.5px !important;
+  line-height: 1.7 !important;
+  padding: 20px 22px !important;
+  margin: 0 !important;
+  border: none !important;
+  border-radius: 0 !important;
+  background: var(--comet-code-bg) !important;
+  color: var(--comet-code-fg) !important;
+}
+
+/* Code blocks always use a dark background (both light and dark site
+   themes), so they need a dark-friendly syntax palette regardless of mode.
+   Pydata ships theme-scoped Pygments rules — html[data-theme="light"]
+   .highlight .TOKEN — whose specificity (0-3-1) beats our plain
+   div.highlight .TOKEN selectors, and in light mode those rules set DARK
+   text that's invisible on our dark background. We use !important here to
+   win that battle uniformly.
+
+   The base-span rule is the safety net: it paints EVERY token we don't
+   explicitly theme below (names, punctuation, console output, Rust types,
+   etc.) in the readable default foreground, so nothing can ever fall back
+   to an invisible light-theme color. The named rules then layer specific
+   hues on top of that floor. */
+div.highlight pre span,
+div[class*="highlight-"] pre span {
+  color: var(--comet-code-fg) !important;
+}
+
+/* Keywords: keyword, k.namespace, k.declaration, k.constant, k.pseudo,
+   k.reserved, k.type (Rust/Go primitive types). */
+div.highlight .k,  div.highlight .kn, div.highlight .kd,
+div.highlight .kc, div.highlight .kp, div.highlight .kr,
+div.highlight .kt  { color: var(--comet-code-keyword) !important; }
+
+/* Strings: string + all subtypes (single, double, char, doc, escape …). */
+div.highlight .s,   div.highlight .s1,  div.highlight .s2,
+div.highlight .sb,  div.highlight .sc,  div.highlight .sd,
+div.highlight .se,  div.highlight .sh,  div.highlight .si,
+div.highlight .sx,  div.highlight .sr,  div.highlight .ss,
+div.highlight .dl   { color: var(--comet-code-string) !important; }
+
+/* Comments: comment + subtypes (line, multiline, preproc, special). */
+div.highlight .c,  div.highlight .c1, div.highlight .cm,
+div.highlight .cp, div.highlight .cs, div.highlight .ch,
+div.highlight .cpf { color: var(--comet-code-comment) !important; font-style: italic; }
+
+/* Function + builtin names. */
+div.highlight .nf, div.highlight .nb,
+div.highlight .fm  { color: var(--comet-code-func) !important; }
+
+/* Numbers: int, float, hex, oct, bin, long, imaginary. */
+div.highlight .m,  div.highlight .mi, div.highlight .mf,
+div.highlight .mh, div.highlight .mo, div.highlight .mb,
+div.highlight .il  { color: var(--comet-code-number) !important; }
+
+/* Operators + punctuation. */
+div.highlight .o,  div.highlight .ow { color: var(--comet-code-operator) !important; }
+
+/* Class / type / namespace names. */
+div.highlight .nc, div.highlight .nn,
+div.highlight .no  { color: var(--comet-code-class) !important; }
+
+/* Console prompt (scala>, >>>, $) and program output/traceback. */
+div.highlight .gp, div.highlight .go,
+div.highlight .gt  { color: var(--comet-code-meta) !important; }
+
+button.copybtn {
+  background: rgba(255,255,255,0.07) !important;
+  border: 1px solid rgba(255,255,255,0.10) !important;
+  border-radius: 4px !important;
+  color: #666 !important;
+  font-family: var(--comet-font) !important;
+  font-size: 11px !important;
+  padding: 3px 8px !important;
+  transition: color 120ms, background 120ms !important;
+}
+button.copybtn:hover {
+  color: #e2e8f0 !important;
+  background: rgba(255,255,255,0.13) !important;
+}
+
+/* ─── TABLES ───────────────────────────────────────────────────────── */
+table.docutils {
+  font-size: 14px !important;
+  border-collapse: collapse !important;
+  width: 100% !important;
+  margin: 18px 0 !important;
+  border-radius: var(--comet-radius) !important;
+  overflow: hidden !important;
+  border: 1px solid var(--pst-color-border) !important;
+}
+
+table.docutils th {
+  font-size: 12px !important;
+  font-weight: 600 !important;
+  text-transform: uppercase !important;
+  letter-spacing: 0.05em !important;
+  padding: 11px 15px !important;
+  border-bottom: 1px solid var(--pst-color-border) !important;
+  color: var(--pst-color-text-muted) !important;
+  white-space: normal !important;
+}
+
+html[data-theme="dark"]  table.docutils th { background: #111111 !important; }
+html[data-theme="light"] table.docutils th { background: #f5f5f6 !important; }
+
+table.docutils td {
+  padding: 11px 15px !important;
+  border-bottom: 1px solid var(--pst-color-border) !important;
+  color: var(--pst-color-text-base) !important;
+  white-space: normal !important;
+}
+
+table.docutils tr:last-child td { border-bottom: none !important; }
+
+html[data-theme="dark"]  table.docutils tbody tr:nth-of-type(odd) { background: rgba(255,255,255,0.02) !important; }
+html[data-theme="light"] table.docutils tbody tr:nth-of-type(odd) { background: rgba(0,0,0,0.02) !important; }
+
+/* ─── ADMONITIONS ──────────────────────────────────────────────────── */
+div.admonition {
+  border-radius: var(--comet-radius) !important;
+  border: 1px solid !important;
+  padding: 14px 18px !important;
+  margin: 22px 0 !important;
+  font-size: 14px !important;
+  box-shadow: none !important;
+}
+
+div.admonition p.admonition-title {
+  font-size: 11.5px !important;
+  font-weight: 700 !important;
+  text-transform: uppercase !important;
+  letter-spacing: 0.06em !important;
+  margin-bottom: 6px !important;
+  /* Reserve room for the icon (which pydata positions absolutely at left:0
+     via a ::before pseudo-element). Without this padding the icon overlaps
+     the first letters of the title. */
+  padding: 0 0 0 26px !important;
+  background: none !important;
+  border: none !important;
+  position: relative !important;
+}
+
+div.note    { background: rgba(59,130,246,0.06) !important;  border-color: rgba(59,130,246,0.25) !important; }
+div.note    p.admonition-title { color: #3b82f6 !important; }
+div.warning { background: rgba(234,179,8,0.06) !important;   border-color: rgba(234,179,8,0.25) !important; }
+div.warning p.admonition-title { color: #ca8a04 !important; }
+div.tip     { background: rgba(34,197,94,0.06) !important;   border-color: rgba(34,197,94,0.25) !important; }
+div.tip     p.admonition-title { color: #16a34a !important; }
+div.important,
+div.caution {
+  background: rgba(var(--comet-accent-rgb),0.06) !important;
+  border-color: rgba(var(--comet-accent-rgb),0.28) !important;
+}
+div.important p.admonition-title,
+div.caution   p.admonition-title { color: var(--comet-accent-text) !important; }
+
+/* ─── PREV / NEXT NAV ──────────────────────────────────────────────── */
+footer.prev-next-footer {
+  border-top: 1px solid var(--pst-color-border) !important;
+  margin-top: 52px !important;
+  padding-top: 26px !important;
+  box-shadow: none !important;
+}
+
+.prev-next-area a {
+  border: 1px solid var(--pst-color-border) !important;
+  border-radius: var(--comet-radius) !important;
+  padding: 13px 18px !important;
+  box-shadow: none !important;
+  text-decoration: none !important;
+  transition: border-color 120ms ease !important;
+}
+
+.prev-next-area a:hover {
+  border-color: var(--comet-accent) !important;
+  background: rgba(var(--comet-accent-rgb),0.05) !important;
+}
+
+.prev-next-subtitle {
+  font-size: 11px !important;
+  text-transform: uppercase !important;
+  letter-spacing: 0.07em !important;
+  color: var(--pst-color-text-muted) !important;
+}
+
+.prev-next-title {
+  font-size: 14px !important;
+  font-weight: 600 !important;
+  color: var(--pst-color-on-surface) !important;
+}
+
+/* ─── FOOTER ───────────────────────────────────────────────────────── */
+/* Used across every doc page. Job: be quiet, surface 5-6 useful links,
+   satisfy ASF legal requirements. Not a place to repeat marketing copy. */
+
+.bd-footer-content { display: none !important; }
+
+footer.comet-footer {
+  font-family: var(--comet-font) !important;
+  border-top: 1px solid var(--pst-color-border-muted);
+  background: transparent;
+  color: var(--pst-color-text-muted);
+}
+
+.comet-footer__inner {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 80px;
+  align-items: start;
+  max-width: 1100px;
+  margin: 0 auto;
+  padding: 56px 56px 40px;
+}
+
+/* Brand: just the logo, clickable, no tagline */
+.comet-footer__brand {
+  display: inline-block;
+  text-decoration: none;
+  flex-shrink: 0;
+  opacity: 0.85;
+  transition: opacity 120ms ease;
+}
+
+.comet-footer__brand:hover { opacity: 1; }
+
+.comet-footer__logo {
+  height: 42px;
+  width: auto;
+  display: block;
+  object-fit: contain;
+  max-width: 180px;
+}
+
+/* Link columns: two of them, generous gap, monospaced rhythm */
+.comet-footer__links {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(180px, 1fr));
+  gap: 48px;
+  justify-content: end;
+  justify-self: end;
+}
+
+.comet-footer__col {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.comet-footer__col-title {
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  color: var(--pst-color-on-surface);
+  margin: 0 0 6px 0;
+}
 
-@media screen {
-    table.docutils td {
-        /* !important prevents the common CSS stylesheets from overriding
-          this as on RTD they are loaded after this stylesheet */
-        white-space: normal !important;
-    }
+.comet-footer__col a {
+  font-size: 14px;
+  color: var(--pst-color-text-muted);
+  text-decoration: none;
+  transition: color 120ms ease;
+  padding: 2px 0;
+  width: max-content;
+}
+
+.comet-footer__col a:hover { color: var(--comet-accent-text); }
+
+/* Legal bar: hairline divider, two quiet lines, plenty of breathing room */
+.comet-footer__legal {
+  max-width: 1100px;
+  margin: 0 auto;
+  padding: 22px 56px 28px;
+  border-top: 1px solid var(--pst-color-border-muted);
+}
+
+.comet-footer__legal p {
+  font-size: 12px;
+  line-height: 1.6;
+  color: var(--pst-color-text-muted);
+  margin: 0 0 6px 0;
+}
+
+.comet-footer__legal p:last-child {
+  margin-bottom: 0;
+}
+
+.comet-footer__legal a {
+  color: var(--pst-color-text-muted);
+  text-decoration: none;
+  border-bottom: 1px solid transparent;
+  transition: border-color 120ms ease, color 120ms ease;
+}
+
+.comet-footer__legal a:hover {
+  color: var(--comet-accent-text);
+  border-bottom-color: var(--comet-accent);
+}
+
+.comet-footer__trademark {
+  opacity: 0.7;
+}
+
+@media (max-width: 768px) {
+  .comet-footer__inner {
+    grid-template-columns: 1fr;
+    gap: 36px;
+    padding: 40px 24px 28px;
+  }
+  .comet-footer__links {
+    justify-self: start;
+    grid-template-columns: repeat(2, 1fr);
+    gap: 28px;
+  }
+  .comet-footer__legal { padding: 18px 24px 24px; }
+}
+
+/* ─── BACK TO TOP ──────────────────────────────────────────────────── */
+#pst-back-to-top {
+  border-radius: 20px !important;
+  font-size: 12.5px !important;
+  font-family: var(--comet-font) !important;
+  background: var(--pst-color-surface) !important;
+  border: 1px solid var(--pst-color-border) !important;
+  color: var(--pst-color-text-muted) !important;
+  box-shadow: none !important;
+  transition: color 120ms, border-color 120ms !important;
+}
+
+#pst-back-to-top:hover {
+  color: var(--pst-color-on-surface) !important;
+  border-color: var(--comet-accent) !important;
+}
+
+/* ─── BREADCRUMB ───────────────────────────────────────────────────── */
+.bd-breadcrumbs {
+  font-size: 13px !important;
+  color: var(--pst-color-text-muted) !important;
+  padding: 12px 0 0 !important;
+}
+.bd-breadcrumbs a {
+  color: var(--pst-color-text-muted) !important;
+  text-decoration: none !important;
+}
+.bd-breadcrumbs a:hover { color: var(--comet-accent-text) !important; }
+
+/* Hide the home icon — the Comet logo in the navbar already does this job */
+.bd-breadcrumbs .breadcrumb-home {
+  display: none !important;
+}
+
+/* Hide the first non-home breadcrumb item (the section index page).
+   The section is already shown as the active orange tab in the top nav,
+   so repeating it here is just noise. */
+.bd-breadcrumbs .breadcrumb-home + .breadcrumb-item {
+  display: none !important;
+}
+
+/* When there's no home icon (some pages), still hide the first item */
+.bd-breadcrumbs > .breadcrumb-item:first-child:not(.active):not(.breadcrumb-home) {
+  display: none !important;
+}
+
+/* ─── IMAGES ───────────────────────────────────────────────────────── */
+article img {
+  border-radius: var(--comet-radius) !important;
+  max-width: 100% !important;
+}
+html[data-theme="dark"] article img { opacity: 0.92 !important; }
+
+/* ─── SCROLLBAR ────────────────────────────────────────────────────── */
+::-webkit-scrollbar { width: 6px; height: 6px; }
+::-webkit-scrollbar-track { background: transparent; }
+html[data-theme="dark"]  ::-webkit-scrollbar-thumb { background: #303030; border-radius: 3px; }
+html[data-theme="light"] ::-webkit-scrollbar-thumb { background: #d0d0d0; border-radius: 3px; }
+
+/* ─── RESPONSIVE ───────────────────────────────────────────────────── */
+@media (min-width: 720px) {
+  @supports (position: -webkit-sticky) or (position: sticky) {
+    .bd-links { max-height: calc(100vh - 8rem); }
+  }
+}
+
+@media (max-width: 960px) {
+  .bd-article-container { padding: 28px 32px 64px !important; }
+}
+
+/* ─── LANDING PAGE ─────────────────────────────────────────────────── */
+/* Sphinx puts a body class of `bd-page-{pagename}` so we can target only
+   the homepage. The hero/cards/etc. take over the full canvas there;
+   every other page keeps the article-container constraints. */
+
+body:has(.comet-hero) .bd-article-container {
+  max-width: 100% !important;
+  padding: 0 !important;
+}
+
+body:has(.comet-hero) article.bd-article {
+  padding: 0 !important;
+}
+
+/* Landing page: hide chrome that doesn't belong on a marketing page.
+   The H1 stays (now lives inside the hero as the project's brand statement)
+   so we no longer hide it. */
+body:has(.comet-hero) .bd-breadcrumbs,
+body:has(.comet-hero) footer.prev-next-footer,
+body:has(.comet-hero) .prev-next-area {
+  display: none !important;
+}
+
+/* Hero H1 — the project brand statement, prominent at the top of the hero */
+body:has(.comet-hero) .comet-hero__inner h1 {
+  font-family: var(--comet-font) !important;
+  font-size: clamp(2.6rem, 5vw, 4rem) !important;
+  font-weight: 700 !important;
+  line-height: 1.05 !important;
+  letter-spacing: -0.035em !important;
+  margin: 0 0 18px 0 !important;
+  padding: 0 !important;
+  border: none !important;
+  color: var(--pst-color-heading) !important;
+  text-align: center;
+}
+
+.comet-hero__tagline {
+  font-family: var(--comet-font) !important;
+  font-size: clamp(1.25rem, 2.5vw, 1.7rem) !important;
+  font-weight: 500 !important;
+  letter-spacing: -0.01em !important;
+  line-height: 1.3 !important;
+  color: var(--comet-accent) !important;
+  margin: 0 0 22px 0 !important;
+  text-align: center;
+}
+
+body:has(.comet-hero) .bd-main {
+  grid-template-columns: minmax(0, 1fr) !important;
+}
+
+/* Each landing section is full-bleed, with its own internal max-width */
+.comet-hero,
+.comet-install,
+.comet-perf,
+.comet-cards,
+.comet-arch,
+.comet-foot-cta {
+  width: 100%;
+  display: block;
+}
+
+.comet-hero__inner,
+.comet-install__inner,
+.comet-perf__inner,
+.comet-cards__inner,
+.comet-arch__inner,
+.comet-foot-cta__inner {
+  max-width: 1100px;
+  margin: 0 auto;
+  padding: 0 32px;
+}
+
+/* ── Hero ─────────────────────────────────────────────────────────── */
+.comet-hero {
+  padding: 88px 0 72px;
+  border-bottom: 1px solid var(--pst-color-border-muted);
+  background:
+    radial-gradient(circle at 80% -20%, rgba(var(--comet-accent-rgb),0.08), transparent 55%),
+    radial-gradient(circle at 10% 110%, rgba(var(--comet-accent-rgb),0.05), transparent 50%);
+}
+
+/* Terminal-style hero variant — centered layout with terminal block centerpiece */
+.comet-hero--terminal {
+  padding: 80px 0 80px;
+  text-align: center;
+}
+
+.comet-hero--terminal .comet-hero__inner {
+  text-align: center;
+  max-width: 1080px;
+}
+
+.comet-hero--terminal .comet-hero__title {
+  max-width: none;
+  margin-left: auto !important;
+  margin-right: auto !important;
+}
+
+.comet-hero--terminal .comet-hero__lede {
+  margin-left: auto !important;
+  margin-right: auto !important;
+  max-width: 56ch;
+}
+
+.comet-hero--terminal .comet-hero__ctas {
+  justify-content: center;
+}
+
+.comet-hero__inner {
+  text-align: left;
+  max-width: 980px;
+}
+
+.comet-hero__eyebrow {
+  font-family: var(--comet-font);
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: var(--comet-accent-text);
+  margin: 0 0 18px 0;
+}
+
+.comet-hero__title {
+  font-family: var(--comet-font) !important;
+  font-size: clamp(2.4rem, 4.5vw, 3.6rem) !important;
+  font-weight: 700 !important;
+  line-height: 1.08 !important;
+  letter-spacing: -0.03em !important;
+  margin: 0 0 22px 0 !important;
+  color: var(--pst-color-heading) !important;
+  border: none !important;
+  padding: 0 !important;
+  max-width: 24ch;
+}
+
+.comet-hero__title-accent {
+  color: var(--comet-accent-text);
+}
+
+.comet-hero__lede {
+  font-size: 1.15rem !important;
+  line-height: 1.6 !important;
+  color: var(--pst-color-text-base) !important;
+  max-width: 60ch;
+  margin: 0 0 32px 0 !important;
+}
+
+.comet-hero__ctas {
+  display: flex;
+  gap: 12px;
+  flex-wrap: wrap;
+  margin: 0 0 24px 0;
+}
+
+.comet-cta {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-family: var(--comet-font) !important;
+  font-size: 15px !important;
+  font-weight: 600 !important;
+  padding: 12px 22px !important;
+  border-radius: 8px !important;
+  text-decoration: none !important;
+  border: 1px solid transparent !important;
+  transition: transform 120ms ease, background 120ms ease, border-color 120ms ease, color 120ms ease !important;
+  cursor: pointer;
+}
+
+.comet-cta--primary {
+  background: var(--comet-accent) !important;
+  color: #ffffff !important;
+}
+
+.comet-cta--primary:hover {
+  background: var(--comet-accent-lite) !important;
+  transform: translateY(-1px);
+}
+
+.comet-cta--secondary {
+  background: transparent !important;
+  color: var(--pst-color-on-surface) !important;
+  border-color: var(--pst-color-border) !important;
+}
+
+.comet-cta--secondary:hover {
+  border-color: var(--comet-accent) !important;
+  color: var(--comet-accent-text) !important;
+}
+
+.comet-hero__meta {
+  font-size: 12.5px !important;
+  color: var(--pst-color-text-muted) !important;
+  margin: 0 !important;
+}
+
+/* Small caption under the hero terminal: keeps the full tuning config
+   discoverable without crowding the drop-in demo. */
+.comet-hero__note {
+  font-size: 13px !important;
+  color: var(--pst-color-text-muted) !important;
+  margin: 0 0 22px 0 !important;
+  text-align: center;
+}
+
+.comet-hero__note a {
+  color: var(--comet-accent-text) !important;
+  text-decoration: none !important;
+  border-bottom: 1px solid var(--comet-accent-underline) !important;
+}
+
+/* ── Install block ────────────────────────────────────────────────── */
+.comet-install {
+  padding: 56px 0;
+  background: var(--pst-color-surface);
+  border-bottom: 1px solid var(--pst-color-border-muted);
+}
+
+html[data-theme="dark"] .comet-install {
+  background: var(--comet-surface-sunken);
+}
+
+.comet-install__label {
+  font-family: var(--comet-font);
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: var(--pst-color-text-muted);
+  margin: 0 0 14px 0;
+}
+
+.comet-install__cmd {
+  font-family: var(--comet-mono) !important;
+  font-size: 14px !important;
+  line-height: 1.7 !important;
+  background: var(--pst-color-background) !important;
+  color: var(--pst-color-on-surface) !important;
+  border: 1px solid var(--pst-color-border) !important;
+  border-radius: 8px !important;
+  padding: 22px 26px !important;
+  margin: 0 0 14px 0 !important;
+  overflow-x: auto !important;
+  white-space: pre !important;
+}
+
+html[data-theme="dark"] .comet-install__cmd {
+  background: #060606 !important;
+  color: #d4d4d4 !important;
+}
+
+.comet-install__hint {
+  font-size: 13.5px !important;
+  color: var(--pst-color-text-muted) !important;
+  margin: 0 !important;
+}
+
+.comet-install__hint a {
+  color: var(--comet-accent-text) !important;
+  text-decoration: none !important;
+  border-bottom: 1px solid var(--comet-accent-underline) !important;
+}
+
+.comet-install__hint a:hover {
+  border-bottom-color: var(--comet-accent) !important;
+}
+
+/* ── Performance section ──────────────────────────────────────────── */
+.comet-perf {
+  padding: 80px 0;
+  border-bottom: 1px solid var(--pst-color-border-muted);
+}
+
+.comet-perf__inner {
+  display: grid;
+  grid-template-columns: minmax(280px, 1fr) minmax(0, 1.8fr);
+  gap: 56px;
+  align-items: center;
+}
+
+.comet-perf__eyebrow {
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: var(--comet-accent-text);
+  margin: 0 0 14px 0;
+}
+
+.comet-perf__title {
+  font-family: var(--comet-font) !important;
+  font-size: 1.7rem !important;
+  font-weight: 700 !important;
+  letter-spacing: -0.02em !important;
+  line-height: 1.2 !important;
+  margin: 0 0 18px 0 !important;
+  color: var(--pst-color-heading) !important;
+  border: none !important;
+  padding: 0 !important;
+  max-width: 18ch;
+}
+
+.comet-perf__caption {
+  font-size: 1.05rem !important;
+  line-height: 1.6 !important;
+  color: var(--pst-color-on-surface) !important;
+  margin: 0 0 18px 0 !important;
+  font-weight: 400 !important;
+}
+
+.comet-perf__detail {
+  font-size: 14px !important;
+  line-height: 1.6 !important;
+  color: var(--pst-color-text-muted) !important;
+  margin: 0 !important;
+}
+
+.comet-perf__detail code {
+  font-family: var(--comet-mono) !important;
+  font-size: 12.5px !important;
+  padding: 1px 5px !important;
+  border-radius: 4px !important;
+  background: var(--pst-color-surface) !important;
+  border: 1px solid var(--pst-color-border) !important;
+  color: var(--pst-color-on-surface) !important;
+}
+
+.comet-perf__detail a {
+  color: var(--comet-accent-text) !important;
+  text-decoration: none !important;
+  border-bottom: 1px solid var(--comet-accent-underline) !important;
+}
+
+.comet-perf__chart figure {
+  margin: 0 !important;
+}
+
+.comet-perf__chart img {
+  width: 100% !important;
+  height: auto !important;
+  display: block !important;
+  border-radius: 10px !important;
+  border: 1px solid var(--pst-color-border) !important;
+  background: var(--comet-figure-bg) !important;
+  padding: 16px !important;
+}
+
+.comet-perf__chart figcaption {
+  font-size: 12.5px !important;
+  color: var(--pst-color-text-muted) !important;
+  text-align: center !important;
+  margin-top: 12px !important;
+  font-style: italic !important;
+}
+
+/* ── Cards grid ───────────────────────────────────────────────────── */
+.comet-cards {
+  padding: 80px 0;
+  background: var(--pst-color-surface);
+  border-bottom: 1px solid var(--pst-color-border-muted);
+}
+
+html[data-theme="dark"] .comet-cards {
+  background: var(--comet-surface-sunken);
+}
+
+.comet-cards__title {
+  font-size: 1.6rem !important;
+  font-weight: 700 !important;
+  letter-spacing: -0.02em !important;
+  margin: 0 0 36px 0 !important;
+  border: none !important;
+  padding: 0 !important;
+  color: var(--pst-color-heading) !important;
+}
+
+.comet-cards__grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 20px;
+}
+
+.comet-card {
+  display: flex !important;
+  flex-direction: column !important;
+  padding: 24px !important;
+  border: 1px solid var(--pst-color-border) !important;
+  border-radius: 12px !important;
+  background: var(--pst-color-background) !important;
+  text-decoration: none !important;
+  transition: border-color 140ms ease, transform 140ms ease, box-shadow 140ms ease !important;
+}
+
+.comet-card:hover {
+  border-color: var(--comet-accent) !important;
+  transform: translateY(-2px);
+  box-shadow: 0 8px 24px var(--comet-accent-glow);
+}
+
+.comet-card__icon {
+  font-size: 28px;
+  margin-bottom: 16px;
+  line-height: 1;
+}
+
+.comet-card__title {
+  font-family: var(--comet-font) !important;
+  font-size: 1.05rem !important;
+  font-weight: 600 !important;
+  letter-spacing: -0.01em !important;
+  margin: 0 0 10px 0 !important;
+  color: var(--pst-color-heading) !important;
+  border: none !important;
+  padding: 0 !important;
+}
+
+.comet-card__body {
+  font-size: 14px !important;
+  line-height: 1.55 !important;
+  color: var(--pst-color-text-muted) !important;
+  margin: 0 0 18px 0 !important;
+  flex: 1;
+}
+
+.comet-card__cta {
+  font-size: 13.5px !important;
+  font-weight: 600 !important;
+  color: var(--comet-accent-text) !important;
+  margin: 0 !important;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+/* ── Architecture section ─────────────────────────────────────────── */
+.comet-arch {
+  padding: 80px 0;
+  border-bottom: 1px solid var(--pst-color-border-muted);
+}
+
+.comet-arch__inner {
+  display: grid;
+  grid-template-columns: 1fr 1.1fr;
+  gap: 56px;
+  align-items: center;
+}
+
+.comet-arch__eyebrow {
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: var(--comet-accent-text);
+  margin: 0 0 14px 0;
+}
+
+.comet-arch__title {
+  font-size: 1.7rem !important;
+  font-weight: 700 !important;
+  letter-spacing: -0.02em !important;
+  line-height: 1.25 !important;
+  margin: 0 0 20px 0 !important;
+  color: var(--pst-color-heading) !important;
+  border: none !important;
+  padding: 0 !important;
+  max-width: 22ch;
+}
+
+.comet-arch__body {
+  font-size: 1rem !important;
+  line-height: 1.65 !important;
+  color: var(--pst-color-text-base) !important;
+  margin: 0 0 16px 0 !important;
+}
+
+.comet-arch__links {
+  font-size: 14px !important;
+  margin: 22px 0 0 0 !important;
+  color: var(--pst-color-text-muted) !important;
+  display: flex;
+  gap: 12px;
+  flex-wrap: wrap;
+  align-items: center;
+}
+
+.comet-arch__links a {
+  color: var(--comet-accent-text) !important;
+  text-decoration: none !important;
+  font-weight: 500 !important;
+  border-bottom: 1px solid transparent !important;
+  transition: border-color 120ms ease !important;
+}
+
+.comet-arch__links a:hover {
+  border-bottom-color: var(--comet-accent) !important;
+}
+
+.comet-arch__diagram img {
+  width: 100% !important;
+  height: auto !important;
+  border-radius: 8px !important;
+  border: 1px solid var(--pst-color-border) !important;
+  background: var(--comet-figure-bg);
+  padding: 12px;
+}
+
+/* ── Foot CTA ─────────────────────────────────────────────────────── */
+.comet-foot-cta {
+  padding: 88px 0;
+  text-align: center;
+  background:
+    radial-gradient(circle at 50% 0%, rgba(var(--comet-accent-rgb),0.06), transparent 60%);
+}
+
+.comet-foot-cta__title {
+  font-size: 1.9rem !important;
+  font-weight: 700 !important;
+  letter-spacing: -0.02em !important;
+  margin: 0 0 14px 0 !important;
+  border: none !important;
+  padding: 0 !important;
+  color: var(--pst-color-heading) !important;
+}
+
+.comet-foot-cta__body {
+  font-size: 1.05rem !important;
+  line-height: 1.55 !important;
+  color: var(--pst-color-text-muted) !important;
+  margin: 0 auto 28px auto !important;
+  max-width: 52ch;
+}
+
+.comet-foot-cta__inner .comet-hero__ctas {
+  justify-content: center;
+}
+
+/* ── Terminal block (hero centerpiece) ────────────────────────────── */
+.comet-terminal {
+  margin: 36px auto 36px;
+  max-width: 880px;
+  border-radius: 12px;
+  overflow: hidden;
+  text-align: left;
+  background: var(--comet-terminal-bg);
+  border: 1px solid var(--comet-terminal-border);
+  box-shadow:
+    0 24px 60px -20px rgba(0, 0, 0, 0.35),
+    0 8px 24px -8px rgba(var(--comet-accent-rgb),0.10);
+}
+
+.comet-terminal__bar {
+  display: flex;
+  align-items: center;
+  padding: 10px 14px;
+  background: var(--comet-terminal-bar);
+  border-bottom: 1px solid var(--comet-terminal-border);
+  position: relative;
+}
+
+.comet-terminal__dots {
+  display: flex;
+  gap: 7px;
+}
+
+.comet-terminal__dots i {
+  width: 11px;
+  height: 11px;
+  border-radius: 50%;
+  background: #5a5a5a;
+}
+
+.comet-terminal__dots i:nth-child(1) { background: #ff5f57; }
+.comet-terminal__dots i:nth-child(2) { background: #febc2e; }
+.comet-terminal__dots i:nth-child(3) { background: #28c840; }
+
+.comet-terminal__title {
+  position: absolute;
+  left: 50%;
+  transform: translateX(-50%);
+  font-family: var(--comet-mono);
+  font-size: 12px;
+  color: #8a8f95;
+  letter-spacing: 0.02em;
+}
+
+.comet-terminal__body {
+  font-family: var(--comet-mono) !important;
+  font-size: 13px !important;
+  line-height: 1.5 !important;
+  color: var(--comet-code-fg) !important;
+  padding: 22px 24px 26px !important;
+  margin: 0 !important;
+  background: var(--comet-terminal-bg) !important;
+  border: none !important;
+  border-radius: 0 !important;
+  overflow-x: auto !important;
+  white-space: pre !important;
+  text-align: left !important;
+}
+
+/* Lines must stay inline — the <pre> already has a literal newline after
+   each <span>, which provides the line break. Making them display:block
+   would add a SECOND break per line, double-spacing the whole block. */
+.comet-terminal__body .term-line {
+  display: inline;
+}
+
+/* A blank line between sections comes from the spacer span's trailing
+   newline in the <pre>; no explicit height needed. */
+.comet-terminal__body .term-spacer {
+  display: inline;
+}
+
+.comet-terminal__body .term-comment {
+  color: var(--comet-code-comment);
+  font-style: italic;
+}
+
+/* The terminal sits on a dark surface in BOTH site themes, so the prompt
+   uses the fixed bright orange (--comet-code-prompt), not --comet-accent-text
+   — the latter darkens to #a84808 in light mode and would lose contrast here. */
+.comet-terminal__body .term-prompt {
+  color: var(--comet-code-prompt);
+  margin-right: 6px;
+  user-select: none;
+}
+
+.comet-terminal__body .term-var {
+  color: var(--comet-code-keyword);
+}
+
+.comet-terminal__body .term-str {
+  color: var(--comet-code-string);
+}
+
+.comet-terminal__body .term-indent {
+  padding-left: 28px;
+  color: #b9bec5;
+}
+
+.comet-terminal__body .term-blink {
+  display: inline-block;
+  color: var(--comet-code-prompt);
+  animation: term-blink 1s steps(2, end) infinite;
+}
+
+@keyframes term-blink {
+  0%, 50% { opacity: 1; }
+  50.01%, 100% { opacity: 0; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .comet-terminal__body .term-blink { animation: none; }
+}
+
+/* ── Prose band (the official two-paragraph pitch) ────────────────── */
+.comet-prose {
+  padding: 64px 0;
+  border-bottom: 1px solid var(--pst-color-border-muted);
+}
+
+.comet-prose__inner {
+  max-width: 760px;
+  margin: 0 auto;
+  padding: 0 32px;
+  text-align: center;
+}
+
+.comet-prose__lede {
+  font-size: 1.15rem !important;
+  line-height: 1.65 !important;
+  color: var(--pst-color-text-base) !important;
+  margin: 0 0 18px 0 !important;
+}
+
+.comet-prose__lede:last-child {
+  margin-bottom: 0 !important;
+}
+
+.comet-prose__lede a {
+  color: var(--comet-accent-text) !important;
+  text-decoration: none !important;
+  border-bottom: 1px solid var(--comet-accent-underline) !important;
+}
+
+/* ── Stacked perf section (two charts, full-width) ────────────────── */
+.comet-perf__inner--stacked {
+  display: block;
+}
+
+.comet-perf__head {
+  text-align: center;
+  max-width: 720px;
+  margin: 0 auto 36px;
+}
+
+.comet-perf__head .comet-perf__eyebrow {
+  font-family: var(--comet-font);
+  font-size: 12px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: var(--comet-accent-text);
+  margin: 0 0 14px 0;
+}
+
+.comet-perf__head .comet-perf__caption {
+  font-size: 1.5rem !important;
+  font-weight: 600 !important;
+  letter-spacing: -0.01em !important;
+  line-height: 1.3 !important;
+  color: var(--pst-color-heading) !important;
+  margin: 0 0 14px 0 !important;
+}
+
+.comet-perf__head .comet-perf__detail {
+  font-size: 15px !important;
+  line-height: 1.6 !important;
+  color: var(--pst-color-text-muted) !important;
+  margin: 0 !important;
+}
+
+.comet-perf__figure {
+  margin: 0 0 40px 0 !important;
+  background: var(--comet-figure-bg);
+  border: 1px solid var(--pst-color-border);
+  border-radius: 12px;
+  padding: 24px;
+}
+
+.comet-perf__figure:last-child {
+  margin-bottom: 0 !important;
+}
+
+.comet-perf__figure img {
+  width: 100% !important;
+  height: auto !important;
+  display: block !important;
+  border: none !important;
+  background: transparent !important;
+  border-radius: 0 !important;
+  padding: 0 !important;
+  margin: 0 auto !important;
+}
+
+.comet-perf__figure figcaption {
+  font-size: 13px !important;
+  color: var(--pst-color-text-muted) !important;
+  text-align: center !important;
+  margin-top: 14px !important;
+  font-style: italic !important;
+}
+
+/* ── Feature bands (alternating colors) ───────────────────────────── */
+.comet-feature {
+  padding: 80px 0;
+  border-bottom: 1px solid var(--pst-color-border-muted);
+}
+
+.comet-feature--alt {
+  background: var(--pst-color-surface);
+}
+
+html[data-theme="dark"] .comet-feature--alt {
+  background: var(--comet-surface-sunken);
+}
+
+.comet-feature__inner {
+  max-width: 880px;
+  margin: 0 auto;
+  padding: 0 32px;
+}
+
+.comet-feature__copy {
+  text-align: left;
+}
+
+.comet-feature__eyebrow {
+  font-size: 12px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: var(--comet-accent-text);
+  margin: 0 0 14px 0;
+}
+
+.comet-feature__title {
+  font-family: var(--comet-font) !important;
+  font-size: 1.7rem !important;
+  font-weight: 700 !important;
+  letter-spacing: -0.02em !important;
+  line-height: 1.25 !important;
+  margin: 0 0 18px 0 !important;
+  color: var(--pst-color-heading) !important;
+  border: none !important;
+  padding: 0 !important;
+  max-width: 28ch;
+}
+
+.comet-feature__body {
+  font-size: 1.02rem !important;
+  line-height: 1.65 !important;
+  color: var(--pst-color-text-base) !important;
+  margin: 0 0 14px 0 !important;
+}
+
+.comet-feature__body:last-child {
+  margin-bottom: 0 !important;
+}
+
+.comet-feature__links {
+  font-size: 14px !important;
+  margin: 20px 0 0 0 !important;
+}
+
+.comet-feature__links a {
+  color: var(--comet-accent-text) !important;
+  text-decoration: none !important;
+  font-weight: 600 !important;
+  border-bottom: 1px solid transparent !important;
+  transition: border-color 120ms ease !important;
+}
+
+.comet-feature__links a:hover {
+  border-bottom-color: var(--comet-accent) !important;
+}
+
+.comet-feature__figure {
+  margin: 28px 0 0 0 !important;
+  background: var(--comet-figure-bg);
+  border: 1px solid var(--pst-color-border);
+  border-radius: 12px;
+  padding: 24px;
+  text-align: center;
+}
+
+.comet-feature__figure img {
+  max-width: 100% !important;
+  height: auto !important;
+  display: block !important;
+  margin: 0 auto !important;
+  border: none !important;
+  background: transparent !important;
+  padding: 0 !important;
+  border-radius: 0 !important;
+}
+
+.comet-feature__figure figcaption {
+  font-size: 13px !important;
+  color: var(--pst-color-text-muted) !important;
+  margin-top: 14px !important;
+  font-style: italic !important;
+}
+
+/* ── Stacked architecture (two diagrams full-width) ───────────────── */
+.comet-arch__inner--stacked {
+  display: block;
+}
+
+.comet-arch__head {
+  text-align: center;
+  max-width: 720px;
+  margin: 0 auto 28px;
+}
+
+.comet-arch__head:not(:first-child) {
+  margin-top: 56px;
+}
+
+.comet-arch__head .comet-arch__eyebrow {
+  font-size: 12px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: var(--comet-accent-text);
+  margin: 0 0 14px 0;
+}
+
+.comet-arch__head .comet-arch__body {
+  font-size: 1.05rem !important;
+  line-height: 1.6 !important;
+  color: var(--pst-color-text-base) !important;
+  margin: 0 !important;
+}
+
+.comet-arch__figure {
+  margin: 0 !important;
+  background: var(--comet-figure-bg);
+  border: 1px solid var(--pst-color-border);
+  border-radius: 12px;
+  padding: 24px;
+  text-align: center;
+}
+
+.comet-arch__figure img {
+  max-width: 100% !important;
+  height: auto !important;
+  display: block !important;
+  margin: 0 auto !important;
+  border: none !important;
+  background: transparent !important;
+  padding: 0 !important;
+  border-radius: 0 !important;
+}
+
+.comet-arch__figure figcaption {
+  font-size: 13px !important;
+  color: var(--pst-color-text-muted) !important;
+  margin-top: 14px !important;
+  font-style: italic !important;
+}
+
+/* ── Community 3-column band ──────────────────────────────────────── */
+.comet-community {
+  padding: 80px 0;
+  border-bottom: 1px solid var(--pst-color-border-muted);
+  background: var(--pst-color-surface);
+}
+
+html[data-theme="dark"] .comet-community {
+  background: var(--comet-surface-sunken);
+}
+
+.comet-community__inner {
+  max-width: 1100px;
+  margin: 0 auto;
+  padding: 0 32px;
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 40px;
+}
+
+.comet-community__inner--two {
+  max-width: 880px;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 56px;
+}
+
+.comet-community__col {
+  text-align: left;
+}
+
+.comet-community__eyebrow {
+  font-size: 12px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: var(--comet-accent-text);
+  margin: 0 0 14px 0;
+}
+
+.comet-community__body {
+  font-size: 15px !important;
+  line-height: 1.65 !important;
+  color: var(--pst-color-text-base) !important;
+  margin: 0 !important;
+}
+
+.comet-community__body a {
+  color: var(--comet-accent-text) !important;
+  text-decoration: none !important;
+  border-bottom: 1px solid var(--comet-accent-underline) !important;
+}
+
+/* ── Responsive collapses ─────────────────────────────────────────── */
+@media (max-width: 960px) {
+  .comet-hero,
+  .comet-hero--terminal { padding: 56px 0 40px; }
+  .comet-perf__inner,
+  .comet-arch__inner { grid-template-columns: 1fr; gap: 32px; }
+  .comet-cards__grid,
+  .comet-community__inner { grid-template-columns: 1fr; gap: 32px; }
+  .comet-install,
+  .comet-perf,
+  .comet-cards,
+  .comet-arch,
+  .comet-feature,
+  .comet-prose,
+  .comet-community,
+  .comet-foot-cta { padding: 56px 0; }
+  .comet-hero__inner,
+  .comet-install__inner,
+  .comet-perf__inner,
+  .comet-cards__inner,
+  .comet-arch__inner,
+  .comet-feature__inner,
+  .comet-prose__inner,
+  .comet-community__inner,
+  .comet-foot-cta__inner { padding: 0 22px; }
+  .comet-terminal { margin: 24px auto; }
+  .comet-terminal__body { font-size: 11.5px !important; padding: 16px 16px 18px !important; }
+  .comet-terminal__title { display: none; }
+}
+
+/* ─── MOBILE NAVBAR (≤ 991px) ──────────────────────────────────────── */
+/* PST uses its own sidebar-toggle (hamburger) button for mobile nav.
+   Our `display: flex !important` on .col-lg-9 overrides Bootstrap's
+   responsive hiding, so 5 nav links overflow horizontally on phones.
+   Fix: hide the entire center+end column on small screens and let the
+   primary-toggle button open the sidebar. */
+@media (max-width: 991.98px) {
+  .col-lg-9.navbar-header-items {
+    display: none !important;
+  }
+  .bd-header.navbar,
+  header.bd-header {
+    padding: 0 12px !important;
+  }
+}
+
+/* ─── TABLET (≤ 768px) ─────────────────────────────────────────────── */
+@media (max-width: 768px) {
+  /* Article: tighter side padding */
+  .bd-article-container {
+    padding: 24px 20px 56px !important;
+  }
+
+  /* Tables: wrap in a scrollable container */
+  .bd-article-container table.docutils {
+    display: block;
+    overflow-x: auto;
+    -webkit-overflow-scrolling: touch;
+    max-width: 100%;
+    width: max-content;
+    min-width: 100%;
+  }
+
+  /* Prevent wide pre/code blocks from breaking layout */
+  .bd-article-container div.highlight pre,
+  .bd-article-container div[class*="highlight-"] pre {
+    overflow-x: auto;
+  }
+
+  /* Community 2-col: collapse to single column */
+  .comet-community__inner--two {
+    grid-template-columns: 1fr !important;
+    gap: 32px !important;
+  }
+
+  /* Perf figure: smaller padding */
+  .comet-perf__figure,
+  .comet-arch__figure,
+  .comet-feature__figure {
+    padding: 16px !important;
+  }
+}
+
+/* ─── SMALL MOBILE (≤ 480px) ───────────────────────────────────────── */
+@media (max-width: 480px) {
+  /* Article: minimal side padding */
+  .bd-article-container {
+    padding: 18px 14px 44px !important;
+  }
+
+  /* Hero: compact on very small screens */
+  .comet-hero,
+  .comet-hero--terminal {
+    padding: 36px 0 24px;
+  }
+
+  /* Hero CTAs: stack vertically, full-width */
+  .comet-hero__ctas {
+    flex-direction: column;
+    align-items: stretch;
+  }
+  .comet-cta {
+    width: 100%;
+    justify-content: center;
+    text-align: center;
+  }
+
+  /* Terminal: smallest readable size */
+  .comet-terminal__body {
+    font-size: 10px !important;
+    padding: 12px 10px 14px !important;
+  }
+
+  /* Install cmd: smaller font, allow wrapping for long lines */
+  .comet-install__cmd {
+    font-size: 12px !important;
+    padding: 14px 14px !important;
+    white-space: pre-wrap !important;
+    word-break: break-all !important;
+  }
+
+  /* All inner section wrappers: minimal padding */
+  .comet-hero__inner,
+  .comet-install__inner,
+  .comet-perf__inner,
+  .comet-cards__inner,
+  .comet-arch__inner,
+  .comet-feature__inner,
+  .comet-prose__inner,
+  .comet-community__inner,
+  .comet-foot-cta__inner {
+    padding: 0 14px;
+  }
+
+  /* Section vertical spacing: very compact */
+  .comet-install,
+  .comet-perf,
+  .comet-cards,
+  .comet-arch,
+  .comet-feature,
+  .comet-prose,
+  .comet-community,
+  .comet-foot-cta {
+    padding: 36px 0;
+  }
+
+  /* Footer: single column, tighter */
+  .comet-footer__links {
+    grid-template-columns: 1fr !important;
+    gap: 16px !important;
+  }
+  .comet-footer__inner {
+    padding: 32px 16px 24px !important;
+  }
+  .comet-footer__legal {
+    padding: 14px 16px 20px !important;
+  }
+
+  /* Foot CTA: tighter padding */
+  .comet-foot-cta {
+    padding: 56px 0;
+  }
 }
diff --git a/docs/source/_templates/docs-sidebar.html b/docs/source/_templates/docs-sidebar.html
index a20c715d20..b865974ddf 100644
--- a/docs/source/_templates/docs-sidebar.html
+++ b/docs/source/_templates/docs-sidebar.html
@@ -17,13 +17,23 @@
 under the License.
 -->
 
-{# Start the sidebar from the deepest captioned section the page lives under:
-   - user-guide/latest/* lives under user-guide/index.md → user-guide/latest/index.rst, so start at depth 2
-   - contributor-guide/* lives under contributor-guide/index.md, so start at depth 1
-   - root and orphan pages (search, genindex) fall back to the global toctree (depth 0). #}
-{% if pagename.startswith("user-guide/latest/") and not suppress_sidebar_toctree(startdepth=2, includehidden=True) %}
-  {% set sidebar_startdepth = 2 %}
-{% elif not suppress_sidebar_toctree(startdepth=1, includehidden=True) %}
+{# Use startdepth=1 consistently across ALL pages so the sidebar stays
+   stable as users navigate within a section. Only the .current highlight
+   moves; the tree structure (e.g. 0.16.x / Dev Snapshot / Older Versions
+   inside User Guide) does not change between sibling pages.
+
+   We deliberately drop upstream's startdepth=2 exception for
+   /user-guide/latest/*. That exception swapped the visible toctree to
+   the snapshot's own captioned subgroups (Getting Started / What Comet
+   Supports / Compatibility), which made clicking a Dev Snapshot child
+   page reload the sidebar with a completely different tree. Reviewers
+   and users found that disorienting. With startdepth=1 fixed, the same
+   three groups stay visible everywhere in User Guide, the active page
+   is highlighted in orange, and parent groups expand inline.
+
+   Orphan pages (no parent section toctree at depth 1) fall back to the
+   global toctree at depth 0. #}
+{% if not suppress_sidebar_toctree(startdepth=1, includehidden=True) %}
   {% set sidebar_startdepth = 1 %}
 {% else %}
   {% set sidebar_startdepth = 0 %}
@@ -33,4 +43,3 @@
     {{ generate_toctree_html("sidebar", startdepth=sidebar_startdepth, maxdepth=4, collapse=False, includehidden=True, titles_only=True) }}
   </div>
 </nav>
-
diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html
index f90a9e0b58..bcbba05eba 100644
--- a/docs/source/_templates/layout.html
+++ b/docs/source/_templates/layout.html
@@ -17,25 +17,76 @@
 under the License.
 -->
 
+{# Comet docs layout — extends pydata_sphinx_theme to add a project footer.
+   All client-side enhancements live in _static/comet-ux.js, registered via
+   html_js_files in conf.py. #}
+
 {% extends "pydata_sphinx_theme/layout.html" %}
 
-<!--
-    Custom footer
--->
+{# Font loading: use the print→all swap pattern so Google Fonts doesn't
+   block first paint. preconnect warms up the connection; the stylesheet
+   is requested non-blocking and then promoted to apply once loaded. The
+   <noscript> fallback covers JS-disabled browsers. #}
+{% block extrahead %}
+{{ super() }}
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="preload" as="style"
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap">
+<link rel="stylesheet"
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap"
+      media="print" onload="this.media='all'">
+<noscript>
+  <link rel="stylesheet"
+        href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap">
+</noscript>
+{% endblock %}
+
 {% block footer %}
-<!-- Based on pydata_sphinx_theme/footer.html -->
-<footer class="footer mt-5 mt-md-0">
-  <div class="container">
-    {% for footer_item in theme_footer_items %}
-    <div class="footer-item">
-      {% include footer_item %}
-    </div>
-    {% endfor %}
-    <div class="footer-item">
-      <p>Apache DataFusion, Apache DataFusion Comet, Apache, the Apache feather logo, and the Apache DataFusion project logo</p>
-      <p>are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries.</p>
-    </div>
+<footer class="comet-footer" role="contentinfo">
+  <div class="comet-footer__inner">
+
+    <!-- Brand: logo only — no duplicated tagline -->
+    <a class="comet-footer__brand" href="{{ pathto('index') }}" aria-label="Apache DataFusion Comet — home">
+      <img src="{{ pathto('_static/images/DataFusionComet-Logo-Light.png', 1) }}"
+           class="comet-footer__logo only-light"
+           width="3256" height="836"
+           loading="lazy" decoding="async"
+           alt="" />
+      <img src="{{ pathto('_static/images/DataFusionComet-Logo-Dark.png', 1) }}"
+           class="comet-footer__logo only-dark pst-js-only"
+           width="3256" height="836"
+           loading="lazy" decoding="async"
+           alt="" />
+    </a>
+
+    <!-- Two compact link columns: documentation + community -->
+    <nav class="comet-footer__links" aria-label="Footer navigation">
+      <div class="comet-footer__col">
+        <div class="comet-footer__col-title">Documentation</div>
+        <a href="{{ pathto('user-guide/index') }}">User Guide</a>
+        <a href="{{ pathto('contributor-guide/index') }}">Contributor Guide</a>
+        <a href="{{ pathto('changelog/index') }}">Changelog</a>
+      </div>
+
+      <div class="comet-footer__col">
+        <div class="comet-footer__col-title">Community</div>
+        <a href="https://github.com/apache/datafusion-comet" target="_blank" rel="noopener">GitHub</a>
+        <a href="https://datafusion.apache.org/contributor-guide/communication.html" target="_blank" rel="noopener">Slack &amp; Discord</a>
+        <a href="https://apache.org" target="_blank" rel="noopener">Apache Software Foundation</a>
+      </div>
+    </nav>
   </div>
-</footer>
 
+  <!-- Legal: license, copyright, trademark — single quiet line -->
+  <div class="comet-footer__legal">
+    <p>
+      &copy; 2023&ndash;2026 Apache Software Foundation &nbsp;·&nbsp;
+      Licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0" target="_blank" rel="noopener">Apache License 2.0</a>
+    </p>
+    <p class="comet-footer__trademark">
+      Apache DataFusion, Apache DataFusion Comet, the Apache feather logo, and the Apache DataFusion project logo are trademarks of The Apache Software Foundation.
+    </p>
+  </div>
+</footer>
 {% endblock %}
diff --git a/docs/source/about/index.md b/docs/source/about/index.md
new file mode 100644
index 0000000000..2065047cf4
--- /dev/null
+++ b/docs/source/about/index.md
@@ -0,0 +1,37 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# About
+
+Background on the project: how Comet compares to similar accelerators, how releases
+are versioned, and links to the Apache Software Foundation resources behind it.
+
+- [Comparison with Gluten](gluten_comparison.md) — how Comet differs from other Spark accelerators
+- [Versioning Policy](versioning_policy.md) — what our version numbers mean and our release cadence
+- [ASF Links](../asf/index.md) — licensing, donations, security reporting, and the code of conduct
+
+```{toctree}
+:maxdepth: 1
+:caption: About
+:hidden:
+
+Comparison with Gluten <gluten_comparison>
+Versioning Policy <versioning_policy>
+ASF Links <../asf/index>
+```
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 311e6fd754..820a6f4a5e 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -94,7 +94,7 @@
     },
 
     "use_edit_page_button": False,
-    "secondary_sidebar_items": [],
+    "secondary_sidebar_items": ["page-toc"],
     "collapse_navigation": True,
     "navbar_start": ["navbar-logo"],
     "navbar_center": ["navbar-nav"],
@@ -128,10 +128,13 @@
 
 html_js_files = [
     ("https://buttons.github.io/buttons.js", {'async': 'true', 'defer': 'true'}),
+    "comet-ux.js",
 ]
 
 html_sidebars = {
-    "**": ["docs-sidebar.html"],
+    "**": ["search-field.html", "docs-sidebar.html"],
+    # Landing page is a full-width marketing page — no left rail.
+    "index": [],
 }
 
 # tell myst_parser to auto-generate anchor links for headers h1, h2, h3, h4
@@ -142,7 +145,6 @@
 
 redirects = {
     "overview.html": "index.html",
-    "about/index.html": "../index.html",
     "gluten_comparison.html": "about/gluten_comparison.html",
     "user-guide/overview.html": "../index.html",
     "user-guide/gluten_comparison.html": "../about/gluten_comparison.html",
@@ -158,4 +160,41 @@
     "user-guide/operators.html": "latest/operators.html",
     "user-guide/source.html": "latest/source.html",
     "user-guide/tuning.html": "latest/tuning.html",
-}
\ No newline at end of file
+}
+
+
+# -- $COMET_VERSION substitution -------------------------------------------
+# build.sh runs `replace_in_files` after copying source/ → temp/ to swap the
+# $COMET_VERSION placeholder with the real version from pom.xml. When Sphinx
+# is invoked directly against source/ (local dev, IDE preview, etc.), that
+# substitution never runs and the literal "$COMET_VERSION" leaks into page
+# titles, breadcrumbs, and the toctree caption. The hook below mirrors the
+# build.sh substitution at Sphinx read-time so local builds match prod.
+
+def _read_comet_version():
+    import os
+    import xml.etree.ElementTree as ET
+    pom_path = os.path.normpath(os.path.join(os.path.dirname(__file__), "..", "..", "pom.xml"))
+    try:
+        tree = ET.parse(pom_path)
+        root = tree.getroot()
+        ns = {"m": "http://maven.apache.org/POM/4.0.0"}
+        ver = root.find("m:version", ns)
+        if ver is not None and ver.text:
+            return ver.text.strip()
+    except Exception:
+        pass
+    return "latest"
+
+
+_comet_version = _read_comet_version()
+
+
+def _substitute_version(app, docname, source):
+    if "$COMET_VERSION" in source[0]:
+        source[0] = source[0].replace("$COMET_VERSION", _comet_version)
+
+
+def setup(app):
+    app.connect("source-read", _substitute_version)
+    return {"version": _comet_version, "parallel_read_safe": True, "parallel_write_safe": True}
\ No newline at end of file
diff --git a/docs/source/index.md b/docs/source/index.md
index d1ea261824..a6730dc940 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -17,88 +17,117 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-# Comet Accelerator for Apache Spark and Apache Iceberg
-
-<!-- Code from https://buttons.github.io/ -->
-<p>
-  <!-- Place this tag where you want the button to render. -->
-  <a class="github-button" href="https://github.com/apache/datafusion-comet" data-size="large" data-show-count="true" aria-label="Star apache/datafusion-comet on GitHub">Star</a>
-  <!-- Place this tag where you want the button to render. -->
-   <a class="github-button" href="https://github.com/apache/datafusion-comet/fork" data-size="large" data-show-count="true" aria-label="Fork apache/datafusion-comet on GitHub">Fork</a>
-</p>
-
-Apache DataFusion Comet is a high-performance accelerator for Apache Spark, built on top of the powerful
-[Apache DataFusion] query engine. Comet is designed to significantly enhance the
-performance of Apache Spark workloads while leveraging commodity hardware and seamlessly integrating with the
-Spark ecosystem without requiring any code changes.
-
-Comet also accelerates Apache Iceberg, when performing Parquet scans from Spark.
-
-[Apache DataFusion]: https://datafusion.apache.org
-
-## Run Spark Queries at DataFusion Speeds
-
-Comet delivers a performance speedup for many queries, enabling faster data processing and shorter time-to-insights.
-
-The following charts demonstrate Comet accelerating TPC-DS @ 1 TB. See the [Comet Benchmarking Guide](https://datafusion.apache.org/comet/contributor-guide/benchmarking.html)
-for details.
-
-![](_static/images/benchmark-results/0.16.0/tpcds_allqueries.png)
-
-Here is a breakdown showing relative speedup for each TPC-DS query.
-
-![](_static/images/benchmark-results/0.16.0/tpcds_queries_speedup_rel.png)
-
-## Use Commodity Hardware
-
-Comet leverages commodity hardware, eliminating the need for costly hardware upgrades or
-specialized hardware accelerators, such as GPUs or FPGA. By maximizing the utilization of commodity hardware, Comet
-ensures cost-effectiveness and scalability for your Spark deployments.
+<section class="comet-hero comet-hero--terminal">
+<div class="comet-hero__inner">
 
-## Spark Compatibility
+# Apache DataFusion Comet
 
-Comet aims for 100% compatibility with all supported versions of Apache Spark, allowing you to integrate Comet into
-your existing Spark deployments and workflows seamlessly. With no code changes required, you can immediately harness
-the benefits of Comet's acceleration capabilities without disrupting your Spark applications.
-
-The project strives to keep feature parity with Apache Spark, that is, users should expect the same behavior (w.r.t
-features, configurations, query results, etc) with Comet turned on or turned off in their Spark jobs. In addition,
-the Comet extension automatically detects unsupported features and falls back to the Spark engine.
-
-## Tight Integration with Apache DataFusion
-
-Comet tightly integrates with the core Apache DataFusion project, leveraging its powerful execution engine. With
-seamless interoperability between Comet and DataFusion, you can achieve optimal performance and efficiency in your
-Spark workloads.
-
-## Architecture
-
-The following diagram provides an overview of Comet's architecture.
-
-![Comet Overview](_static/images/comet-overview.png)
-
-The following diagram shows how Comet integrates with Apache Spark.
-
-![Comet System Diagram](_static/images/comet-system-diagram.png)
-
-## Active Community
+<p class="comet-hero__tagline">A high-performance accelerator for Apache Spark</p>
+<p class="comet-hero__lede">
+Runs your existing Spark queries on the Apache DataFusion native engine, no code changes required. Also accelerates Parquet scans for Apache Iceberg.
+</p>
 
-Comet boasts a vibrant and active community of developers, contributors, and users dedicated to advancing the
-capabilities of Apache DataFusion and accelerating the performance of Apache Spark.
+<div class="comet-terminal" aria-label="Sample terminal session showing how to enable Comet">
+<div class="comet-terminal__bar">
+<span class="comet-terminal__dots" aria-hidden="true"><i></i><i></i><i></i></span>
+<span class="comet-terminal__title">spark-shell &mdash; comet enabled</span>
+</div>
+<pre class="comet-terminal__body"><span class="term-line term-comment"># Add the Comet jar to your existing Spark job — no code changes</span>
+<span class="term-line"><span class="term-prompt">$</span> $SPARK_HOME/bin/spark-shell \</span>
+<span class="term-line term-indent">--jars comet-spark-spark4.1_2.13-0.16.0.jar \</span>
+<span class="term-line term-indent">--conf spark.plugins=org.apache.spark.CometPlugin \</span>
+<span class="term-line term-indent">--conf spark.shuffle.manager=org.apache.spark.sql.comet.execution.shuffle.CometShuffleManager</span>
+<span class="term-line term-spacer"></span>
+<span class="term-line term-comment">// Your existing queries now run on the DataFusion native engine</span>
+<span class="term-line"><span class="term-prompt">scala&gt;</span> spark.sql(<span class="term-str">"SELECT category, COUNT(*) FROM events GROUP BY category"</span>).show()</span>
+<span class="term-line term-cursor"><span class="term-prompt">scala&gt;</span> <span class="term-blink">▍</span></span></pre>
+</div>
+
+<p class="comet-hero__note">Off-heap memory and classpath tuning flags are covered in the <a href="user-guide/latest/installation.html">installation guide</a>.</p>
+
+<div class="comet-hero__ctas">
+<a class="comet-cta comet-cta--primary" href="user-guide/latest/installation.html">Install Comet <span aria-hidden="true">→</span></a>
+<a class="comet-cta comet-cta--secondary" href="https://github.com/apache/datafusion-comet" target="_blank" rel="noopener">View on GitHub</a>
+</div>
+<p class="comet-hero__meta">Apache 2.0 &nbsp;·&nbsp; Apache Software Foundation project &nbsp;·&nbsp; Runs on commodity hardware</p>
+</div>
+</section>
+
+<section class="comet-perf">
+<div class="comet-perf__inner comet-perf__inner--stacked">
+<div class="comet-perf__head">
+<p class="comet-perf__eyebrow">Run Spark Queries at DataFusion Speeds</p>
+<p class="comet-perf__caption">Comet delivers a performance speedup for many queries, enabling faster data processing and shorter time-to-insights.</p>
+<p class="comet-perf__detail">The chart below shows Comet accelerating TPC-DS @ 1 TB. See the <a href="https://datafusion.apache.org/comet/contributor-guide/benchmarking.html">Comet Benchmarking Guide</a> for the full per-query breakdown and reproduction methodology.</p>
+</div>
+<figure class="comet-perf__figure">
+<img src="_static/images/benchmark-results/0.16.0/tpcds_allqueries.png"
+     width="1000" height="600"
+     loading="lazy" decoding="async"
+     alt="Total time to run all TPC-DS queries — Comet versus stock Apache Spark" />
+<figcaption>Total time to run all queries (lower is better).</figcaption>
+</figure>
+</div>
+</section>
+
+<section class="comet-feature">
+<div class="comet-feature__inner">
+<div class="comet-feature__copy">
+<p class="comet-feature__eyebrow">Spark Compatibility</p>
+<h2 class="comet-feature__title">100% compatibility with supported Spark versions.</h2>
+<p class="comet-feature__body">Comet aims for 100% compatibility with all supported versions of Apache Spark, allowing you to integrate Comet into your existing Spark deployments and workflows seamlessly. With no code changes required, you can immediately harness the benefits of Comet's acceleration capabilities without disrupting your Spark applications. The Comet extension automatically detects unsupported features and falls back to the Spark engine.</p>
+<p class="comet-feature__links">
+<a href="user-guide/latest/compatibility/spark-versions.html">Spark version compatibility &rarr;</a>
+</p>
+</div>
+</div>
+</section>
+
+<section class="comet-feature comet-feature--alt">
+<div class="comet-feature__inner">
+<div class="comet-feature__copy">
+<p class="comet-feature__eyebrow">Use Commodity Hardware</p>
+<h2 class="comet-feature__title">No GPUs. No FPGAs. No vendor lock-in.</h2>
+<p class="comet-feature__body">Comet leverages commodity hardware, eliminating the need for costly hardware upgrades or specialized hardware accelerators, such as GPUs or FPGA. By maximizing the utilization of commodity hardware, Comet ensures cost-effectiveness and scalability for your Spark deployments.</p>
+</div>
+</div>
+</section>
+
+<section class="comet-feature">
+<div class="comet-feature__inner">
+<div class="comet-feature__copy">
+<p class="comet-feature__eyebrow">Architecture</p>
+<h2 class="comet-feature__title">Tight integration with Apache DataFusion.</h2>
+<p class="comet-feature__body">Comet tightly integrates with the core Apache DataFusion project, leveraging its powerful execution engine. The diagram below shows how the Comet plugin intercepts Spark physical plans, translates supported operators into a protocol-buffer representation, and hands them to the Apache DataFusion native engine for execution.</p>
+</div>
+<figure class="comet-feature__figure">
+<img src="_static/images/comet-overview.png"
+     width="2569" height="2006"
+     loading="lazy" decoding="async"
+     alt="Comet architecture overview diagram showing the bridge between Apache Spark and Apache DataFusion" />
+<figcaption>Comet Overview</figcaption>
+</figure>
+<p class="comet-feature__links">
+<a href="contributor-guide/plugin_overview.html">How Comet works &rarr;</a>
+</p>
+</div>
+</section>
 
-## Getting Started
+<section class="comet-community">
+<div class="comet-community__inner comet-community__inner--two">
 
-To get started with Apache DataFusion Comet, follow the
-[installation instructions](https://datafusion.apache.org/comet/user-guide/installation.html). Join the
-[DataFusion Slack and Discord channels](https://datafusion.apache.org/contributor-guide/communication.html) to connect
-with other users, ask questions, and share your experiences with Comet.
+<div class="comet-community__col">
+<p class="comet-community__eyebrow">Getting Started</p>
+<p class="comet-community__body">To get started with Apache DataFusion Comet, follow the <a href="user-guide/latest/installation.html">installation instructions</a>. Join the <a href="https://datafusion.apache.org/contributor-guide/communication.html">DataFusion Slack and Discord channels</a> to connect with other users, ask questions, and share your experiences with Comet.</p>
+</div>
 
-## Contributing
+<div class="comet-community__col">
+<p class="comet-community__eyebrow">Contributing</p>
+<p class="comet-community__body">We welcome contributions from the community to help improve and enhance Apache DataFusion Comet. Whether it's fixing bugs, adding new features, writing documentation, or optimizing performance, your contributions are invaluable in shaping the future of Comet. Check out our <a href="contributor-guide/index.html">contributor guide</a> to get started.</p>
+</div>
 
-We welcome contributions from the community to help improve and enhance Apache DataFusion Comet. Whether it's fixing
-bugs, adding new features, writing documentation, or optimizing performance, your contributions are invaluable in
-shaping the future of Comet. Check out our
-[contributor guide](https://datafusion.apache.org/comet/contributor-guide/contributing.html) to get started.
+</div>
+</section>
 
 ```{toctree}
 :maxdepth: 1
@@ -108,7 +137,5 @@ shaping the future of Comet. Check out our
 User Guide <user-guide/index>
 Contributor Guide <contributor-guide/index>
 Changelog <changelog/index>
-Comparison with Gluten <about/gluten_comparison>
-Versioning Policy <about/versioning_policy>
-ASF Links <asf/index>
+About <about/index>
 ```