feat(docs): add bilingual package documentation site

packages/search/docs/en-US/advanced/adapter-and-pagination.mdx

@@ -0,0 +1,42 @@
+---
+title: Adapter and pagination
+description: Implement cancellable search requests and return mergeable grouped pages.
+order: 20
+toc:
+  - id: implement-adapter
+    title: Implement the adapter
+  - id: group-results
+    title: Group results
+  - id: paginate
+    title: Paginate
+---
+
+## Implement the adapter {#implement-adapter}
+
+`SearchAdapter` is the package's only data dependency:
+
+```ts
+const searchAdapter: SearchAdapter = {
+  async search({ cursor, query, signal }) {
+    const response = await fetch(
+      `/api/search?q=${encodeURIComponent(query)}&cursor=${cursor ?? ""}`,
+      { signal }
+    )
+
+    if (!response.ok) throw new Error("Search request failed")
+    return response.json()
+  },
+}
+```
+
+Pass `signal` to the underlying request so an older response cannot replace a newer query.
+
+## Group results {#group-results}
+
+Each `SearchPage` contains `SearchResultGroup` values. Keep a group's `id` stable between pages and each item's `id` stable inside its group. Search uses both identifiers to merge results and remove duplicates.
+
+Use `payload` for application data and `icon` or `image` to customize result presentation.
+
+## Paginate {#paginate}
+
+Return `nextCursor` when another page is available; return `null` or omit it at the end. The surface only displays “Load more” while a cursor exists. A cursor can be a string or number and is passed back to the adapter unchanged.

packages/search/docs/en-US/examples/global-search.mdx

@@ -0,0 +1,58 @@
+---
+title: Global search example
+description: Compose a trigger, dialog, recent searches, and result navigation.
+order: 30
+toc:
+  - id: define-results
+    title: Define results
+  - id: handle-selection
+    title: Handle selection
+  - id: control-history
+    title: Control history
+---
+
+## Define results {#define-results}
+
+```ts
+const searchAdapter: SearchAdapter = {
+  async search({ query }) {
+    return {
+      groups: [
+        {
+          id: "docs",
+          label: "Documentation",
+          items: documents
+            .filter((document) => document.title.includes(query))
+            .map((document) => ({
+              id: document.slug,
+              title: document.title,
+              description: document.description,
+              payload: { href: `/docs/${document.slug}` },
+            })),
+        },
+      ],
+    }
+  },
+}
+```
+
+## Handle selection {#handle-selection}
+
+```tsx
+<SearchProvider
+  adapter={searchAdapter}
+  onSelect={({ item }) => {
+    const payload = item.payload as { href: string }
+    router.navigate({ to: payload.href })
+  }}
+>
+  <HeaderSearchButton />
+  <SearchDialog />
+</SearchProvider>
+```
+
+Code that cannot render `SearchTrigger` can call `searchDialogHandle.open(null)`.
+
+## Control history {#control-history}
+
+Recent searches use `workspace-search-history` by default. Supply a product-specific `historyStorageKey`, or set it to `false` to keep history in memory for the current session only.

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

@@ -0,0 +1,47 @@
+---
+title: Installation and setup
+description: Add Search, register its catalog, and mount the search surface.
+order: 10
+toc:
+  - id: add-the-package
+    title: Add the package
+  - id: import-styles
+    title: Import styles
+  - id: mount-search
+    title: Mount search
+---
+
+## Add the package {#add-the-package}
+
+Add Search to the consuming application:
+
+```json
+{
+  "dependencies": {
+    "@workspace/search": "workspace:*"
+  }
+}
+```
+
+## Import styles {#import-styles}
+
+Import the Search stylesheet once from the application's global stylesheet so Tailwind scans the utilities used by the package:
+
+```css
+@import "@workspace/search/globals.css";
+```
+
+Also add `@workspace/search/locales/{locale}` to the application's internationalization catalog sources.
+
+## Mount search {#mount-search}
+
+```tsx
+import { SearchDialog, SearchProvider, SearchTrigger } from "@workspace/search"
+
+;<SearchProvider adapter={searchAdapter} onSelect={openResult}>
+  <SearchTrigger>Search</SearchTrigger>
+  <SearchDialog />
+</SearchProvider>
+```
+
+`SearchDialog` registers `Mod+K` by default. Pass `hotkey={false}` when the application manages shortcuts centrally.

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

@@ -0,0 +1,29 @@
+---
+title: Overview
+description: Understand the Search package data boundary, interactions, and use cases.
+order: 1
+toc:
+  - id: package-role
+    title: Package role
+  - id: capabilities
+    title: Capabilities
+  - id: design-boundary
+    title: Design boundary
+---
+
+## Package role {#package-role}
+
+`@workspace/search` provides an application-search surface and its state management. The host supplies data through `SearchAdapter`; Search owns the query lifecycle, pagination, result presentation, selection interactions, and recent searches.
+
+## Capabilities {#capabilities}
+
+- Connect any HTTP API, database, command registry, or local index through an adapter.
+- Present results in domain groups and merge paginated data.
+- Cancel stale requests with `AbortSignal`.
+- Keep recent searches with configurable local persistence.
+- Provide a `Mod+K` shortcut plus empty, loading, and error states.
+- Ship `en-US` and `zh-Hans` message catalogs.
+
+## Design boundary {#design-boundary}
+
+Search does not choose the data source or perform navigation. The application implements the adapter and interprets each result's `payload` in `onSelect`.