docs(media): add standalone package guide

packages/media/docs/en-US/advanced/storage-adapter.mdx

@@ -0,0 +1,41 @@
+---
+title: Storage adapter
+description: Connect queries, uploads, mutations, URL resolution, and pagination to product infrastructure.
+order: 20
+toc:
+  - id: implement-the-contract
+    title: Implement the contract
+  - id: separate-display-and-reference-urls
+    title: Separate display and reference URLs
+  - id: preserve-query-semantics
+    title: Preserve query semantics
+---
+
+## Implement the contract {#implement-the-contract}
+
+`MediaAdapter` is the package's complete persistence boundary. Implement its asset queries, folder operations, uploads, updates, and deletes with the product's storage service.
+
+```ts
+import type { MediaAdapter } from "@workspace/media"
+
+export const mediaAdapter: MediaAdapter = {
+  listAssets: (query) => api.media.list(query),
+  listFolders: () => api.media.listFolders(),
+  upload: (input) => api.media.upload(input),
+  createFolder: (input) => api.media.createFolder(input),
+  updateFolder: (input) => api.media.updateFolder(input),
+  deleteFolder: (id) => api.media.deleteFolder(id),
+  moveAsset: (id, folderId) => api.media.move(id, folderId),
+  renameAsset: (id, name) => api.media.rename(id, name),
+  updateFavorite: (id, favorite) => api.media.favorite(id, favorite),
+  deleteAsset: (id) => api.media.delete(id),
+}
+```
+
+## Separate display and reference URLs {#separate-display-and-reference-urls}
+
+Use `resolveUrl` for short-lived signed URLs or image transformations used while rendering. Use `resolveReference` for the value returned by the picker and stored in another document. When `resolveReference` is absent, images use `defaultMediaReference`, which preserves intrinsic dimensions in the URL.
+
+## Preserve query semantics {#preserve-query-semantics}
+
+Treat `MediaAssetQuery` as an immutable request. Apply `allowedKinds`, `filter`, `folder`, and `keyword` before pagination, then return `hasNextPage` based on the filtered result. This keeps desktop and mobile filters consistent.

packages/media/docs/en-US/examples/asset-picker.mdx

@@ -0,0 +1,34 @@
+---
+title: Asset picker
+description: Reuse the media library as a controlled single- or multiple-selection dialog.
+order: 30
+toc:
+  - id: open-the-picker
+    title: Open the picker
+  - id: constrain-selection
+    title: Constrain selection
+  - id: consume-results
+    title: Consume results
+---
+
+## Open the picker {#open-the-picker}
+
+`MediaPickerDialog` reuses the same adapter and folder model as the full library:
+
+```tsx
+import { MediaPickerDialog } from "@workspace/media"
+
+;<MediaPickerDialog
+  open={open}
+  onOpenChange={setOpen}
+  onConfirm={(assets) => editor.insertImages(assets)}
+/>
+```
+
+## Constrain selection {#constrain-selection}
+
+Pass `allowedKinds={["image"]}` for an image-only workflow. The dialog selects one asset by default; pass `multiple` when the consumer accepts several assets, and provide `initialSelection` when editing an existing value.
+
+## Consume results {#consume-results}
+
+The confirmation callback receives complete `MediaAsset` records. Store the adapter-provided reference rather than a temporary preview URL when the result must survive signed-URL expiration.

packages/media/docs/en-US/guide/setup.mdx

@@ -0,0 +1,48 @@
+---
+title: Installation and setup
+description: Add Media, register its catalog, and connect the storage adapter.
+order: 10
+toc:
+  - id: add-the-package
+    title: Add the package
+  - id: register-styles-and-catalogs
+    title: Register styles and catalogs
+  - id: provide-media
+    title: Provide media
+---
+
+## Add the package {#add-the-package}
+
+Add Media to the consuming application:
+
+```json
+{
+  "dependencies": {
+    "@workspace/media": "workspace:*"
+  }
+}
+```
+
+## Register styles and catalogs {#register-styles-and-catalogs}
+
+Import the stylesheet once so Tailwind includes utilities used by the package:
+
+```css
+@import "@workspace/media/globals.css";
+```
+
+Add `@workspace/media/locales/{locale}` to the application's internationalization catalog sources.
+
+## Provide media {#provide-media}
+
+Mount the adapter once around every media surface that should share storage behavior and notifications:
+
+```tsx
+import { MediaLibrary, MediaProvider } from "@workspace/media"
+
+;<MediaProvider adapter={mediaAdapter} notify={showNotice}>
+  <MediaLibrary />
+</MediaProvider>
+```
+
+The optional `notify` callback turns operation results into the application's toast or notification system.

packages/media/docs/en-US/overview.mdx

@@ -0,0 +1,31 @@
+---
+title: Overview
+description: Understand the Media package, its storage boundary, and the workflows it owns.
+order: 1
+toc:
+  - id: package-role
+    title: Package role
+  - id: capabilities
+    title: Capabilities
+  - id: design-boundary
+    title: Design boundary
+---
+
+## Package role {#package-role}
+
+`@workspace/media` provides reusable media-library and asset-picker surfaces. The host application supplies persistence through `MediaAdapter`; Media owns browsing, filtering, pagination, uploads, folders, selection, and asset actions.
+
+## Capabilities {#capabilities}
+
+- Browse images and videos with search, filters, folders, favorites, and pagination.
+- Upload to local or cloud storage targets exposed by the adapter.
+- Create, rename, nest, and delete organizational folders.
+- Select one or multiple assets through `MediaPickerDialog`.
+- Resolve display URLs and stable references independently.
+- Ship `en-US` and `zh-Hans` message catalogs.
+
+## Design boundary {#design-boundary}
+
+Media does not choose an API, database, object store, CDN, or signing strategy. The application implements those decisions behind `MediaAdapter` and can replace them without changing the interface components.
+
+> Folders classify assets inside the library. They do not need to mirror object-storage paths or change public URLs.