diff --git a/.github/workflows/squad-ci.yml b/.github/workflows/squad-ci.yml
index b10f94647..67a7299d0 100644
--- a/.github/workflows/squad-ci.yml
+++ b/.github/workflows/squad-ci.yml
@@ -23,6 +23,10 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Install docs dependencies
+        run: npm ci
+        working-directory: docs
+
       - name: Install Playwright browsers
         run: npx playwright install chromium --with-deps
 
diff --git a/docs/public/images/squad-logo.png b/docs/src/assets/images/squad-logo.png
similarity index 100%
rename from docs/public/images/squad-logo.png
rename to docs/src/assets/images/squad-logo.png
diff --git a/docs/src/components/Footer.astro b/docs/src/components/Footer.astro
index 095dbc756..f44ae621e 100644
--- a/docs/src/components/Footer.astro
+++ b/docs/src/components/Footer.astro
@@ -1,4 +1,6 @@
 ---
+import { Image } from 'astro:assets';
+import squadLogo from '../assets/images/squad-logo.png';
 const base = import.meta.env.BASE_URL;
 ---
 
@@ -7,7 +9,7 @@ const base = import.meta.env.BASE_URL;
     <div class="grid grid-cols-1 md:grid-cols-4 gap-8">
       <div>
         <div class="flex items-center gap-2 mb-3">
-          <img src={`${base}images/squad-logo.png`} alt="Squad" class="h-6 w-6" />
+          <Image src={squadLogo} alt="Squad" class="h-6 w-6" />
           <span class="font-semibold text-surface-900 dark:text-white">Squad</span>
         </div>
         <p class="text-base text-surface-500 dark:text-surface-400">
diff --git a/docs/src/components/Header.astro b/docs/src/components/Header.astro
index 3e2026568..c553ea458 100644
--- a/docs/src/components/Header.astro
+++ b/docs/src/components/Header.astro
@@ -1,7 +1,18 @@
 ---
+import { Image } from 'astro:assets';
 import ThemeToggle from './ThemeToggle.astro';
 import Search from './Search.astro';
+import squadLogo from '../assets/images/squad-logo.png';
 const base = import.meta.env.BASE_URL;
+const pathname = Astro.url.pathname;
+const isDocsActive = pathname.startsWith(`${base}docs/`);
+const isBlogActive = pathname.startsWith(`${base}blog/`);
+
+const navBase = "px-3 py-1.5 rounded-md transition-colors";
+const navInactive = "text-surface-600 dark:text-surface-400 hover:text-surface-900 dark:hover:text-white hover:bg-surface-100 dark:hover:bg-surface-800";
+const navActive = "text-squad-700 dark:text-squad-300 bg-squad-50 dark:bg-squad-900/30 font-medium";
+
+const mobileNavBase = "block px-3 py-2 rounded-md text-base transition-colors";
 ---
 
 <header class="sticky top-0 z-40 w-full border-b border-surface-200 dark:border-surface-800 bg-white/80 dark:bg-surface-950/80 backdrop-blur-lg">
@@ -30,15 +41,15 @@ const base = import.meta.env.BASE_URL;
 
     <!-- Logo -->
     <a href={base} class="flex items-center gap-2 font-semibold text-surface-900 dark:text-white mr-6">
-      <img src={`${base}images/squad-logo.png`} alt="Squad" class="h-7 w-7" />
+      <Image src={squadLogo} alt="Squad" class="h-7 w-7" />
       <span class="text-lg">Squad</span>
     </a>
 
     <!-- Top nav links (desktop) -->
     <nav class="hidden md:flex items-center gap-1 text-base">
-      <a href={`${base}docs/get-started/installation/`} class="px-3 py-1.5 rounded-md text-surface-600 dark:text-surface-400 hover:text-surface-900 dark:hover:text-white hover:bg-surface-100 dark:hover:bg-surface-800 transition-colors">Docs</a>
-      <a href={`${base}blog/`} class="px-3 py-1.5 rounded-md text-surface-600 dark:text-surface-400 hover:text-surface-900 dark:hover:text-white hover:bg-surface-100 dark:hover:bg-surface-800 transition-colors">Blog</a>
-      <a href="https://github.com/bradygaster/squad" class="px-3 py-1.5 rounded-md text-surface-600 dark:text-surface-400 hover:text-surface-900 dark:hover:text-white hover:bg-surface-100 dark:hover:bg-surface-800 transition-colors" target="_blank" rel="noopener">GitHub</a>
+      <a href={`${base}docs/get-started/installation/`} class:list={[navBase, isDocsActive ? navActive : navInactive]}>Docs</a>
+      <a href={`${base}blog/`} class:list={[navBase, isBlogActive ? navActive : navInactive]}>Blog</a>
+      <a href="https://github.com/bradygaster/squad" class:list={[navBase, navInactive]} target="_blank" rel="noopener">GitHub</a>
     </nav>
 
     <!-- Right side -->
@@ -62,9 +73,9 @@ const base = import.meta.env.BASE_URL;
   <!-- Mobile nav dropdown -->
   <nav id="mobile-nav" class="hidden md:hidden border-t border-surface-200 dark:border-surface-800 bg-white dark:bg-surface-950">
     <div class="px-4 py-3 space-y-1">
-      <a href={`${base}docs/get-started/installation/`} class="block px-3 py-2 rounded-md text-base text-surface-600 dark:text-surface-400 hover:text-surface-900 dark:hover:text-white hover:bg-surface-100 dark:hover:bg-surface-800 transition-colors">Docs</a>
-      <a href={`${base}blog/`} class="block px-3 py-2 rounded-md text-base text-surface-600 dark:text-surface-400 hover:text-surface-900 dark:hover:text-white hover:bg-surface-100 dark:hover:bg-surface-800 transition-colors">Blog</a>
-      <a href="https://github.com/bradygaster/squad" class="block px-3 py-2 rounded-md text-base text-surface-600 dark:text-surface-400 hover:text-surface-900 dark:hover:text-white hover:bg-surface-100 dark:hover:bg-surface-800 transition-colors" target="_blank" rel="noopener">GitHub</a>
+      <a href={`${base}docs/get-started/installation/`} class:list={[mobileNavBase, isDocsActive ? navActive : navInactive]}>Docs</a>
+      <a href={`${base}blog/`} class:list={[mobileNavBase, isBlogActive ? navActive : navInactive]}>Blog</a>
+      <a href="https://github.com/bradygaster/squad" class:list={[mobileNavBase, navInactive]} target="_blank" rel="noopener">GitHub</a>
     </div>
   </nav>
 </header>
diff --git a/docs/src/layouts/BaseLayout.astro b/docs/src/layouts/BaseLayout.astro
index db21b80c0..fe6b5a4b4 100644
--- a/docs/src/layouts/BaseLayout.astro
+++ b/docs/src/layouts/BaseLayout.astro
@@ -4,8 +4,11 @@ interface Props {
   description?: string;
 }
 
+import squadLogo from '../assets/images/squad-logo.png';
 const { title, description = 'Squad — Your AI Development Team. Describe what you\'re building. Get a team of specialists that live in your repo.' } = Astro.props;
-const base = import.meta.env.BASE_URL;
+const fullTitle = `${title} — Squad Docs`;
+const canonicalUrl = Astro.site ? new URL(Astro.url.pathname, Astro.site).href : undefined;
+const ogImage = Astro.site ? new URL(squadLogo.src, Astro.site).href : squadLogo.src;
 ---
 
 <!doctype html>
@@ -15,8 +18,21 @@ const base = import.meta.env.BASE_URL;
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="description" content={description} />
     <meta name="generator" content={Astro.generator} />
-    <link rel="icon" type="image/png" href={`${base}images/squad-logo.png`} />
-    <title>{title} — Squad Docs</title>
+    <link rel="icon" type="image/png" href={squadLogo.src} />
+    <title>{fullTitle}</title>
+
+    <!-- Open Graph -->
+    <meta property="og:type" content="website" />
+    <meta property="og:title" content={fullTitle} />
+    <meta property="og:description" content={description} />
+    <meta property="og:image" content={ogImage} />
+    {canonicalUrl && <meta property="og:url" content={canonicalUrl} />}
+
+    <!-- Twitter Card -->
+    <meta name="twitter:card" content="summary" />
+    <meta name="twitter:title" content={fullTitle} />
+    <meta name="twitter:description" content={description} />
+    <meta name="twitter:image" content={ogImage} />
     <script is:inline>
       const theme = localStorage.getItem('theme');
       if (theme === 'dark' || (!theme && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
diff --git a/package-lock.json b/package-lock.json
index c6d72f84e..acb6242c5 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@bradygaster/squad",
-  "version": "0.8.24.2",
+  "version": "0.8.25",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bradygaster/squad",
-      "version": "0.8.24.2",
+      "version": "0.8.25",
       "license": "MIT",
       "workspaces": [
         "packages/*"
@@ -17,6 +17,8 @@
         "@opentelemetry/sdk-trace-base": "^2.5.1",
         "@playwright/test": "^1.58.2",
         "@vitest/coverage-v8": "^3.2.4",
+        "highlight.js": "^11.11.1",
+        "markdown-it": "^14.1.1",
         "playwright": "^1.58.2",
         "typescript": "^5.7.0",
         "vitest": "^3.0.0"
@@ -2491,6 +2493,13 @@
         "url": "https://github.com/chalk/ansi-styles?sponsor=1"
       }
     },
+    "node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+      "dev": true,
+      "license": "Python-2.0"
+    },
     "node_modules/assertion-error": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
@@ -2878,6 +2887,19 @@
       "integrity": "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==",
       "license": "MIT"
     },
+    "node_modules/entities": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
+      "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
     "node_modules/environment": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/environment/-/environment-1.1.0.tgz",
@@ -3128,6 +3150,16 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/highlight.js": {
+      "version": "11.11.1",
+      "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-11.11.1.tgz",
+      "integrity": "sha512-Xwwo44whKBVCYoliBQwaPvtd/2tYFkRQtXDWj1nackaV2JPXx3L0+Jvd8/qCJ2p+ML0/XVkJ2q+Mr+UVdpJK5w==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/html-escaper": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz",
@@ -3357,6 +3389,16 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/linkify-it": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz",
+      "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "uc.micro": "^2.0.0"
+      }
+    },
     "node_modules/lodash.camelcase": {
       "version": "4.3.0",
       "resolved": "https://registry.npmjs.org/lodash.camelcase/-/lodash.camelcase-4.3.0.tgz",
@@ -3423,6 +3465,31 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/markdown-it": {
+      "version": "14.1.1",
+      "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.1.tgz",
+      "integrity": "sha512-BuU2qnTti9YKgK5N+IeMubp14ZUKUUw7yeJbkjtosvHiP0AZ5c8IAgEMk79D0eC8F23r4Ac/q8cAIFdm2FtyoA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1",
+        "entities": "^4.4.0",
+        "linkify-it": "^5.0.0",
+        "mdurl": "^2.0.0",
+        "punycode.js": "^2.3.1",
+        "uc.micro": "^2.1.0"
+      },
+      "bin": {
+        "markdown-it": "bin/markdown-it.mjs"
+      }
+    },
+    "node_modules/mdurl": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz",
+      "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/mimic-fn": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-2.1.0.tgz",
@@ -3694,6 +3761,16 @@
         "node": ">=12.0.0"
       }
     },
+    "node_modules/punycode.js": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz",
+      "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/react": {
       "version": "19.2.4",
       "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz",
@@ -4218,6 +4295,13 @@
         "node": ">=14.17"
       }
     },
+    "node_modules/uc.micro": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz",
+      "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/undici-types": {
       "version": "6.21.0",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
@@ -5193,11 +5277,11 @@
     },
     "packages/squad-cli": {
       "name": "@bradygaster/squad-cli",
-      "version": "0.8.24.2",
+      "version": "0.8.25",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {
-        "@bradygaster/squad-sdk": "*",
+        "@bradygaster/squad-sdk": "0.8.25",
         "ink": "^6.8.0",
         "react": "^19.2.4",
         "vscode-jsonrpc": "^8.2.1"
@@ -5219,7 +5303,7 @@
     },
     "packages/squad-sdk": {
       "name": "@bradygaster/squad-sdk",
-      "version": "0.8.24.2",
+      "version": "0.8.25",
       "license": "MIT",
       "dependencies": {
         "@github/copilot-sdk": "^0.1.32",