diff --git a/web/src/pages/Docs/index.jsx b/web/src/pages/Docs/index.jsx
index e4e1b06..83c9b52 100644
--- a/web/src/pages/Docs/index.jsx
+++ b/web/src/pages/Docs/index.jsx
@@ -85,7 +85,7 @@ function CodeBlock({ code, lang = 'bash' }) {
 /* ─── SectionTitle ─── */
 function SectionTitle({ id, icon: Icon, children }) {
   return (
-    <h2 id={id} className="group flex items-center gap-3 mt-12 mb-5 scroll-mt-24">
+    <h2 id={id} className="group flex items-center gap-3 mt-12 mb-5 scroll-mt-[72px]">
       <span className="flex items-center justify-center w-9 h-9 rounded-lg bg-violet-100 dark:bg-violet-900/30 text-violet-600 dark:text-violet-400">
         <Icon size={18} />
       </span>
@@ -152,6 +152,9 @@ export default function Docs() {
   const [sidebarOpen, setSidebarOpen] = useState(false);
   const contentRef = useRef(null);
 
+  // Header height offset (56px header + 16px breathing room)
+  const HEADER_OFFSET = 72;
+
   // Scroll spy
   useEffect(() => {
     const observer = new IntersectionObserver(
@@ -163,7 +166,7 @@ export default function Docs() {
           }
         }
       },
-      { rootMargin: '-80px 0px -70% 0px', threshold: 0 }
+      { rootMargin: `-${HEADER_OFFSET}px 0px -70% 0px`, threshold: 0 }
     );
 
     const ids = DOC_SECTIONS.map((s) => s.id);
@@ -177,7 +180,10 @@ export default function Docs() {
 
   const scrollTo = (id) => {
     setSidebarOpen(false);
-    document.getElementById(id)?.scrollIntoView({ behavior: 'smooth' });
+    const el = document.getElementById(id);
+    if (!el) return;
+    const top = el.getBoundingClientRect().top + window.scrollY - HEADER_OFFSET;
+    window.scrollTo({ top, behavior: 'smooth' });
   };
 
   const BASE_HOST = window.location.origin;