diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4f9c2df..ecf03b8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,9 @@ release steps in [CONTRIBUTING.md](CONTRIBUTING.md).
- `npm run types:check`, a `tsc --noEmit` pass over a compile-time test of the
public surface, enforced in CI so the declarations cannot drift from the
implementation unnoticed.
+- README now opens with status badges, a demo GIF, and an "Is this the right
+ tool?" section answering the question evaluators actually arrive with.
+- A CDN install option, so the library can be tried without an npm install.
- Open Graph and Twitter card metadata on the demo site, plus a description and
canonical URL. Links to the demo previously rendered as a bare URL with no
preview anywhere they were shared, and search engines had no description to
diff --git a/README.md b/README.md
index 342e6a2..548f285 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,14 @@
Zero-dependency vanilla JS tool to pick focal points and crop zones on images. Returns pixel coordinates you can feed straight into your image pipeline.
+
+ 
+ 
+ 
+ 
+ 
+
+
@@ -16,17 +24,44 @@ Zero-dependency vanilla JS tool to pick focal points and crop zones on images. R
- **Focus point**: Set a point of interest on the image with a visual marker
- **Crop zone**: Define a crop zone with resize handles
-- **No dependencies**: Works without external libraries
-- **Simple API**: Clear and easy-to-use interface
+- **No dependencies**: 3.6 kB gzipped, nothing else to install
+- **Typed**: TypeScript declarations ship with the package
+- **Framework-agnostic**: plain DOM, so it drops into anything
- **Customizable**: Flexible configuration options
- **Responsive**: Adapts to screen resizing
+## Is this the right tool?
+
+**Yes, if** you need a person to mark _where_ the subject of an image is, and
+you want those positions back as numbers — to store on a record, or hand to an
+image pipeline. The coordinates are in the image's original pixels, so they stay
+valid at any display size:
+
+| What you get | Where it tends to go |
+| ------------------------ | ------------------------------------------------------------------------ |
+| `focusPoint: {x, y}` | CSS `object-position`, imgix `fp-x`/`fp-y`, Cloudinary gravity |
+| `cropZone: {x, y, w, h}` | a server-side crop with sharp or ImageMagick, or a stored crop rectangle |
+
+**No, if** you need the browser to actually produce the cropped image — rotation,
+zoom, canvas export, file output. This library never touches pixels; it only
+reports coordinates. A full cropper such as Cropper.js is built for that job.
+
## Installation
```bash
npm install @h4md1/visual-image-tool
```
+Or skip the install entirely and load it from a CDN — this is what the
+[live demo](https://h4md1.fr/visual-image-tool/) does:
+
+```html
+
+```
+
+Pin the exact version rather than the major in production. There is a runnable
+[JSFiddle](https://jsfiddle.net/zuadgm4p/7/) if you would rather poke at it first.
+
## Quick Start Guide
### 1. Import