diff --git a/docs/public/bg.png b/docs/src/assets/bg.png
similarity index 100%
rename from docs/public/bg.png
rename to docs/src/assets/bg.png
diff --git a/docs/public/section-bg-1.png b/docs/src/assets/section-bg-1.png
similarity index 100%
rename from docs/public/section-bg-1.png
rename to docs/src/assets/section-bg-1.png
diff --git a/docs/public/section-bg-2.png b/docs/src/assets/section-bg-2.png
similarity index 100%
rename from docs/public/section-bg-2.png
rename to docs/src/assets/section-bg-2.png
diff --git a/docs/public/section-bg-3.png b/docs/src/assets/section-bg-3.png
similarity index 100%
rename from docs/public/section-bg-3.png
rename to docs/src/assets/section-bg-3.png
diff --git a/docs/src/components/FeatureVisual.astro b/docs/src/components/FeatureVisual.astro
new file mode 100644
index 00000000..3a958280
--- /dev/null
+++ b/docs/src/components/FeatureVisual.astro
@@ -0,0 +1,24 @@
+---
+import { getImage } from 'astro:assets';
+
+interface Props {
+  /** Image import from src/assets/ — processed by Astro's image pipeline */
+  image: ImageMetadata;
+  class?: string;
+}
+
+const { image, class: className } = Astro.props;
+
+const optimized = await getImage({
+  src: image,
+  format: 'webp',
+  quality: 80,
+});
+---
+
+<div
+  class:list={['feature-visual', className]}
+  style={`background-image: url('${optimized.src}');`}
+>
+  <slot />
+</div>
diff --git a/docs/src/components/Terminal.astro b/docs/src/components/Terminal.astro
index 28064bd1..9fc2b968 100644
--- a/docs/src/components/Terminal.astro
+++ b/docs/src/components/Terminal.astro
@@ -1,4 +1,7 @@
 ---
+import { getImage } from 'astro:assets';
+import bgImage from '../assets/bg.png';
+
 interface Props {
   title?: string;
   background?: 'custom';
@@ -6,11 +9,15 @@ interface Props {
 
 const { title = "Terminal", background } = Astro.props;
 const bgClass = background ? `bg-${background}` : '';
-const baseUrl = import.meta.env.BASE_URL;
-const base = baseUrl.endsWith('/') ? baseUrl : baseUrl + '/';
+
+let bgStyle = '';
+if (background) {
+  const optimized = await getImage({ src: bgImage, format: 'webp', quality: 80 });
+  bgStyle = `--bg-image: url('${optimized.src}');`;
+}
 ---
 
-<div class={`terminal-wrapper ${bgClass}`} style={background ? `--bg-image: url('${base}bg.png');` : ''}>
+<div class={`terminal-wrapper ${bgClass}`} style={bgStyle}>
   <div class="terminal">
     <div class="terminal-header">
       <div class="terminal-dots">
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
index 8aca048c..a1b47e7e 100644
--- a/docs/src/content/docs/index.mdx
+++ b/docs/src/content/docs/index.mdx
@@ -16,8 +16,10 @@ import CommandBox from '../../components/CommandBox.astro';
 import InstallSelector from '../../components/InstallSelector.astro';
 import Terminal from '../../components/Terminal.astro';
 import FeatureTerminal from '../../components/FeatureTerminal.astro';
-
-export const base = import.meta.env.BASE_URL.endsWith('/') ? import.meta.env.BASE_URL : import.meta.env.BASE_URL + '/';
+import FeatureVisual from '../../components/FeatureVisual.astro';
+import sectionBg1 from '../../assets/section-bg-1.png';
+import sectionBg2 from '../../assets/section-bg-2.png';
+import sectionBg3 from '../../assets/section-bg-3.png';
 
 <div class="hero-command">
 <InstallSelector options={[
@@ -44,7 +46,7 @@ export const base = import.meta.env.BASE_URL.endsWith('/') ? import.meta.env.BAS
       <p>No config files. No flags. The CLI reads your <code>.env</code>, detects your project from the codebase, and just works. Monorepos, multiple orgs, complex setups — all handled automatically.</p>
       <p>Stop memorizing project slugs and DSNs. Start typing commands that make sense.</p>
     </div>
-    <div class="feature-visual" style={`background-image: url('${base}section-bg-1.png');`}>
+    <FeatureVisual image={sectionBg1}>
       <FeatureTerminal title="Terminal">
         <div class="line"><span class="prompt">$</span> <span class="command">sentry issue list</span></div>
         <div class="line dimmed">Detected project: my-app (from .env)</div>
@@ -70,7 +72,7 @@ export const base = import.meta.env.BASE_URL.endsWith('/') ? import.meta.env.BAS
           <span class="col-count">34</span>
         </div>
       </FeatureTerminal>
-    </div>
+    </FeatureVisual>
   </div>
 </section>
 
@@ -81,7 +83,7 @@ export const base = import.meta.env.BASE_URL.endsWith('/') ? import.meta.env.BAS
       <p>Get AI-powered root cause analysis right in your terminal. Seer analyzes stack traces, related events, and your codebase to explain exactly what went wrong and why.</p>
       <p>Then run <code>sentry issue plan</code> to get a step-by-step fix you can apply immediately.</p>
     </div>
-    <div class="feature-visual" style={`background-image: url('${base}section-bg-2.png');`}>
+    <FeatureVisual image={sectionBg2}>
       <FeatureTerminal title="Terminal">
         <div class="line"><span class="prompt">$</span> <span class="command">sentry issue explain WQ</span></div>
         <div class="line dimmed">Analyzing MYAPP-WQ...</div>
@@ -92,7 +94,7 @@ export const base = import.meta.env.BASE_URL.endsWith('/') ? import.meta.env.BAS
         <div class="line dimmed">Affected: src/hooks/useUser.ts:42</div>
         <div class="line dimmed">Run `sentry issue plan` for a fix.</div>
       </FeatureTerminal>
-    </div>
+    </FeatureVisual>
   </div>
 </section>
 
@@ -103,7 +105,7 @@ export const base = import.meta.env.BASE_URL.endsWith('/') ? import.meta.env.BAS
       <p>Structured JSON output for scripts and pipelines. Open issues directly in your browser. Pipe to <code>jq</code>, <code>fzf</code>, or your favorite tools.</p>
       <p>Built for humans and AI agents alike — every command is predictable, composable, and automation-ready.</p>
     </div>
-    <div class="feature-visual" style={`background-image: url('${base}section-bg-3.png');`}>
+    <FeatureVisual image={sectionBg3}>
       <FeatureTerminal title="Terminal">
         <div class="line"><span class="prompt">$</span> <span class="command">sentry org list --json | jq '.[0]'</span></div>
         <div class="spacer"></div>
@@ -114,6 +116,6 @@ export const base = import.meta.env.BASE_URL.endsWith('/') ? import.meta.env.BAS
         <div class="line">  <span class="highlight">"members"</span>: 8</div>
         <div class="line">{"}"}</div>
       </FeatureTerminal>
-    </div>
+    </FeatureVisual>
   </div>
-</section>
+</section>
\ No newline at end of file