From e2d4619c65781d590fc4b30239919d8c792e2ddf Mon Sep 17 00:00:00 2001
From: gmegidish <gil@megidish.net>
Date: Fri, 17 Apr 2026 18:35:26 +0200
Subject: [PATCH] docs: rewrite README with clearer structure and usage
 instructions

---
 README.md | 52 ++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 38 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 572f57a..ff66767 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,47 @@
-# Create Mobilewright
+# create-mobilewright
 
-Getting started with Mobilewright with a single "npm init" command
+Scaffold a [Mobilewright](https://mobilewright.dev) test project in seconds.
+
+## Usage
 
 ```sh
 npm init mobilewright
-# Or for Yarn
-yarn create mobilewright
-# Or for pnpm
-pnpm create mobilewright
 ```
 
-Follow the instructions on screen to create a scaffold Mobilewright test project:
+Also works with Yarn (`yarn create mobilewright`) and pnpm (`pnpm create mobilewright`).
 
-```text
-mobilewright.config.ts
-package.json
-package-lock.json
-tests/
-  example.spec.ts
-```
+The CLI walks you through setup and creates a ready-to-run project:
 
 ![create-mobilewright screenshot](docs/screenshot.png)
+
+## What you get
+
+```
+my-project/
+  mobilewright.config.ts   # Device and app configuration
+  tests/
+    example.spec.ts        # A working test you can run immediately
+  package.json
+```
+
+## Run your first test
+
+```sh
+cd my-project
+npx mobilewright test
+```
+
+That's it. 
+
+If this is the first time you are running a test on iOS (simulator or real device), you will need to run `npx mobilewright install` to set up the agent on the device.
+
+If something's missing, `npx mobilewright doctor` tells you exactly what to fix.
+
+## Next steps
+
+- [Mobilewright docs](https://mobilewright.dev/docs) — API reference and guides
+- [mobile-use.com](https://mobile-use.com) — Run tests on real devices in the cloud
+
+## License
+
+Apache