diff --git a/apps/web/src/components/docs/DocsSidebar.astro b/apps/web/src/components/docs/DocsSidebar.astro
index 41cd1f5..352b69e 100644
--- a/apps/web/src/components/docs/DocsSidebar.astro
+++ b/apps/web/src/components/docs/DocsSidebar.astro
@@ -99,8 +99,9 @@ const tree = buildTree(headings);
 <style>
   .docs-sidebar {
     position: sticky;
-    top: 2rem;
-    max-height: calc(100vh - 4rem);
+    top: calc(2rem + var(--sticky-offset));
+    max-height: calc(100vh - 4rem - var(--sticky-offset));
+    transition: top 260ms cubic-bezier(0.2, 0.7, 0.2, 1);
     overflow-y: auto;
   }
 
@@ -108,15 +109,16 @@ const tree = buildTree(headings);
     display: none;
   }
 
-  @media (max-width: 760px) {
+  @media (max-width: 759px) {
     .docs-sidebar {
       display: none;
     }
 
     .docs-mobile-toc-wrap {
       position: sticky;
-      top: 0;
+      top: var(--sticky-offset);
       z-index: 40;
+      transition: top 260ms cubic-bezier(0.2, 0.7, 0.2, 1);
       padding-block: 0.5rem;
       background: var(--paper);
       display: block;
diff --git a/apps/web/src/components/landing/CommandsSection.astro b/apps/web/src/components/landing/CommandsSection.astro
index 1eabb0b..da49afb 100644
--- a/apps/web/src/components/landing/CommandsSection.astro
+++ b/apps/web/src/components/landing/CommandsSection.astro
@@ -40,7 +40,8 @@ const commands = [
 
     .commands__title {
       position: sticky;
-      top: 2rem;
+      top: calc(2rem + var(--sticky-offset));
+      transition: top 260ms cubic-bezier(0.2, 0.7, 0.2, 1);
     }
   }
 
diff --git a/apps/web/src/components/landing/CopyCommand.astro b/apps/web/src/components/landing/CopyCommand.astro
index 8c67db9..163300b 100644
--- a/apps/web/src/components/landing/CopyCommand.astro
+++ b/apps/web/src/components/landing/CopyCommand.astro
@@ -13,8 +13,17 @@ const { command, size = "base" } = Astro.props;
     <span class="copy__text">{command}</span>
   </code>
   <button type="button" class="copy__button" aria-label={`Copy ${command}`}>
-    <span class="copy__idle">Copy</span>
-    <span class="copy__done" aria-hidden="true">Copied</span>
+    <svg class="copy__icon copy__icon--copy" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
+      <rect x="5.25" y="5.25" width="8" height="8" rx="1.5" fill="none" stroke="currentColor" stroke-width="1.5" />
+      <path d="M10.75 3.5v-.25A1.5 1.5 0 0 0 9.25 1.75h-5.5a1.5 1.5 0 0 0-1.5 1.5v5.5a1.5 1.5 0 0 0 1.5 1.5H4" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
+    </svg>
+    <svg class="copy__icon copy__icon--check" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
+      <path d="m3 8.5 3.25 3.25L13 4.75" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" />
+    </svg>
+    <span class="copy__label">
+      <span class="copy__idle">Copy</span>
+      <span class="copy__done" aria-hidden="true">Copied</span>
+    </span>
   </button>
 </div>
 
@@ -29,94 +38,123 @@ const { command, size = "base" } = Astro.props;
 </script>
 
 <style>
+  /*
+   * One line of type sitting on a rule, not a box. The whole row is the click
+   * target (the button stretches over it), and the rule turns blue on hover.
+   */
   .copy {
-    display: inline-flex;
-    align-items: stretch;
-    max-width: 100%;
-    border: 1px solid var(--ink);
-    border-radius: var(--radius);
-    background: var(--paper);
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 1.5rem;
+    width: min(100%, 30rem);
+    padding-bottom: 0.7rem;
+    border-bottom: 1px solid var(--ink);
+    transition: border-color 150ms ease;
+  }
+
+  .copy:hover,
+  .copy:has(.copy__button:focus-visible) {
+    border-bottom-color: var(--accent);
   }
 
   .copy__line {
-    display: flex;
-    align-items: center;
-    gap: 0.75ch;
     min-width: 0;
-    padding: 0.8rem 1rem;
-    font-size: 0.9375rem;
+    font-size: 1.0625rem;
     color: var(--ink);
-    overflow-x: auto;
-    white-space: nowrap;
+    overflow-wrap: anywhere;
   }
 
   .copy__prompt {
-    color: var(--accent);
+    margin-right: 0.9ch;
+    color: var(--muted);
   }
 
   .copy__button {
     flex: none;
-    min-width: 5.5rem;
-    padding: 0 1rem;
+    display: inline-flex;
+    align-items: center;
+    gap: 0.45rem;
+    padding: 0;
     border: 0;
-    border-left: 1px solid var(--ink);
-    border-radius: 0 calc(var(--radius) - 1px) calc(var(--radius) - 1px) 0;
-    background: var(--ink);
-    color: var(--paper);
+    background: none;
+    color: var(--muted);
     font-family: var(--font-body);
     font-size: 0.9375rem;
-    font-weight: 500;
     cursor: pointer;
-    transition: background 150ms ease;
+    transition: color 150ms ease;
   }
 
-  .copy__button:hover {
-    background: var(--accent);
+  /* Stretch the hit area over the whole row. */
+  .copy__button::after {
+    content: "";
+    position: absolute;
+    inset: -0.5rem 0 0;
+  }
+
+  .copy__button:focus-visible {
+    outline: none;
+  }
+
+  .copy__button:focus-visible::after {
+    outline: 2px solid var(--accent);
+    outline-offset: 4px;
+  }
+
+  .copy:hover .copy__button {
+    color: var(--accent);
   }
 
+  .copy__icon {
+    flex: none;
+  }
+
+  .copy__icon--check,
   .copy__done,
+  .copy__button[data-copied] .copy__icon--copy,
   .copy__button[data-copied] .copy__idle {
     display: none;
   }
 
+  .copy__button[data-copied] {
+    color: var(--accent);
+  }
+
+  .copy__button[data-copied] .copy__icon--check {
+    display: block;
+  }
+
   .copy__button[data-copied] .copy__done {
     display: inline;
   }
 
-  /* On narrow screens let the command wrap instead of hiding its tail. */
-  @media (max-width: 40rem) {
-    .copy__line {
-      align-items: flex-start;
-      padding: 0.75rem;
-      font-size: 0.8125rem;
-      white-space: normal;
-      overflow-wrap: anywhere;
-    }
-
-    .copy__button {
-      min-width: 4.5rem;
-      padding: 0 0.75rem;
-    }
+  /* Large: the command is the headline of its section. */
+  .copy--large {
+    width: min(100%, 52rem);
+    padding-bottom: 1.1rem;
   }
 
   .copy--large .copy__line {
-    padding: 1.1rem 1.4rem;
-    font-size: clamp(1rem, 2.6vw, 1.75rem);
+    font-size: clamp(1.25rem, 4.6vw, 2.75rem);
+    letter-spacing: -0.03em;
   }
 
   .copy--large .copy__button {
-    min-width: 7rem;
     font-size: 1.0625rem;
   }
 
   @media (max-width: 40rem) {
-    .copy--large .copy__line {
-      padding: 0.9rem 0.75rem;
-      font-size: 1rem;
+    .copy {
+      gap: 1rem;
     }
 
-    .copy--large .copy__button {
-      min-width: 4.5rem;
+    .copy__line {
+      font-size: 0.9375rem;
+    }
+
+    .copy--large .copy__line {
+      font-size: clamp(0.9375rem, 4.2vw, 1.5rem);
     }
   }
 </style>
diff --git a/apps/web/src/components/landing/HeroSection.astro b/apps/web/src/components/landing/HeroSection.astro
index 108d1de..3793582 100644
--- a/apps/web/src/components/landing/HeroSection.astro
+++ b/apps/web/src/components/landing/HeroSection.astro
@@ -19,7 +19,7 @@ import CopyCommand from "./CopyCommand.astro";
     <a class="link" href="https://github.com/itsflaid/devmap">Source on GitHub</a>
   </div>
 
-  <p class="hero__note">Needs Node 22 or newer. No account or API key to analyze.</p>
+  <p class="hero__note">Needs Node 22 or newer. An API key is optional and only adds the AI layer.</p>
 </section>
 
 <style>
@@ -74,9 +74,9 @@ import CopyCommand from "./CopyCommand.astro";
   .hero__install {
     display: flex;
     flex-wrap: wrap;
-    align-items: center;
-    gap: 1rem 2rem;
-    margin-top: 2rem;
+    align-items: baseline;
+    gap: 1.25rem 2.5rem;
+    margin-top: 2.25rem;
   }
 
   .hero__note {
diff --git a/apps/web/src/components/landing/SiteHeader.astro b/apps/web/src/components/landing/SiteHeader.astro
index ccf631f..e1a603d 100644
--- a/apps/web/src/components/landing/SiteHeader.astro
+++ b/apps/web/src/components/landing/SiteHeader.astro
@@ -6,26 +6,148 @@ const links = [
 ];
 ---
 
-<header class="header page">
-  <a class="header__brand" href="/" aria-label="DevMap home">
-    <img src="/logo-mark.png" alt="" width="28" height="28" />
-    <span>devmap</span>
-  </a>
-
-  <nav class="header__nav" aria-label="Primary">
-    {links.map((link) => <a href={link.href}>{link.label}</a>)}
-  </nav>
+<header class="site-header" data-site-header>
+  <div class="site-header__bar page">
+    <a class="site-header__brand" href="/" aria-label="DevMap home">
+      <img src="/logo-mark.png" alt="" width="28" height="28" />
+      <span>devmap</span>
+    </a>
+
+    <nav class="site-header__nav" id="site-nav" aria-label="Primary">
+      {links.map((link) => <a href={link.href}>{link.label}</a>)}
+    </nav>
+
+    <button
+      type="button"
+      class="site-header__toggle"
+      aria-expanded="false"
+      aria-controls="site-nav"
+      aria-label="Open menu"
+    >
+      <span class="site-header__toggle-bar"></span>
+      <span class="site-header__toggle-bar"></span>
+    </button>
+  </div>
 </header>
 
+<script>
+  const header = document.querySelector<HTMLElement>("[data-site-header]");
+  const toggle = header?.querySelector<HTMLButtonElement>(".site-header__toggle");
+  const nav = header?.querySelector<HTMLElement>(".site-header__nav");
+  const root = document.documentElement;
+
+  if (header && toggle && nav) {
+    // Tuned so a small flick upward brings the bar back at once, while
+    // reading downward (even with a jittery trackpad) keeps it out of the way.
+    const HIDE_AFTER = 96;
+    const DOWN_STEP = 6;
+    const UP_STEP = 3;
+
+    let lastY = window.scrollY;
+    let ticking = false;
+    let menuOpen = false;
+
+    const setShown = (shown: boolean) => {
+      header.classList.toggle("is-hidden", !shown);
+      root.dataset.header = shown ? "shown" : "hidden";
+    };
+
+    const setMenu = (open: boolean) => {
+      menuOpen = open;
+      header.classList.toggle("is-open", open);
+      toggle.setAttribute("aria-expanded", String(open));
+      toggle.setAttribute("aria-label", open ? "Close menu" : "Open menu");
+      if (open) setShown(true);
+    };
+
+    const update = () => {
+      ticking = false;
+      // iOS rubber-banding reports values outside the scrollable range.
+      const maxY = document.documentElement.scrollHeight - window.innerHeight;
+      const y = Math.min(Math.max(window.scrollY, 0), Math.max(maxY, 0));
+      const delta = y - lastY;
+
+      header.classList.toggle("is-stuck", y > 0);
+
+      if (y <= HIDE_AFTER) {
+        setShown(true);
+      } else if (delta >= DOWN_STEP && !menuOpen) {
+        setShown(false);
+      } else if (delta <= -UP_STEP) {
+        setShown(true);
+      }
+
+      if (Math.abs(delta) >= UP_STEP) lastY = y;
+    };
+
+    window.addEventListener(
+      "scroll",
+      () => {
+        if (!ticking) {
+          ticking = true;
+          window.requestAnimationFrame(update);
+        }
+      },
+      { passive: true }
+    );
+
+    toggle.addEventListener("click", () => setMenu(!menuOpen));
+
+    nav.querySelectorAll("a").forEach((link) =>
+      link.addEventListener("click", () => setMenu(false))
+    );
+
+    document.addEventListener("keydown", (event) => {
+      if (event.key === "Escape" && menuOpen) {
+        setMenu(false);
+        toggle.focus();
+      }
+    });
+
+    document.addEventListener("click", (event) => {
+      if (menuOpen && event.target instanceof Node && !header.contains(event.target)) {
+        setMenu(false);
+      }
+    });
+
+    // Leaving the narrow layout while the menu is open would strand state.
+    window.matchMedia("(min-width: 40.01rem)").addEventListener("change", (event) => {
+      if (event.matches) setMenu(false);
+    });
+
+    root.dataset.header = "shown";
+    update();
+  }
+</script>
+
 <style>
-  .header {
+  .site-header {
+    position: sticky;
+    top: 0;
+    z-index: 50;
+    background: var(--paper);
+    border-bottom: 1px solid transparent;
+    transition:
+      transform 260ms cubic-bezier(0.2, 0.7, 0.2, 1),
+      border-color 200ms ease;
+  }
+
+  .site-header.is-stuck {
+    border-bottom-color: var(--rule);
+  }
+
+  .site-header.is-hidden {
+    transform: translateY(-100%);
+  }
+
+  .site-header__bar {
     display: flex;
     align-items: center;
     justify-content: space-between;
-    min-height: 5rem;
+    min-height: var(--header-height);
   }
 
-  .header__brand {
+  .site-header__brand {
     display: inline-flex;
     align-items: center;
     gap: 0.6rem;
@@ -36,17 +158,17 @@ const links = [
     color: var(--ink);
   }
 
-  .header__brand img {
+  .site-header__brand img {
     display: block;
   }
 
-  .header__nav {
+  .site-header__nav {
     display: flex;
     gap: clamp(1rem, 3vw, 2rem);
     font-size: 0.9375rem;
   }
 
-  .header__nav a {
+  .site-header__nav a {
     padding-block: 0.5rem;
     color: var(--text);
     text-decoration: underline;
@@ -56,8 +178,94 @@ const links = [
     transition: text-decoration-color 150ms ease;
   }
 
-  .header__nav a:hover {
+  .site-header__nav a:hover {
     color: var(--ink);
     text-decoration-color: var(--accent);
   }
+
+  .site-header__toggle {
+    display: none;
+  }
+
+  /* Narrow screens: the links move into a panel under the bar. */
+  @media (max-width: 40rem) {
+    .site-header__toggle {
+      display: inline-flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      gap: 6px;
+      /* 44px square: the minimum comfortable touch target */
+      width: 2.75rem;
+      height: 2.75rem;
+      margin-right: -0.75rem;
+      padding: 0;
+      border: 0;
+      background: transparent;
+      cursor: pointer;
+    }
+
+    .site-header__toggle-bar {
+      display: block;
+      width: 1.375rem;
+      height: 2px;
+      background: var(--ink);
+      transition: transform 200ms ease;
+    }
+
+    .site-header.is-open .site-header__toggle-bar:first-child {
+      transform: translateY(4px) rotate(45deg);
+    }
+
+    .site-header.is-open .site-header__toggle-bar:last-child {
+      transform: translateY(-4px) rotate(-45deg);
+    }
+
+    .site-header__nav {
+      position: absolute;
+      inset-inline: 0;
+      top: 100%;
+      flex-direction: column;
+      gap: 0;
+      padding: 0.5rem var(--gutter) 1.25rem;
+      background: var(--paper);
+      border-bottom: 1px solid var(--rule);
+      font-family: var(--font-display);
+      font-size: 2rem;
+      font-weight: 600;
+      letter-spacing: -0.03em;
+      visibility: hidden;
+      opacity: 0;
+      transform: translateY(-0.5rem);
+      transition:
+        opacity 180ms ease,
+        transform 180ms ease,
+        visibility 0s linear 180ms;
+    }
+
+    .site-header.is-open .site-header__nav {
+      visibility: visible;
+      opacity: 1;
+      transform: none;
+      transition-delay: 0s;
+    }
+
+    .site-header__nav a {
+      padding-block: 0.75rem;
+      color: var(--ink);
+      border-top: 1px solid var(--rule);
+    }
+
+    .site-header__nav a:first-child {
+      border-top: 0;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .site-header,
+    .site-header__nav,
+    .site-header__toggle-bar {
+      transition: none;
+    }
+  }
 </style>
diff --git a/apps/web/src/pages/docs.astro b/apps/web/src/pages/docs.astro
index 45cc4a1..441e0fb 100644
--- a/apps/web/src/pages/docs.astro
+++ b/apps/web/src/pages/docs.astro
@@ -31,6 +31,17 @@ const { Content, headings } = await render(entry);
     padding-block: 1.5rem 5rem;
   }
 
+  /*
+   * Below the grid breakpoint the slot only wraps the mobile contents bar.
+   * Letting its children belong to .docs-page gives that bar the full page
+   * height to stick within; as a box of its own it would never stick.
+   */
+  @media (max-width: 759px) {
+    .docs-sidebar-slot {
+      display: contents;
+    }
+  }
+
   @media (min-width: 760px) {
     .docs-page {
       display: grid;
diff --git a/apps/web/src/styles/docs-prose.css b/apps/web/src/styles/docs-prose.css
index f502354..5bcf95e 100644
--- a/apps/web/src/styles/docs-prose.css
+++ b/apps/web/src/styles/docs-prose.css
@@ -10,7 +10,16 @@
 .docs-prose h4 {
   font-family: var(--font-display);
   color: var(--ink);
-  scroll-margin-top: 2rem;
+}
+
+/* On phones the sticky contents bar also sits under the header. */
+@media (max-width: 759px) {
+  .docs-prose h1,
+  .docs-prose h2,
+  .docs-prose h3,
+  .docs-prose h4 {
+    scroll-margin-top: 4.5rem;
+  }
 }
 
 .docs-prose h1 {
diff --git a/apps/web/src/styles/global.css b/apps/web/src/styles/global.css
index 2dc7299..6cb2e74 100644
--- a/apps/web/src/styles/global.css
+++ b/apps/web/src/styles/global.css
@@ -26,6 +26,9 @@
   --gutter: clamp(1.25rem, 5vw, 4rem);
   --section-space: clamp(4.5rem, 10vw, 8rem);
   --radius: 0.5rem;
+  --header-height: 4.5rem;
+  /* Sticky elements sit below the site header only while it is showing. */
+  --sticky-offset: 0px;
 
   background: var(--paper);
   font-family: var(--font-body);
@@ -42,7 +45,12 @@
 
 html {
   scroll-behavior: smooth;
-  scroll-padding-top: 2rem;
+  /* Anchors land below the site header, which may be showing when they scroll. */
+  scroll-padding-top: calc(var(--header-height) + 1.5rem);
+}
+
+html[data-header="shown"] {
+  --sticky-offset: var(--header-height);
 }
 
 body {