diff --git a/.github/banner.png b/.github/banner.png
new file mode 100644
index 0000000..c6b6bcd
Binary files /dev/null and b/.github/banner.png differ
diff --git a/.github/banner.svg b/.github/banner.svg
new file mode 100644
index 0000000..14566dc
--- /dev/null
+++ b/.github/banner.svg
@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="320" viewBox="0 0 1280 320" fill="none" role="img" aria-label="@smooai/file — Trust the bytes, not the extension">
+  <defs>
+    <linearGradient id="mark" x1="22" y1="22" x2="113" y2="113" gradientUnits="userSpaceOnUse">
+      <stop offset=".3" stop-color="#f49f0a"/><stop offset=".79" stop-color="#fb7a4d"/><stop offset="1" stop-color="#ff6b6c"/>
+    </linearGradient>
+    <linearGradient id="word" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#ffffff"/><stop offset="1" stop-color="#cdd6e4"/></linearGradient>
+    <linearGradient id="rule" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#f49f0a"/><stop offset=".55" stop-color="#ff6b6c"/><stop offset="1" stop-color="#00a6a6"/></linearGradient>
+    <radialGradient id="gW" cx="0.16" cy="0.42" r="0.5"><stop offset="0" stop-color="#ff6b6c" stop-opacity="0.55"/><stop offset="1" stop-color="#ff6b6c" stop-opacity="0"/></radialGradient>
+    <radialGradient id="gT" cx="0.92" cy="0.85" r="0.6"><stop offset="0" stop-color="#00a6a6" stop-opacity="0.40"/><stop offset="1" stop-color="#00a6a6" stop-opacity="0"/></radialGradient>
+    <radialGradient id="gO" cx="0.30" cy="0.10" r="0.55"><stop offset="0" stop-color="#f49f0a" stop-opacity="0.35"/><stop offset="1" stop-color="#f49f0a" stop-opacity="0"/></radialGradient>
+    <filter id="soft" x="-30%" y="-30%" width="160%" height="160%"><feGaussianBlur stdDeviation="7"/></filter>
+    <pattern id="grid" width="34" height="34" patternUnits="userSpaceOnUse"><path d="M34 0H0V34" fill="none" stroke="#9fb3c8" stroke-opacity="0.06" stroke-width="1"/></pattern>
+  </defs>
+  <rect width="1280" height="320" rx="20" fill="#020618"/>
+  <rect width="1280" height="320" rx="20" fill="url(#grid)"/>
+  <rect width="1280" height="320" rx="20" fill="url(#gW)"/>
+  <rect width="1280" height="320" rx="20" fill="url(#gT)"/>
+  <rect width="1280" height="320" rx="20" fill="url(#gO)"/>
+  <rect x="1" y="1" width="1278" height="318" rx="19" fill="none" stroke="#ffffff" stroke-opacity="0.08"/>
+  <g transform="translate(96,86) scale(1.07)">
+    <path d="M45.63,15.38c-12.39,5.21-22.54,14.64-28.65,26.61-6.12,11.97-7.8,25.72-4.77,38.81,3.04,13.09,10.6,24.69,21.36,32.75,10.76,8.06,24.02,12.05,37.44,11.28,13.42-.77,26.13-6.26,35.9-15.5,9.76-9.24,15.95-21.63,17.46-34.99,1.51-13.36-1.74-26.82-9.19-38.01-1.07-1.61-.64-3.78.97-4.85,1.61-1.07,3.78-.64,4.85.97,8.36,12.56,12.02,27.68,10.32,42.67-1.7,15-8.64,28.91-19.61,39.28-10.96,10.37-25.24,16.54-40.31,17.4-15.07.87-29.96-3.62-42.04-12.66-12.08-9.05-20.58-22.07-23.99-36.77-3.41-14.7-1.51-30.14,5.35-43.58,6.87-13.44,18.26-24.02,32.17-29.87,13.91-5.85,29.44-6.6,43.85-2.11,1.85.57,2.88,2.54,2.3,4.38-.57,1.85-2.54,2.88-4.38,2.3-12.83-4-26.67-3.33-39.06,1.88ZM108.73,20.17c0,2.07-1.68,3.75-3.75,3.75s-3.75-1.68-3.75-3.75,1.68-3.75,3.75-3.75,3.75,1.68,3.75,3.75ZM61.98,60.34c0,1.91,2.39,2.56,7.69,3.88,3.89.97,6.6,2.18,8.15,3.63,1.53,1.45,2.29,3.53,2.29,6.25,0,3.57-1.03,6.26-3.11,8.08-2.07,1.82-5.09,2.73-9.09,2.73h-9.6c-1.97,0-3.57-1.6-3.59-3.57-.01-1.99,1.6-3.61,3.59-3.61h9.41c3.15-.12,4.79-.95,4.91-2.47,0-1.3-1.03-2.21-3.07-2.73-6.91-1.72-11.11-3.44-12.6-5.15-1.48-1.71-2.23-3.77-2.23-6.19,0-6.59,3.2-9.85,9.59-9.8h10.77c1.99,0,3.6,1.61,3.6,3.59s-1.61,3.59-3.6,3.59h-9.69c-1.83,0-3.43.06-3.43,1.77Z" fill="url(#mark)" opacity="0.55" filter="url(#soft)"/>
+    <path d="M45.63,15.38c-12.39,5.21-22.54,14.64-28.65,26.61-6.12,11.97-7.8,25.72-4.77,38.81,3.04,13.09,10.6,24.69,21.36,32.75,10.76,8.06,24.02,12.05,37.44,11.28,13.42-.77,26.13-6.26,35.9-15.5,9.76-9.24,15.95-21.63,17.46-34.99,1.51-13.36-1.74-26.82-9.19-38.01-1.07-1.61-.64-3.78.97-4.85,1.61-1.07,3.78-.64,4.85.97,8.36,12.56,12.02,27.68,10.32,42.67-1.7,15-8.64,28.91-19.61,39.28-10.96,10.37-25.24,16.54-40.31,17.4-15.07.87-29.96-3.62-42.04-12.66-12.08-9.05-20.58-22.07-23.99-36.77-3.41-14.7-1.51-30.14,5.35-43.58,6.87-13.44,18.26-24.02,32.17-29.87,13.91-5.85,29.44-6.6,43.85-2.11,1.85.57,2.88,2.54,2.3,4.38-.57,1.85-2.54,2.88-4.38,2.3-12.83-4-26.67-3.33-39.06,1.88ZM108.73,20.17c0,2.07-1.68,3.75-3.75,3.75s-3.75-1.68-3.75-3.75,1.68-3.75,3.75-3.75,3.75,1.68,3.75,3.75ZM61.98,60.34c0,1.91,2.39,2.56,7.69,3.88,3.89.97,6.6,2.18,8.15,3.63,1.53,1.45,2.29,3.53,2.29,6.25,0,3.57-1.03,6.26-3.11,8.08-2.07,1.82-5.09,2.73-9.09,2.73h-9.6c-1.97,0-3.57-1.6-3.59-3.57-.01-1.99,1.6-3.61,3.59-3.61h9.41c3.15-.12,4.79-.95,4.91-2.47,0-1.3-1.03-2.21-3.07-2.73-6.91-1.72-11.11-3.44-12.6-5.15-1.48-1.71-2.23-3.77-2.23-6.19,0-6.59,3.2-9.85,9.59-9.8h10.77c1.99,0,3.6,1.61,3.6,3.59s-1.61,3.59-3.6,3.59h-9.69c-1.83,0-3.43.06-3.43,1.77Z" fill="url(#mark)"/>
+  </g>
+  <text x="300" y="150" font-family="'Helvetica Neue',Arial,sans-serif" font-size="84" font-weight="800" letter-spacing="-2" fill="url(#word)">@smooai/file</text>
+  <rect x="302" y="178" width="150" height="5" rx="2.5" fill="url(#rule)"/>
+  <text x="300" y="230" font-family="'Helvetica Neue',Arial,sans-serif" font-size="30" font-weight="500" fill="#aab6c6">Trust the bytes, not the extension</text>
+  <text x="300" y="274" font-family="'Helvetica Neue',Arial,sans-serif" font-size="20" font-weight="600" letter-spacing="3" fill="#5a6b80">SMOO AI · AI BUILT INTO EVERY PRODUCT</text>
+</svg>
\ No newline at end of file
diff --git a/README.md b/README.md
index 6251ca9..923416d 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,17 @@
 <a name="readme-top"></a>
 
 <p align="center">
-  <a href="https://smoo.ai"><img src="https://smoo.ai/images/logo/logo.svg" alt="Smoo AI" width="220" /></a>
+  <a href="https://smoo.ai"><img src=".github/banner.png" alt="@smooai/file — Trust the bytes, not the extension" width="100%" /></a>
 </p>
 
-<h1 align="center">@smooai/file</h1>
-
 <p align="center">
-  <strong>File operations that don't lie — magic-byte MIME detection, built-in validation, and one-call presigned S3 uploads, all stream-first.</strong>
+  <a href="https://www.npmjs.com/package/@smooai/file"><img src="https://img.shields.io/npm/v/@smooai/file?style=for-the-badge&color=00A6A6&label=npm&logo=npm&logoColor=white&labelColor=020618" alt="npm"></a>
+  <a href="https://smoo.ai"><img src="https://img.shields.io/badge/Smoo_AI-platform-00A6A6?style=for-the-badge&labelColor=020618" alt="Smoo AI"></a>
+  <img src="https://img.shields.io/badge/license-MIT-F49F0A?style=for-the-badge&labelColor=020618" alt="license">
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@smooai/file"><img src="https://img.shields.io/npm/v/@smooai/file?style=flat-square&color=00A6A6&label=npm" alt="npm"></a>
   <a href="https://www.npmjs.com/package/@smooai/file"><img src="https://img.shields.io/npm/dw/@smooai/file?style=flat-square&color=F49F0A&label=downloads" alt="downloads"></a>
-  <img src="https://img.shields.io/badge/Smoo_AI-platform-00A6A6?style=flat-square" alt="Smoo AI">
-  <img src="https://img.shields.io/badge/license-MIT-F49F0A?style=flat-square" alt="license">
   <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
   <img src="https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python">
   <img src="https://img.shields.io/badge/Rust-000000?style=flat-square&logo=rust&logoColor=white" alt="Rust">
@@ -23,10 +20,7 @@
 </p>
 
 <p align="center">
-  <a href="#features">Features</a> ·
-  <a href="#install">Install</a> ·
-  <a href="#usage">Usage</a> ·
-  <a href="#part-of-smoo-ai">Platform</a>
+  <a href="#-features"><b>Features</b></a> &nbsp;·&nbsp; <a href="#-install"><b>Install</b></a> &nbsp;·&nbsp; <a href="#-usage"><b>Usage</b></a> &nbsp;·&nbsp; <a href="#-part-of-smoo-ai"><b>Platform</b></a>
 </p>
 
 ---
@@ -301,14 +295,10 @@ const url = await File.createPresignedUploadUrl({
 
 ## 🧩 Part of Smoo AI <a name="part-of-smoo-ai"></a>
 
-@smooai/file is part of the [Smoo AI](https://smoo.ai) platform — an AI-powered business platform with AI built into every product. It's one of a small family of open-source packages we maintain to keep our own stack honest. Use them in your stack, or take them as a reference for how we build.
-
-- [@smooai/fetch](https://github.com/SmooAI/fetch) — typed HTTP with retries and structured errors
-- [@smooai/logger](https://github.com/SmooAI/logger) — contextual structured logging
-- [@smooai/config](https://github.com/SmooAI/config) — typed config, secrets, and feature flags
-- [smooth](https://github.com/SmooAI/smooth) — the agent orchestration toolkit
+`@smooai/file` is built and open-sourced by **[Smoo AI](https://smoo.ai)** — the AI-powered business platform with AI built into every product: CRM, customer support, campaigns, field service, observability, and developer tools.
 
-Browse everything at [smoo.ai/open-source](https://smoo.ai/open-source) and [github.com/SmooAI](https://github.com/SmooAI).
+- 🧰 **More open source from Smoo AI** — [smoo.ai/open-source](https://smoo.ai/open-source)
+- 🧩 **Sibling packages** — [@smooai/fetch](https://github.com/SmooAI/fetch), [@smooai/logger](https://github.com/SmooAI/logger), [@smooai/config](https://github.com/SmooAI/config), [smooth](https://github.com/SmooAI/smooth)
 
 ## 🤝 Contributing <a name="contributing"></a>