diff --git a/README.md b/README.md
index b81c571..51736bd 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,68 @@
 # worldcountries
-A small responsive app build with Vue, Vuex, Axios and Bulma. It calls the restcountries API, visualizes the list of countries, and shows detailed information for each country in a modal.
-## Project setup
+A small responsive Vue app that lists countries and shows details in a modal. Built with Vue, Vuex, Axios and Bulma. It consumes the REST Countries API.
+
+## Features
+- Responsive UI with Bulma
+- Country list with basic info
+- Country details shown in a modal
+- Vuex for state management
+- Axios for API requests
+- Unit tests and coverage reporting
+
+## Prerequisites
+- Node.js (v14+ recommended)
+- npm (v6+)
+- Git
+
+## Quick start
+
+1. Clone the repository
+   ```
+   git clone https://github.com/dadobos/worldcountries.git
+   ```
+2. Enter the project directory
+   ```
+   cd worldcountries
+   ```
+3. Install dependencies
+   ```
+   npm install
+   ```
+4. Start the dev server
+   ```
+   npm run serve
+   ```
+5. Open http://localhost:8080/ in your browser
+
+## Scripts
+
+- `npm run serve` — start the dev server
+- `npm run build` — build for production
+- `npm test` — run unit tests
+- `npm run coverage` — run tests and generate coverage report
+- `npm run lint` — run linting (if configured)
+
+## API
+
+This project uses the REST Countries API:
+https://restcountries.com
+
+No API key is required.
+
+## Testing
+Run unit tests with:
 ```
-clone the project to your local drive with 
-git clone https://github.com/dadobos/worldcountries.git
-
-go inside the project with
-cd worldcountries
-
-install the packages with
-npm install
-
-start the project with
-npm run serve
-
-it is now available in your browser on http://localhost:8080/
-
-
-start testing with
 npm test
-
-check full coverage with
+```
+Check full coverage:
+```
 npm run coverage
-
 ```
 
+## Development notes
+- Main frameworks: Vue + Vuex
+- HTTP client: Axios
+- Styling: Bulma
+- Components are organized under `src/components`, store under `src/store`
 
+If you add environment-specific endpoints or keys, use `.env` files and do not commit secrets.
diff --git a/package.json b/package.json
index 24e4bde..bd85c3d 100644
--- a/package.json
+++ b/package.json
@@ -1,5 +1,6 @@
 {
 	"name": "worldcountries",
+	"homepage": "https://dadobos.github.io/worldcountries/",
 	"version": "0.1.0",
 	"private": true,
 	"jest": {