diff --git a/.gitignore b/.gitignore
index b516d4dd9..ca210db9a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,7 +18,6 @@ Package.resolved
 .venv/
 .vscode
 _build
-docs/src
 # Sample tool-calling datasets generated by NVIDIA notebooks
 docs/notebooks/nvidia/tool_calling/sample_data/
 pyrightconfig.json
diff --git a/docs/src/components/HomepageFeatures/index.js b/docs/src/components/HomepageFeatures/index.js
new file mode 100644
index 000000000..78f410ba6
--- /dev/null
+++ b/docs/src/components/HomepageFeatures/index.js
@@ -0,0 +1,64 @@
+import React from 'react';
+import clsx from 'clsx';
+import styles from './styles.module.css';
+
+const FeatureList = [
+  {
+    title: 'Easy to Use',
+    Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,
+    description: (
+      <>
+        Docusaurus was designed from the ground up to be easily installed and
+        used to get your website up and running quickly.
+      </>
+    ),
+  },
+  {
+    title: 'Focus on What Matters',
+    Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default,
+    description: (
+      <>
+        Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
+        ahead and move your docs into the <code>docs</code> directory.
+      </>
+    ),
+  },
+  {
+    title: 'Powered by React',
+    Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
+    description: (
+      <>
+        Extend or customize your website layout by reusing React. Docusaurus can
+        be extended while reusing the same header and footer.
+      </>
+    ),
+  },
+];
+
+function Feature({Svg, title, description}) {
+  return (
+    <div className={clsx('col col--4')}>
+      <div className="text--center">
+        <Svg className={styles.featureSvg} role="img" />
+      </div>
+      <div className="text--center padding-horiz--md">
+        <h3>{title}</h3>
+        <p>{description}</p>
+      </div>
+    </div>
+  );
+}
+
+export default function HomepageFeatures() {
+  return (
+    <section className={styles.features}>
+      <div className="container">
+        <div className="row">
+          {FeatureList.map((props, idx) => (
+            <Feature key={idx} {...props} />
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}
diff --git a/docs/src/components/HomepageFeatures/styles.module.css b/docs/src/components/HomepageFeatures/styles.module.css
new file mode 100644
index 000000000..b248eb2e5
--- /dev/null
+++ b/docs/src/components/HomepageFeatures/styles.module.css
@@ -0,0 +1,11 @@
+.features {
+  display: flex;
+  align-items: center;
+  padding: 2rem 0;
+  width: 100%;
+}
+
+.featureSvg {
+  height: 200px;
+  width: 200px;
+}
diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css
new file mode 100644
index 000000000..0e4d95b9b
--- /dev/null
+++ b/docs/src/css/custom.css
@@ -0,0 +1,191 @@
+/**
+ * Any CSS included here will be global. The classic template
+ * bundles Infima by default. Infima is a CSS framework designed to
+ * work well for content-centric websites.
+ */
+
+/* You can override the default Infima variables here. */
+:root {
+  /* Llama Stack Original Theme - Based on llamastack.github.io */
+  --ifm-color-primary: #4a4a68;
+  --ifm-color-primary-dark: #3a3a52;
+  --ifm-color-primary-darker: #332735;
+  --ifm-color-primary-darkest: #2b2129;
+  --ifm-color-primary-light: #5a5a7e;
+  --ifm-color-primary-lighter: #6a6a94;
+  --ifm-color-primary-lightest: #8080aa;
+
+  /* Additional theme colors */
+  --ifm-color-secondary: #1b263c;
+  --ifm-color-info: #2980b9;
+  --ifm-color-success: #16a085;
+  --ifm-color-warning: #f39c12;
+  --ifm-color-danger: #e74c3c;
+
+  /* Background colors */
+  --ifm-background-color: #ffffff;
+  --ifm-background-surface-color: #f8f9fa;
+
+  /* Code and syntax highlighting */
+  --ifm-code-font-size: 95%;
+  --ifm-pre-background: #1b263c;
+  --ifm-pre-color: #e1e5e9;
+  --docusaurus-highlighted-code-line-bg: rgba(51, 39, 53, 0.1);
+
+  /* Link colors */
+  --ifm-link-color: var(--ifm-color-primary);
+  --ifm-link-hover-color: var(--ifm-color-primary-darker);
+
+  /* Navbar */
+  --ifm-navbar-background-color: rgba(255, 255, 255, 0.95);
+  --ifm-navbar-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+
+  /* Hero section gradient - matching original theme */
+  --hero-gradient: linear-gradient(90deg, #332735 0%, #1b263c 100%);
+
+  /* OpenAPI method colors */
+  --openapi-code-blue: #2980b9;
+  --openapi-code-green: #16a085;
+  --openapi-code-orange: #f39c12;
+  --openapi-code-red: #e74c3c;
+  --openapi-code-purple: #332735;
+}
+
+/* For readability concerns, you should choose a lighter palette in dark mode. */
+[data-theme='dark'] {
+  /* Dark theme primary colors - lighter versions of original theme */
+  --ifm-color-primary: #8080aa;
+  --ifm-color-primary-dark: #6a6a94;
+  --ifm-color-primary-darker: #5a5a7e;
+  --ifm-color-primary-darkest: #4a4a68;
+  --ifm-color-primary-light: #9090ba;
+  --ifm-color-primary-lighter: #a0a0ca;
+  --ifm-color-primary-lightest: #b0b0da;
+
+  /* Dark theme background colors */
+  --ifm-background-color: #1a1a1a;
+  --ifm-background-surface-color: #2a2a2a;
+
+  /* Dark theme navbar */
+  --ifm-navbar-background-color: rgba(26, 26, 26, 0.95);
+
+  /* Dark theme code highlighting */
+  --docusaurus-highlighted-code-line-bg: rgba(51, 39, 53, 0.3);
+
+  /* Dark theme text colors */
+  --ifm-font-color-base: #e1e5e9;
+  --ifm-font-color-secondary: #a0a6ac;
+}
+
+/* Sidebar Method labels */
+.api-method>.menu__link {
+  align-items: center;
+  justify-content: start;
+}
+
+.api-method>.menu__link::before {
+  width: 50px;
+  height: 20px;
+  font-size: 12px;
+  line-height: 20px;
+  text-transform: uppercase;
+  font-weight: 600;
+  border-radius: 0.25rem;
+  border: 1px solid;
+  margin-right: var(--ifm-spacing-horizontal);
+  text-align: center;
+  flex-shrink: 0;
+  border-color: transparent;
+  color: white;
+}
+
+.get>.menu__link::before {
+  content: "get";
+  background-color: var(--ifm-color-primary);
+}
+
+.put>.menu__link::before {
+  content: "put";
+  background-color: var(--openapi-code-blue);
+}
+
+.post>.menu__link::before {
+  content: "post";
+  background-color: var(--openapi-code-green);
+}
+
+.delete>.menu__link::before {
+  content: "del";
+  background-color: var(--openapi-code-red);
+}
+
+.patch>.menu__link::before {
+  content: "patch";
+  background-color: var(--openapi-code-orange);
+}
+
+.footer--dark {
+  --ifm-footer-link-color: #ffffff;
+  --ifm-footer-title-color: #ffffff;
+}
+
+.footer--dark .footer__link-item {
+  color: #ffffff;
+}
+
+.footer--dark .footer__title {
+  color: #ffffff;
+}
+
+/* OpenAPI theme fixes for light mode readability */
+/* Version badge fixes */
+.openapi__version-badge,
+.theme-doc-version-badge,
+[class*="version-badge"],
+[class*="versionBadge"] {
+  background-color: #ffffff !important;
+  color: #333333 !important;
+  border: 1px solid #d1d5db !important;
+}
+
+/* OpenAPI method badges in light mode */
+.openapi__method-badge,
+[class*="method-badge"] {
+  color: #ffffff !important;
+}
+
+/* Button fixes for light mode */
+.openapi__button,
+.theme-api-docs-demo-panel button,
+[class*="api-docs"] button,
+button[class*="button"],
+.openapi-explorer__response-schema button,
+.openapi-tabs__operation button {
+  color: #ffffff !important;
+}
+
+.openapi__button:hover,
+.theme-api-docs-demo-panel button:hover,
+[class*="api-docs"] button:hover,
+button[class*="button"]:hover,
+.openapi-explorer__response-schema button:hover,
+.openapi-tabs__operation button:hover {
+  color: #ffffff !important;
+}
+
+/* Navigation buttons (Next/Previous) */
+.pagination-nav__link,
+.pagination-nav__label {
+  color: #333333 !important;
+}
+
+.pagination-nav__link--next,
+.pagination-nav__link--prev {
+  background-color: #ffffff !important;
+  border: 1px solid #d1d5db !important;
+}
+
+.pagination-nav__link--next:hover,
+.pagination-nav__link--prev:hover {
+  background-color: #f3f4f6 !important;
+}
diff --git a/docs/src/pages/index.js b/docs/src/pages/index.js
new file mode 100644
index 000000000..c97959d77
--- /dev/null
+++ b/docs/src/pages/index.js
@@ -0,0 +1,163 @@
+import React from 'react';
+import clsx from 'clsx';
+import Layout from '@theme/Layout';
+import Link from '@docusaurus/Link';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import styles from './index.module.css';
+
+function HomepageHeader() {
+  const {siteConfig} = useDocusaurusContext();
+  return (
+    <header className={clsx('hero hero--primary', styles.heroBanner)}>
+      <div className="container">
+        <div className={styles.heroContent}>
+          <h1 className={styles.heroTitle}>Build AI Applications with Llama Stack</h1>
+          <p className={styles.heroSubtitle}>
+            Unified APIs for Inference, RAG, Agents, Tools, Safety, and Telemetry
+          </p>
+          <div className={styles.buttons}>
+            <Link
+              className={clsx('button button--primary button--lg', styles.getStartedButton)}
+              to="/docs/getting_started/quickstart">
+              🚀 Get Started
+            </Link>
+            <Link
+              className={clsx('button button--primary button--lg', styles.apiButton)}
+              to="/docs/api/llama-stack-specification">
+              📚 API Reference
+            </Link>
+          </div>
+        </div>
+      </div>
+    </header>
+  );
+}
+
+function QuickStart() {
+  return (
+    <section className={styles.quickStart}>
+      <div className="container">
+        <div className="row">
+          <div className="col col--6">
+            <h2 className={styles.sectionTitle}>Quick Start</h2>
+            <p className={styles.sectionDescription}>
+              Get up and running with Llama Stack in just a few commands. Build your first RAG application locally.
+            </p>
+            <div className={styles.codeBlock}>
+              <pre><code>{`# Install uv and start Ollama
+ollama run llama3.2:3b --keepalive 60m
+
+# Run Llama Stack server
+OLLAMA_URL=http://localhost:11434 \\
+  uv run --with llama-stack \\
+  llama stack build --distro starter \\
+  --image-type venv --run
+
+# Try the Python SDK
+from llama_stack_client import LlamaStackClient
+
+client = LlamaStackClient(
+  base_url="http://localhost:8321"
+)
+
+response = client.inference.chat_completion(
+  model="Llama3.2-3B-Instruct",
+  messages=[{
+    "role": "user",
+    "content": "What is machine learning?"
+  }]
+)`}</code></pre>
+            </div>
+          </div>
+          <div className="col col--6">
+            <h2 className={styles.sectionTitle}>Why Llama Stack?</h2>
+            <div className={styles.features}>
+              <div className={styles.feature}>
+                <div className={styles.featureIcon}>🔗</div>
+                <div>
+                  <h4>Unified APIs</h4>
+                  <p>One consistent interface for all your AI needs - inference, safety, agents, and more.</p>
+                </div>
+              </div>
+              <div className={styles.feature}>
+                <div className={styles.featureIcon}>🔄</div>
+                <div>
+                  <h4>Provider Flexibility</h4>
+                  <p>Swap between providers without code changes. Start local, deploy anywhere.</p>
+                </div>
+              </div>
+              <div className={styles.feature}>
+                <div className={styles.featureIcon}>🛡️</div>
+                <div>
+                  <h4>Production Ready</h4>
+                  <p>Built-in safety, monitoring, and evaluation tools for enterprise applications.</p>
+                </div>
+              </div>
+              <div className={styles.feature}>
+                <div className={styles.featureIcon}>📱</div>
+                <div>
+                  <h4>Multi-Platform</h4>
+                  <p>SDKs for Python, Node.js, iOS, Android, and REST APIs for any language.</p>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function CommunityLinks() {
+  return (
+    <section className={styles.community}>
+      <div className="container">
+        <div className={styles.communityContent}>
+          <h2 className={styles.sectionTitle}>Join the Community</h2>
+          <p className={styles.sectionDescription}>
+            Connect with developers building the future of AI applications
+          </p>
+          <div className={styles.communityLinks}>
+            <a
+              href="https://github.com/llamastack/llama-stack"
+              className={clsx('button button--outline button--lg', styles.communityButton)}
+              target="_blank"
+              rel="noopener noreferrer">
+              <span className={styles.communityIcon}>⭐</span>
+              Star on GitHub
+            </a>
+            <a
+              href="https://discord.gg/llama-stack"
+              className={clsx('button button--outline button--lg', styles.communityButton)}
+              target="_blank"
+              rel="noopener noreferrer">
+              <span className={styles.communityIcon}>💬</span>
+              Join Discord
+            </a>
+            <Link
+              to="/docs/"
+              className={clsx('button button--outline button--lg', styles.communityButton)}>
+              <span className={styles.communityIcon}>📚</span>
+              Read Docs
+            </Link>
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}
+
+export default function Home() {
+  const {siteConfig} = useDocusaurusContext();
+  return (
+    <Layout
+      title="Build AI Applications"
+      description="The open-source framework for building generative AI applications with unified APIs for Inference, RAG, Agents, Tools, Safety, and Telemetry.">
+      <HomepageHeader />
+      <main>
+        <QuickStart />
+        <CommunityLinks />
+      </main>
+    </Layout>
+  );
+}
diff --git a/docs/src/pages/index.module.css b/docs/src/pages/index.module.css
new file mode 100644
index 000000000..c3681653b
--- /dev/null
+++ b/docs/src/pages/index.module.css
@@ -0,0 +1,283 @@
+/**
+ * CSS files with the .module.css suffix will be treated as CSS modules
+ * and scoped locally.
+ */
+
+.heroBanner {
+  padding: 4rem 0;
+  text-align: center;
+  position: relative;
+  overflow: hidden;
+  background: var(--hero-gradient);
+  color: white;
+  display: flex;
+  align-items: center;
+}
+
+.heroBanner::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: radial-gradient(circle at 30% 20%, rgba(255, 255, 255, 0.1) 0%, transparent 50%),
+              radial-gradient(circle at 70% 80%, rgba(255, 255, 255, 0.05) 0%, transparent 50%);
+  pointer-events: none;
+}
+
+.heroContent {
+  max-width: 800px;
+  margin: 0 auto;
+}
+
+.heroLogo {
+  height: 48px;
+  width: auto;
+  margin-bottom: 1.5rem;
+}
+
+.heroTitle {
+  font-size: 2.8rem;
+  font-weight: 700;
+  margin-bottom: 1rem;
+  line-height: 1.2;
+}
+
+.heroSubtitle {
+  font-size: 1.1rem;
+  font-weight: 400;
+  margin-bottom: 2rem;
+  opacity: 0.9;
+  line-height: 1.5;
+  max-width: 600px;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.buttons {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 1rem;
+}
+
+.heroBanner .getStartedButton {
+  background: white;
+  color: #332735;
+  border: 2px solid white;
+  font-weight: 600;
+  transition: all 0.3s ease;
+}
+
+.heroBanner .getStartedButton:hover {
+  background: rgba(255, 255, 255, 0.9);
+  color: #2b2129;
+  border-color: rgba(255, 255, 255, 0.9);
+  transform: translateY(-2px);
+  box-shadow: 0 8px 25px rgba(0, 0, 0, 0.15);
+}
+
+.heroBanner .apiButton {
+  background: transparent;
+  color: white;
+  border: 2px solid white;
+  font-weight: 600;
+  transition: all 0.3s ease;
+}
+
+.heroBanner .apiButton:hover {
+  background: white;
+  border-color: white;
+  color: #332735;
+  transform: translateY(-2px);
+}
+
+/* Quick Start Section */
+.quickStart {
+  padding: 4rem 0;
+  background: var(--ifm-background-color);
+}
+
+.sectionTitle {
+  font-size: 2rem;
+  font-weight: 600;
+  margin-bottom: 0.75rem;
+  color: var(--ifm-color-emphasis-800);
+}
+
+.sectionDescription {
+  font-size: 1rem;
+  color: var(--ifm-color-emphasis-600);
+  margin-bottom: 1.5rem;
+  line-height: 1.5;
+}
+
+.codeBlock {
+  background: var(--ifm-color-gray-900);
+  border-radius: 8px;
+  padding: 1.5rem;
+  margin-top: 1.5rem;
+  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
+}
+
+.codeBlock pre {
+  margin: 0;
+  padding: 0;
+  background: none;
+  border: none;
+}
+
+.codeBlock code {
+  color: var(--ifm-color-gray-100);
+  font-family: 'Fira Code', 'Consolas', 'Monaco', monospace;
+  font-size: 0.9rem;
+  line-height: 1.6;
+}
+
+/* Features */
+.features {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  margin-top: 1.5rem;
+}
+
+.feature {
+  display: flex;
+  align-items: flex-start;
+  gap: 1rem;
+  padding: 1rem;
+  border-radius: 8px;
+  background: var(--ifm-color-gray-50);
+  border: 1px solid var(--ifm-color-gray-200);
+  transition: all 0.2s ease;
+}
+
+.feature:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 8px 25px rgba(0, 0, 0, 0.1);
+  border-color: var(--ifm-color-primary-lighter);
+}
+
+.featureIcon {
+  font-size: 2rem;
+  width: 3rem;
+  height: 3rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--ifm-color-primary-lightest);
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+.feature h4 {
+  margin: 0 0 0.5rem 0;
+  font-size: 1.1rem;
+  font-weight: 600;
+  color: var(--ifm-color-emphasis-800);
+}
+
+.feature p {
+  margin: 0;
+  color: var(--ifm-color-emphasis-600);
+  line-height: 1.5;
+}
+
+/* Community Section */
+.community {
+  padding: 3rem 0;
+  background: var(--ifm-color-gray-50);
+  border-top: 1px solid var(--ifm-color-gray-200);
+}
+
+.communityContent {
+  text-align: center;
+  max-width: 600px;
+  margin: 0 auto;
+}
+
+.communityLinks {
+  display: flex;
+  justify-content: center;
+  gap: 1rem;
+  margin-top: 2rem;
+}
+
+.communityButton {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-weight: 600;
+  transition: all 0.3s ease;
+}
+
+.communityButton:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 8px 25px rgba(0, 0, 0, 0.1);
+}
+
+.communityIcon {
+  font-size: 1.2rem;
+}
+
+/* Responsive Design */
+@media screen and (max-width: 996px) {
+  .heroBanner {
+    padding: 3rem 2rem;
+  }
+
+  .heroTitle {
+    font-size: 2.2rem;
+  }
+
+  .heroSubtitle {
+    font-size: 1rem;
+  }
+
+  .buttons {
+    flex-direction: column;
+    gap: 1rem;
+  }
+
+  .quickStart {
+    padding: 3rem 0;
+  }
+
+  .sectionTitle {
+    font-size: 1.75rem;
+  }
+
+  .communityLinks {
+    flex-direction: column;
+    align-items: center;
+  }
+
+  .communityButton {
+    width: 200px;
+    justify-content: center;
+  }
+}
+
+@media screen and (max-width: 768px) {
+  .heroLogo {
+    height: 40px;
+  }
+
+  .heroTitle {
+    font-size: 1.8rem;
+  }
+
+  .codeBlock {
+    padding: 1rem;
+  }
+
+  .codeBlock code {
+    font-size: 0.8rem;
+  }
+
+  .feature {
+    padding: 0.75rem;
+  }
+}
diff --git a/docs/src/pages/markdown-page.md b/docs/src/pages/markdown-page.md
new file mode 100644
index 000000000..9756c5b66
--- /dev/null
+++ b/docs/src/pages/markdown-page.md
@@ -0,0 +1,7 @@
+---
+title: Markdown page example
+---
+
+# Markdown page example
+
+You don't need React to write simple standalone pages.