diff --git a/src/app/[slug]/page.tsx b/src/app/[slug]/page.tsx
index deb14fe..1743730 100644
--- a/src/app/[slug]/page.tsx
+++ b/src/app/[slug]/page.tsx
@@ -33,16 +33,16 @@ export default async function StandaloneSitePage({ params }: SitePageParams) {
   if (!page) notFound();
 
   return (
-    <div className="mx-auto max-w-3xl px-6 py-10 sm:px-8 lg:py-14">
-      <h1 className="text-3xl font-bold tracking-tight text-foreground sm:text-4xl">
+    <div className="mx-auto w-full max-w-3xl px-4 py-8 sm:px-6 lg:py-12 min-w-0 overflow-hidden">
+      <h1 className="text-2xl sm:text-3xl md:text-4xl font-bold tracking-tight text-foreground">
         {page.title}
       </h1>
       {page.description && (
-        <p className="mt-3 text-base text-muted-foreground leading-relaxed">
+        <p className="mt-3 text-sm sm:text-base text-muted-foreground leading-relaxed">
           {page.description}
         </p>
       )}
-      <div className="mt-8 border-t border-border pt-6">
+      <div className="mt-8 border-t border-border pt-6 min-w-0 break-words">
         <Markdown source={page.body} />
       </div>
     </div>
diff --git a/src/app/changelog/page.tsx b/src/app/changelog/page.tsx
index f67940a..f91dfaf 100644
--- a/src/app/changelog/page.tsx
+++ b/src/app/changelog/page.tsx
@@ -17,11 +17,11 @@ export default async function ChangelogPage() {
   const entries = await getChangelog();
 
   return (
-    <div className="mx-auto max-w-3xl px-6 py-10 sm:px-8 lg:py-14">
-      <h1 className="text-3xl font-bold tracking-tight text-foreground sm:text-4xl">
+    <div className="mx-auto w-full max-w-3xl px-4 py-8 sm:px-6 lg:py-12 min-w-0 overflow-hidden">
+      <h1 className="text-2xl sm:text-3xl md:text-4xl font-bold tracking-tight text-foreground">
         Changelog
       </h1>
-      <p className="mt-3 text-base text-muted-foreground leading-relaxed">
+      <p className="mt-3 text-sm sm:text-base text-muted-foreground leading-relaxed">
         What shipped, release by release. Releases are tagged on{" "}
         <a
           href={`${GITHUB_URL}/releases`}
@@ -34,18 +34,18 @@ export default async function ChangelogPage() {
         .
       </p>
 
-      <div className="mt-12 space-y-0">
+      <div className="mt-10 sm:mt-12 space-y-0">
         {entries.map((entry) => (
           <section
             key={entry.version}
             id={`v${entry.version}`}
-            className="relative grid scroll-mt-24 gap-4 border-l border-border pb-12 pl-6 sm:grid-cols-[8.5rem_minmax(0,1fr)] sm:gap-8"
+            className="relative grid scroll-mt-24 gap-4 border-l border-border pb-10 pl-5 sm:pb-12 sm:pl-8 sm:grid-cols-[8.5rem_minmax(0,1fr)] sm:gap-8 min-w-0"
           >
             <span
               aria-hidden
               className="absolute -left-[5px] top-1.5 size-2 rounded-full bg-foreground"
             />
-            <header>
+            <header className="min-w-0">
               <h2 className="font-mono text-base font-semibold text-foreground">
                 v{entry.version}
               </h2>
@@ -66,13 +66,13 @@ export default async function ChangelogPage() {
                 ))}
               </p>
             </header>
-            <div>
+            <div className="min-w-0 overflow-hidden">
               {entry.title && (
-                <h3 className="text-lg font-semibold tracking-tight text-foreground">
+                <h3 className="text-base sm:text-lg font-semibold tracking-tight text-foreground">
                   {entry.title}
                 </h3>
               )}
-              <div className="mt-2.5">
+              <div className="mt-2.5 min-w-0 break-words">
                 <Markdown source={entry.body} className="prose-sm" />
               </div>
             </div>
diff --git a/src/app/docs/[section]/[slug]/page.tsx b/src/app/docs/[section]/[slug]/page.tsx
index 7766ace..84270c4 100644
--- a/src/app/docs/[section]/[slug]/page.tsx
+++ b/src/app/docs/[section]/[slug]/page.tsx
@@ -70,7 +70,7 @@ export default async function DocPage({ params }: DocPageParams) {
   const templateBadge = TEMPLATE_BADGES[page.sectionSlug] ?? { label: "Guide", color: "bg-muted text-muted-foreground border-border" };
 
   return (
-    <div className="flex w-full justify-between gap-12">
+    <div className="flex w-full justify-between gap-8 lg:gap-12 min-w-0">
       <JsonLd
         data={{
           "@context": "https://schema.org",
@@ -100,30 +100,30 @@ export default async function DocPage({ params }: DocPageParams) {
       />
 
       {/* Centre Column: max-w-[720px] for prose, code breaks wider up to 860px */}
-      <article className="min-w-0 max-w-[720px] flex-1 pb-16">
+      <article className="min-w-0 max-w-full lg:max-w-[720px] flex-1 pb-16">
         {/* Breadcrumb + Diataxis badge */}
         <div className="flex items-center justify-between gap-2 text-xs mb-3">
-          <nav aria-label="Breadcrumb" className="flex items-center gap-1.5 text-muted-foreground">
-            <Link href="/docs" className="hover:text-foreground transition-colors">
+          <nav aria-label="Breadcrumb" className="flex items-center gap-1.5 text-muted-foreground truncate pr-2">
+            <Link href="/docs" className="hover:text-foreground transition-colors shrink-0">
               Docs
             </Link>
-            <span className="text-border-strong">/</span>
-            <span>{page.sectionTitle}</span>
+            <span className="text-border-strong shrink-0">/</span>
+            <span className="truncate">{page.sectionTitle}</span>
           </nav>
 
-          <span className={`inline-flex items-center px-2 py-0.5 rounded text-[10px] font-mono font-medium border ${templateBadge.color}`}>
+          <span className={`inline-flex items-center px-2 py-0.5 rounded text-[10px] font-mono font-medium border shrink-0 ${templateBadge.color}`}>
             {templateBadge.label}
           </span>
         </div>
 
         {/* H1 Title */}
-        <h1 className="text-3xl sm:text-4xl font-bold tracking-tight text-foreground leading-tight">
+        <h1 className="text-2xl sm:text-3xl md:text-4xl font-bold tracking-tight text-foreground leading-tight">
           {page.title}
         </h1>
 
         {/* One-sentence summary in larger, muted text */}
         {page.description && (
-          <p className="mt-3 text-lg leading-relaxed text-muted-foreground font-normal">
+          <p className="mt-3 text-base sm:text-lg leading-relaxed text-muted-foreground font-normal">
             {page.description}
           </p>
         )}
@@ -135,7 +135,7 @@ export default async function DocPage({ params }: DocPageParams) {
         </div>
 
         {/* Markdown Content */}
-        <div className="mt-6">
+        <div className="mt-6 min-w-0 max-w-full overflow-hidden">
           <Markdown source={page.body} />
         </div>
 
diff --git a/src/app/docs/layout.tsx b/src/app/docs/layout.tsx
index cd9a9c5..524e32c 100644
--- a/src/app/docs/layout.tsx
+++ b/src/app/docs/layout.tsx
@@ -9,9 +9,9 @@ export default async function DocsLayout({
   const sections = await getDocSections();
 
   return (
-    <div className="mx-auto flex w-full max-w-[1400px] flex-1">
+    <div className="mx-auto flex w-full max-w-[1440px] flex-1">
       <DocsSidebar sections={sections} />
-      <div className="min-w-0 flex-1 px-6 py-8 sm:px-10 lg:py-10">
+      <div className="min-w-0 flex-1 px-4 py-6 sm:px-8 lg:px-10 lg:py-10 overflow-x-hidden">
         {children}
       </div>
     </div>
diff --git a/src/app/globals.css b/src/app/globals.css
index 2aebb5e..03ae851 100644
--- a/src/app/globals.css
+++ b/src/app/globals.css
@@ -192,6 +192,9 @@ body {
   font-size: 0.875rem;
   margin: 1.75rem 0;
   border: 1px solid var(--border);
+  display: block;
+  overflow-x: auto;
+  max-width: 100%;
 }
 
 .prose :where(thead th) {
@@ -272,7 +275,7 @@ body {
   background: var(--code-bg);
   border-radius: 6px;
   overflow: hidden;
-  max-width: 860px;
+  max-width: 100%;
 }
 
 [data-rehype-pretty-code-figure] pre {
diff --git a/src/components/docs/sidebar.tsx b/src/components/docs/sidebar.tsx
index daed31d..e19c3c8 100644
--- a/src/components/docs/sidebar.tsx
+++ b/src/components/docs/sidebar.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { ChevronDown } from "lucide-react";
+import { ChevronDown, FileText, X } from "lucide-react";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
 import { useState } from "react";
@@ -17,11 +17,11 @@ const DIATAXIS_HINTS: Record<string, string> = {
   reference: "Reference",
 };
 
-function SectionNav({ sections }: { sections: DocSection[] }) {
+function SectionNav({ sections, onNavigate }: { sections: DocSection[]; onNavigate?: () => void }) {
   const pathname = usePathname();
 
   return (
-    <nav aria-label="Documentation" className="space-y-6 text-xs flex flex-col justify-between min-h-[calc(100vh-6.5rem)]">
+    <nav aria-label="Documentation" className="space-y-6 text-xs flex flex-col justify-between min-h-full">
       <div className="space-y-6">
         {sections.map((section) => {
           const modeHint = DIATAXIS_HINTS[section.slug];
@@ -43,6 +43,7 @@ function SectionNav({ sections }: { sections: DocSection[] }) {
                     <li key={page.slug}>
                       <Link
                         href={href}
+                        onClick={onNavigate}
                         aria-current={active ? "page" : undefined}
                         className={cn(
                           "block px-2.5 py-1.5 rounded transition-colors text-xs leading-snug",
@@ -71,6 +72,7 @@ function SectionNav({ sections }: { sections: DocSection[] }) {
           <li>
             <Link
               href="/privacy"
+              onClick={onNavigate}
               className={cn(
                 "block px-2 py-1 rounded transition-colors",
                 pathname === "/privacy"
@@ -84,6 +86,7 @@ function SectionNav({ sections }: { sections: DocSection[] }) {
           <li>
             <Link
               href="/terms"
+              onClick={onNavigate}
               className={cn(
                 "block px-2 py-1 rounded transition-colors",
                 pathname === "/terms"
@@ -126,30 +129,47 @@ export function DocsSidebar({ sections }: { sections: DocSection[] }) {
 
   return (
     <>
-      {/* Mobile: bottom drawer toggle */}
+      {/* Mobile: sticky page selector bar */}
       <div className="sticky top-14 z-30 flex w-full items-center justify-between border-b border-border bg-background/95 px-4 py-2.5 backdrop-blur-md lg:hidden">
         <button
           onClick={() => setMobileOpen((open) => !open)}
           aria-expanded={mobileOpen}
           className="flex w-full cursor-pointer items-center justify-between text-xs font-medium"
         >
-          <span className="text-foreground">
-            {current?.title ?? "Documentation"}
-          </span>
+          <div className="flex items-center gap-2 truncate pr-2">
+            <FileText className="size-3.5 text-muted-foreground shrink-0" />
+            <span className="text-foreground truncate">
+              {current?.title ?? "Documentation"}
+            </span>
+          </div>
           <ChevronDown
             className={cn(
-              "size-4 text-muted-foreground transition-transform duration-200",
+              "size-4 text-muted-foreground transition-transform duration-200 shrink-0",
               mobileOpen && "rotate-180",
             )}
             aria-hidden
           />
         </button>
+
         {mobileOpen && (
-          <div
-            className="absolute left-0 right-0 top-full max-h-[75vh] overflow-y-auto border-b border-border bg-background p-4 shadow-xl z-50"
-            onClick={() => setMobileOpen(false)}
-          >
-            <SectionNav sections={sections} />
+          <div className="fixed inset-0 top-14 z-50 flex flex-col bg-background/98 backdrop-blur-md">
+            {/* Top close header bar */}
+            <div className="flex items-center justify-between border-b border-border px-4 py-3 bg-muted/40">
+              <span className="text-xs font-semibold text-foreground uppercase tracking-wider font-mono">
+                Documentation Index
+              </span>
+              <button
+                onClick={() => setMobileOpen(false)}
+                className="flex size-7 items-center justify-center rounded border border-border text-muted-foreground hover:text-foreground"
+                aria-label="Close menu"
+              >
+                <X className="size-4" />
+              </button>
+            </div>
+            {/* Nav content */}
+            <div className="flex-1 overflow-y-auto p-5">
+              <SectionNav sections={sections} onNavigate={() => setMobileOpen(false)} />
+            </div>
           </div>
         )}
       </div>
diff --git a/src/components/site-header.tsx b/src/components/site-header.tsx
index 5a5c685..e95c85b 100644
--- a/src/components/site-header.tsx
+++ b/src/components/site-header.tsx
@@ -31,13 +31,13 @@ export function SiteHeader({ searchItems }: { searchItems: SearchItem[] }) {
   }
 
   return (
-    <header className="sticky top-0 z-40 h-14 border-b border-border bg-background/90 backdrop-blur-md transition-colors">
-      <div className="mx-auto flex h-full max-w-[1440px] items-center justify-between gap-4 px-4 sm:px-6">
+    <header className="sticky top-0 z-40 h-14 border-b border-border bg-background/90 backdrop-blur-md transition-colors w-full overflow-hidden">
+      <div className="mx-auto flex h-full max-w-[1440px] items-center justify-between gap-1 sm:gap-3 px-3 sm:px-6">
         {/* Left: Logo + Version Dropdown Pill */}
-        <div className="flex items-center gap-4">
+        <div className="flex items-center gap-1.5 sm:gap-3 shrink min-w-0">
           <Logo />
 
-          <div className="relative">
+          <div className="relative shrink-0 hidden sm:block">
             <button
               onClick={() => setVersionOpen((o) => !o)}
               aria-label="Version selector"
@@ -76,7 +76,7 @@ export function SiteHeader({ searchItems }: { searchItems: SearchItem[] }) {
             )}
           </div>
 
-          <nav aria-label="Main" className="hidden items-center gap-1 ml-4 md:flex">
+          <nav aria-label="Main" className="hidden lg:flex items-center gap-1 ml-2">
             {NAV.map((item) => {
               const active =
                 item.href === "/docs"
@@ -101,18 +101,14 @@ export function SiteHeader({ searchItems }: { searchItems: SearchItem[] }) {
           </nav>
         </div>
 
-        {/* Center / Wide Search: ⌘K or / */}
-        <div className="flex-1 max-w-md mx-2 hidden sm:block">
+        {/* Center: Search Field */}
+        <div className="flex-1 min-w-0 max-w-[120px] xs:max-w-[180px] sm:max-w-xs md:max-w-md mx-1 sm:mx-2">
           <SearchDialog items={searchItems} />
         </div>
 
-        {/* Right: Language, GitHub, Theme, Mobile toggle */}
-        <div className="flex items-center gap-2 sm:gap-2.5">
-          <div className="sm:hidden">
-            <SearchDialog items={searchItems} />
-          </div>
-
-          <div className="hidden sm:flex items-center rounded border border-border bg-card px-2 py-0.5 font-mono text-[11px] text-muted-foreground">
+        {/* Right Controls */}
+        <div className="flex items-center gap-1 shrink-0">
+          <div className="hidden xl:flex items-center rounded border border-border bg-card px-2 py-0.5 font-mono text-[11px] text-muted-foreground">
             <span className="font-semibold text-foreground">Python</span>
             <span className="text-faint ml-1">3.11+</span>
           </div>
@@ -122,7 +118,7 @@ export function SiteHeader({ searchItems }: { searchItems: SearchItem[] }) {
             target="_blank"
             rel="noreferrer"
             aria-label="Agentling on GitHub"
-            className="flex size-8 items-center justify-center rounded border border-border text-muted-foreground hover:text-foreground hover:border-border-strong transition-colors"
+            className="hidden sm:flex size-8 items-center justify-center rounded border border-border text-muted-foreground hover:text-foreground hover:border-border-strong transition-colors"
           >
             <GithubIcon className="size-3.5" aria-hidden />
           </a>
@@ -133,7 +129,7 @@ export function SiteHeader({ searchItems }: { searchItems: SearchItem[] }) {
             onClick={() => setMenuOpen((open) => !open)}
             aria-expanded={menuOpen}
             aria-label={menuOpen ? "Close menu" : "Open menu"}
-            className="flex size-8 cursor-pointer items-center justify-center rounded border border-border text-muted-foreground md:hidden"
+            className="flex size-8 cursor-pointer items-center justify-center rounded border border-border text-muted-foreground lg:hidden shrink-0"
           >
             {menuOpen ? <X className="size-3.5" aria-hidden /> : <Menu className="size-3.5" aria-hidden />}
           </button>
@@ -143,7 +139,7 @@ export function SiteHeader({ searchItems }: { searchItems: SearchItem[] }) {
       {menuOpen && (
         <nav
           aria-label="Mobile"
-          className="border-t border-border bg-background px-4 py-3 md:hidden shadow-lg"
+          className="border-t border-border bg-background px-4 py-3 lg:hidden shadow-lg"
         >
           <ul className="flex flex-col gap-1">
             {NAV.map((item) => (
diff --git a/src/components/theme-toggle.tsx b/src/components/theme-toggle.tsx
index daaf986..c24e5ef 100644
--- a/src/components/theme-toggle.tsx
+++ b/src/components/theme-toggle.tsx
@@ -8,7 +8,6 @@ import { cn } from "@/lib/utils";
 
 const emptySubscribe = () => () => {};
 
-/** True after hydration; false during SSR, so theme state never mismatches. */
 function useMounted(): boolean {
   return useSyncExternalStore(
     emptySubscribe,
@@ -17,43 +16,79 @@ function useMounted(): boolean {
   );
 }
 
-const OPTIONS = [
-  { value: "light", label: "Light theme", icon: Sun },
-  { value: "dark", label: "Dark theme", icon: Moon },
-  { value: "system", label: "System theme", icon: Monitor },
-] as const;
-
-export function ThemeToggle() {
+export function ThemeToggle({ className }: { className?: string }) {
   const { theme, setTheme } = useTheme();
   const mounted = useMounted();
 
+  const isDark = mounted ? theme === "dark" : true;
+
+  function toggle() {
+    setTheme(isDark ? "light" : "dark");
+  }
+
   return (
-    <div
-      role="radiogroup"
-      aria-label="Theme"
-      className="flex items-center gap-0.5 rounded-full border border-border p-0.5"
-    >
-      {OPTIONS.map(({ value, label, icon: Icon }) => {
-        const active = mounted && theme === value;
-        return (
-          <button
-            key={value}
-            role="radio"
-            aria-checked={active}
-            aria-label={label}
-            title={label}
-            onClick={() => setTheme(value)}
-            className={cn(
-              "flex size-7 cursor-pointer items-center justify-center rounded-full transition-colors duration-150",
-              active
-                ? "bg-muted text-foreground"
-                : "text-muted-foreground hover:text-foreground",
-            )}
-          >
-            <Icon className="size-3.5" aria-hidden />
-          </button>
-        );
-      })}
-    </div>
+    <>
+      {/* Mobile / Tablet compact 1-button toggle (32x32px) */}
+      <button
+        onClick={toggle}
+        aria-label={isDark ? "Switch to light theme" : "Switch to dark theme"}
+        className={cn(
+          "flex size-8 cursor-pointer items-center justify-center rounded border border-border text-muted-foreground hover:text-foreground hover:border-border-strong transition-colors sm:hidden",
+          className
+        )}
+      >
+        {isDark ? <Sun className="size-3.5" /> : <Moon className="size-3.5" />}
+      </button>
+
+      {/* Desktop 3-option toggle pill */}
+      <div
+        role="radiogroup"
+        aria-label="Theme"
+        className={cn("hidden sm:flex items-center gap-0.5 rounded-full border border-border p-0.5", className)}
+      >
+        <button
+          role="radio"
+          aria-checked={mounted ? theme === "light" : false}
+          aria-label="Light theme"
+          onClick={() => setTheme("light")}
+          className={cn(
+            "flex size-6 cursor-pointer items-center justify-center rounded-full transition-colors duration-150",
+            mounted && theme === "light"
+              ? "bg-muted text-foreground"
+              : "text-muted-foreground hover:text-foreground",
+          )}
+        >
+          <Sun className="size-3" aria-hidden />
+        </button>
+        <button
+          role="radio"
+          aria-checked={mounted ? theme === "dark" : true}
+          aria-label="Dark theme"
+          onClick={() => setTheme("dark")}
+          className={cn(
+            "flex size-6 cursor-pointer items-center justify-center rounded-full transition-colors duration-150",
+            mounted && theme === "dark"
+              ? "bg-muted text-foreground"
+              : "text-muted-foreground hover:text-foreground",
+          )}
+        >
+          <Moon className="size-3" aria-hidden />
+        </button>
+        <button
+          role="radio"
+          aria-checked={mounted ? theme === "system" : false}
+          aria-label="System theme"
+          onClick={() => setTheme("system")}
+          className={cn(
+            "flex size-6 cursor-pointer items-center justify-center rounded-full transition-colors duration-150",
+            mounted && theme === "system"
+              ? "bg-muted text-foreground"
+              : "text-muted-foreground hover:text-foreground",
+          )}
+        >
+          <Monitor className="size-3" aria-hidden />
+        </button>
+      </div>
+    </>
   );
 }