diff --git a/package.json b/package.json
index bc69f79..c28b3eb 100644
--- a/package.json
+++ b/package.json
@@ -40,7 +40,7 @@
   },
   "lint-staged": {
     "*.{js,jsx,ts,tsx}": "ultracite fix --type-aware",
-    "*.{json,jsonc,css}": "oxfmt"
+    "*.{json,jsonc,css,md,mdx}": "oxfmt"
   },
   "engines": {
     "node": ">=24.16.0"
diff --git a/packages/firebase-storage-kit/README.md b/packages/firebase-storage-kit/README.md
index 9bc5b44..16bf188 100644
--- a/packages/firebase-storage-kit/README.md
+++ b/packages/firebase-storage-kit/README.md
@@ -23,15 +23,35 @@ import { StorageManager } from "firebase-storage-kit";
 const storage = getStorage(app);
 const manager = new StorageManager(storage);
 
-const handle = manager.uploadFile(file, { path: `uploads/${file.name}` });
+const handle = manager.uploadFile(file, {
+  path: `uploads/${file.name}`,
+  validate: {
+    maxSizeBytes: 10 * 1024 * 1024,
+    allowedMimeTypes: ["image/jpeg", "image/png", "image/webp"],
+    allowedExtensions: [".jpg", ".jpeg", ".png", ".webp"],
+  },
+  retry: { maxRetries: 3 },
+});
 
 handle.on("progress", (upload) => {
   console.log(upload.progress);
 });
 
+handle.on("retry", ({ attempt, maxAttempts, delayMs }) => {
+  console.log(`Retry ${attempt}/${maxAttempts} in ${delayMs}ms`);
+});
+
 handle.on("success", (upload) => {
   console.log(upload.downloadURL);
 });
+
+handle.on("error", (upload) => {
+  if (upload.error?.name === "ValidationError") {
+    console.error("Invalid file:", upload.error.message);
+    return;
+  }
+  console.error("Upload failed:", upload.error?.message);
+});
 ```
 
 ### React
@@ -40,7 +60,15 @@ handle.on("success", (upload) => {
 import { useStorageManager, useUpload } from "firebase-storage-kit/react";
 
 const manager = useStorageManager(storage);
-const handle = manager.uploadFile(file, { path: `uploads/${file.name}` });
+const handle = manager.uploadFile(file, {
+  path: `uploads/${file.name}`,
+  validate: {
+    maxSizeBytes: 10 * 1024 * 1024,
+    allowedMimeTypes: ["image/jpeg", "image/png", "image/webp"],
+    allowedExtensions: [".jpg", ".jpeg", ".png", ".webp"],
+  },
+  retry: { maxRetries: 3 },
+});
 const upload = useUpload(handle);
 ```
 
@@ -49,6 +77,7 @@ See [React hooks](https://firebase-storage-kit.vercel.app/docs/guides/react-hook
 ## Learn more
 
 - [Single upload](https://firebase-storage-kit.vercel.app/docs/getting-started/single-upload)
+- [Retries](https://firebase-storage-kit.vercel.app/docs/guides/retries)
 - [Batch uploads](https://firebase-storage-kit.vercel.app/docs/guides/batch-uploads)
 - [API reference](https://firebase-storage-kit.vercel.app/docs/api/storage-manager)
 - [Troubleshooting](https://firebase-storage-kit.vercel.app/docs/troubleshooting)