diff --git a/README.md b/README.md
index c4a70ee3..9e1a6cc9 100644
--- a/README.md
+++ b/README.md
@@ -5,43 +5,46 @@
 [![MIT license](https://img.shields.io/badge/license-MIT-0f766e.svg)](LICENSE)
 [![React 19](https://img.shields.io/badge/React-19-087ea4.svg?logo=react)](https://react.dev/)
 
-Accessible, composable bottom sheets for React 19. An independently maintained continuation of the original `react-spring-bottom-sheet`, rebuilt with compound components, explicit styling contracts, and current-browser verification.
+A draggable bottom sheet for React 19, with dialog semantics, focus management,
+snap points, and scroll-aware gestures. Use it for filters, account actions, or
+details that should stay close to the page the user is working on.
 
-[Live docs](https://react-spring-bottom-sheet.nipesolutions.com) · [Live demo](https://react-spring-bottom-sheet.nipesolutions.com/examples) · [Migration from the original](https://react-spring-bottom-sheet.nipesolutions.com/migration-from-react-spring-bottom-sheet/) · [API reference](https://react-spring-bottom-sheet.nipesolutions.com/api) · [npm](https://www.npmjs.com/package/@nipe-solutions/react-spring-bottom-sheet)
+This is an independently maintained continuation of the original
+`react-spring-bottom-sheet`. Version 5 uses a redesigned compound API; existing
+applications need to follow the migration guide.
 
-## Install
+[Live docs](https://react-spring-bottom-sheet.nipesolutions.com) · [Live demo](https://react-spring-bottom-sheet.nipesolutions.com/examples) · [Migration from the original](https://react-spring-bottom-sheet.nipesolutions.com/migration-from-react-spring-bottom-sheet/) · [API reference](https://react-spring-bottom-sheet.nipesolutions.com/docs/api/) · [npm](https://www.npmjs.com/package/@nipe-solutions/react-spring-bottom-sheet)
 
-```bash
-npm install @nipe-solutions/react-spring-bottom-sheet
-```
+## When to use it
 
-Import the complete default styling once from your application entry point:
+Choose a sheet when the interaction benefits from dragging between heights or
+sharing space with the page. Modal sheets contain focus and isolate background
+content; `modal={false}` supports persistent panels such as map details. Named
+snap points can be content-sized, pixel heights, or viewport percentages.
 
-```ts
-import '@nipe-solutions/react-spring-bottom-sheet/styles.css'
-```
+For a simple dialog with no dragging or snap behavior, a native `<dialog>` or an
+existing dialog component may be enough. This version requires React 19 and
+current evergreen browsers; it is not a drop-in replacement for version 4.
 
-## Why version 5
+## Install
 
-- Built for React 19 with accessible dialog and focus behavior backed by
-  explicit accessibility tests.
-- Interruption-safe gestures and motion keep the sheet responsive through rapid
-  input and state changes.
-- Replaceable styling contracts let applications own the visual design without
-  fighting library mechanics.
-- Verified against current evergreen Chromium, Firefox, and WebKit browsers.
+In an application with React 19 and React DOM 19:
 
-## Migrating from the original package
+```bash
+npm install @nipe-solutions/react-spring-bottom-sheet
+```
 
-Move from `react-spring-bottom-sheet` to
-`@nipe-solutions/react-spring-bottom-sheet` with the [dedicated migration
-page](https://react-spring-bottom-sheet.nipesolutions.com/migration-from-react-spring-bottom-sheet/)
-and the [detailed repository guide](docs/migration-v4-to-v5.md).
+## Quick start
 
-## Example
+Import the complete default stylesheet once. In a Next.js App Router application,
+put interactive sheet components behind a client boundary and import the
+stylesheet from the location your application uses for global CSS.
 
 ```tsx
+'use client'
+
 import { Sheet } from '@nipe-solutions/react-spring-bottom-sheet'
+import '@nipe-solutions/react-spring-bottom-sheet/styles.css'
 
 export function AccountActions() {
   return (
@@ -65,7 +68,24 @@ export function AccountActions() {
 }
 ```
 
-`BottomSheet` is available as a convenience component for the common structure.
+The example manages its own open state. To connect it to application state, use
+`open` and `onOpenChange` together. Keep `Sheet.Title` in the content so the
+dialog has an accessible name; `Sheet.Description` supplies optional context.
+
+See [component anatomy](https://react-spring-bottom-sheet.nipesolutions.com/docs/anatomy/),
+[state](https://react-spring-bottom-sheet.nipesolutions.com/docs/state/), and the
+[examples](https://react-spring-bottom-sheet.nipesolutions.com/examples) for
+controlled sheets, forms, and multiple snap points.
+
+## Why version 5
+
+Compound components let you place actions, scroll regions, and surrounding
+content while the library owns gestures, motion, and modal coordination.
+`BottomSheet` provides the common structure as a convenience component. The
+mechanical stylesheet and optional theme have separate entry points, so you can
+keep the behavior while supplying your own design. Read the
+[accessibility guide](https://react-spring-bottom-sheet.nipesolutions.com/docs/accessibility/)
+for dialog naming, focus, and non-modal behavior.
 
 ## Styles
 
@@ -74,6 +94,10 @@ export function AccountActions() {
 - `/theme.css` includes the optional visual theme and token defaults.
 - `/tokens.css` exposes the default token declarations separately.
 
+Use `/styles.css` for the example above. For your own theme, import `/core.css`
+and supply application CSS; omitting the mechanical stylesheet breaks the
+positioning and interaction contract.
+
 All library-owned classes and custom properties use the `rsbs` namespace.
 Mechanical selectors use low specificity so an application can replace the
 visual design with ordinary CSS and without `!important`.
@@ -85,9 +109,21 @@ visual design with ordinary CSS and without `!important`.
 - Current evergreen Chromium, Firefox, and WebKit browsers
 - TypeScript declarations, ESM, and CommonJS package entry points
 
-Read the [documentation](https://react-spring-bottom-sheet.nipesolutions.com),
-the [migration guide](docs/migration-v4-to-v5.md), and the [contribution
-guide](CONTRIBUTING.md).
+Gesture, dialog, focus, and styling behavior are covered by repository tests,
+including automated browser scenarios. Validate the sheet inside your own
+scroll containers, overlay stack, and target devices. A custom portal container
+must establish the size and clipping boundary the sheet should fill; see
+[portals and layering](https://react-spring-bottom-sheet.nipesolutions.com/docs/portals/).
+
+## Migrating from the original package
+
+Move from `react-spring-bottom-sheet` to
+`@nipe-solutions/react-spring-bottom-sheet` with the [dedicated migration
+page](https://react-spring-bottom-sheet.nipesolutions.com/migration-from-react-spring-bottom-sheet/)
+and the [detailed repository guide](docs/migration-v4-to-v5.md). Props, refs,
+callbacks, snap points, and CSS selectors changed in version 5.
+
+For development and contributions, read [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Project lineage
 
@@ -101,4 +137,5 @@ MIT license notices are preserved.
 
 ## License
 
-MIT
+[MIT](LICENSE). See [third-party notices](THIRD_PARTY_NOTICES.md) for preserved
+dependency notices.