diff --git a/README.md b/README.md
index 87bd5bc..1bb6dba 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,139 @@
 # Simple React App Kit
 
-Simple React App Kit is a reusable React application kit built with TanStack
-Start, shadcn/ui, and workspace packages.
+Simple React App Kit is a production-oriented React workspace for building application interfaces without assembling the foundation from scratch. It includes a runnable TanStack Start application, shared shadcn/ui components, feature packages, internationalization, documentation, and tested integration patterns.
 
-## Adding components
+[Open the documentation](https://react-app-kit.go-slim.dev) · [English documentation](https://react-app-kit.go-slim.dev/en-US/)
 
-To add components to your app, run the following command at the root of your `web` app:
+## What you get
 
-```bash
-pnpm dlx shadcn@latest add button -c apps/web
+- A TanStack Start application with routing, SSR, responsive layout, and light/dark themes.
+- Shared shadcn/ui primitives that remain editable source code.
+- Application-level navigation, notifications, chat, and appearance blocks.
+- Adapter-based Media and Search packages that do not prescribe a backend.
+- A composable Lexical editor package.
+- Type-safe application preferences and an internationalization workflow.
+- A bilingual MDX documentation site with SSG, search, and Cloudflare deployment.
+
+## Quick start
+
+Requirements:
+
+- [Bun](https://bun.com/) 1.3.5 or newer
+- Node.js 22.19 or newer
+
+Install dependencies and start the example application:
+
+```sh
+bun install
+bun run dev
 ```
 
-This will place the ui components in the `packages/ui/src/components` directory.
+The development server prints the local URL when it is ready.
 
-## Using components
+To run the documentation site separately:
 
-To use the components in your app, import them from the `ui` package.
+```sh
+bun run --cwd docs dev
+```
+
+## Workspace packages
+
+The packages are private workspace packages by default. Use them inside this repository with `workspace:*`, or adapt and publish them under your own scope.
+
+| Package | Use it for |
+| --- | --- |
+| `@workspace/ui` | Shared components, hooks, icons, design tokens, and global styles |
+| `@workspace/blocks` | Application shell, navigation, notifications, chat, and appearance controls |
+| `@workspace/media` | Media browsing, uploads, folders, asset selection, and storage adapters |
+| `@workspace/search` | Application search, grouped results, pagination, and search history |
+| `@workspace/lexical` | Rich-text editing, actions, media nodes, and editor presets |
+| `@workspace/i18n` | Locale runtime, catalogs, extraction, compilation, and development tools |
+| `@workspace/preferences` | Typed external state, persistence callbacks, SSR snapshots, and effects |
+
+The intended boundary is simple: your application owns APIs, persistence, routing decisions, and business rules; workspace packages own reusable presentation and interaction behavior.
+
+## Using a package
+
+Add a workspace dependency to the consuming application:
+
+```json
+{
+  "dependencies": {
+    "@workspace/media": "workspace:*"
+  }
+}
+```
+
+Import the package stylesheet once when it provides one. This also lets Tailwind discover the utilities used by that package:
+
+```css
+@import "@workspace/ui/globals.css";
+@import "@workspace/media/globals.css";
+```
+
+Then import only the public API you need:
 
 ```tsx
-import { Button } from "@workspace/ui/components/button";
+import {
+  MediaLibrary,
+  MediaProvider,
+  type MediaAdapter,
+} from "@workspace/media"
+
+export function MediaPage({ adapter }: { adapter: MediaAdapter }) {
+  return (
+    <MediaProvider adapter={adapter}>
+      <MediaLibrary />
+    </MediaProvider>
+  )
+}
 ```
+
+Package-specific setup, adapters, locale catalogs, and progressive examples are documented on the [documentation site](https://react-app-kit.go-slim.dev).
+
+## Adding shadcn/ui components
+
+Run the shadcn CLI from the repository root:
+
+```sh
+bunx shadcn@latest add button -c apps/web
+```
+
+The workspace aliases place generated components in `packages/ui/src/components`. Import them through the UI package:
+
+```tsx
+import { Button } from "@workspace/ui/components/button"
+```
+
+Generated components belong to the repository and can be changed to match the product instead of being treated as an opaque dependency.
+
+## Common commands
+
+| Command | Purpose |
+| --- | --- |
+| `bun run dev` | Start the example web application |
+| `bun run build` | Build the web application |
+| `bun run check` | Check formatting, lint, and all workspace types |
+| `bun run format` | Format application and package source files |
+| `bun run lint` | Run Oxlint across the repository |
+| `bun run typecheck` | Type-check every workspace |
+| `bun run --cwd packages/media test` | Run tests for one package |
+| `bun run --cwd docs build` | Generate the static documentation site |
+| `bun run --cwd docs deploy` | Build and deploy the docs to Cloudflare |
+
+## Project structure
+
+```text
+apps/web/       Runnable TanStack Start application
+docs/           Documentation application and SSG pipeline
+packages/
+  blocks/       Application-level interface blocks
+  i18n/         Internationalization runtime and tooling
+  lexical/      Rich-text editor
+  media/        Media library and picker
+  preferences/  Typed preference state
+  search/       Application search
+  ui/           Shared shadcn/ui components
+```
+
+Documentation for each package lives beside its source under `packages/<name>/docs`, so examples and APIs evolve with the implementation.