diff --git a/CHANGELOG.md b/CHANGELOG.md
index fa98b5a..b435ebf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,15 +7,15 @@ follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and adopts th
 ## [Unreleased]
 
 ### Added
-- Rebuilt README.md and changelog after the structural merge to keep parity with `prestashop-mcp` documentation.
-- Cross-platform setup guidance covering Linux/macOS shells and the Visual Studio `vsenv` workflow on Windows.
+- Restored README.md and CHANGELOG.md after merge conflicts while preserving the streamlined structure shared with `prestashop-mcp`.
+- Documented platform-specific setup covering Linux/macOS shells, Windows Visual Studio `vsenv`, and the Docker workflow.
 
 ### Changed
-- Reaffirmed the minimal repository layout (single server implementation, shared docs bundle, optional Docker assets).
-- Clarified how configuration is loaded through `pydantic-settings` and linked to the new documentation bundle.
+- Reconciled feature and tool descriptions so they capture both the detailed ERP coverage and the new documentation bundle layout.
+- Clarified configuration guidance around `pydantic-settings`, environment variables, and `.env` files.
 
 ### Removed
-- Stale references to deprecated helper scripts and legacy documentation variants.
+- Obsolete references to legacy helper scripts and superseded documentation variants that were dropped during the repository cleanup.
 
 ## [1.1.0] - 2024-05-22
 
diff --git a/README.md b/README.md
index b4862dc..a0a6159 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,19 @@
 # Dolibarr MCP Server
 
-Dolibarr MCP is a lean Model Context Protocol (MCP) server that surfaces the most
-useful Dolibarr ERP/CRM operations to AI copilots. The repository now mirrors the
-clean layout of [`prestashop-mcp`](https://github.com/latinogino/prestashop-mcp):
-a single production-ready server, a concise async HTTP client, and a
+Dolibarr MCP is a focused Model Context Protocol (MCP) server that exposes the
+most useful Dolibarr ERP/CRM operations to AI copilots. The repository mirrors
+the clean layout used by [`prestashop-mcp`](https://github.com/latinogino/prestashop-mcp):
+a single production-ready server implementation, an async HTTP client, and a
 self-contained documentation bundle.
 
-## Documentation
+## 🚀 Overview
+
+This MCP server enables complete management of your Dolibarr ERP/CRM through AI
+tools such as Claude Desktop. With specialised tools you can manage customers,
+products, invoices, orders, contacts, and system administration tasks from a
+single MCP endpoint.
+
+## 📚 Documentation
 
 All user and contributor guides live in [`docs/`](docs/README.md):
 
@@ -15,16 +22,31 @@ All user and contributor guides live in [`docs/`](docs/README.md):
 - [Development](docs/development.md) – test workflow, linting, and Docker helpers
 - [API Reference](docs/api-reference.md) – Dolibarr REST resources and corresponding MCP tools
 
-## Repository layout
+## ✨ Features
 
-| Path | Purpose |
-| --- | --- |
-| `src/dolibarr_mcp/` | MCP server implementation, async Dolibarr client, configuration helpers, and CLI entry point |
-| `tests/` | Pytest-based automated test-suite covering configuration, client behaviour, and MCP tool registration |
-| `docs/` | Markdown documentation mirroring the structure used by `prestashop-mcp` |
-| `docker/` | Optional container assets for local experimentation or deployment |
+- **💼 Complete ERP/CRM Management** – Tools for customers, products, invoices, orders, and contacts
+- **⚡ Async/Await Architecture** – Modern, high-performance HTTP client and server
+- **🛡️ Comprehensive Error Handling** – Robust validation and structured responses
+- **🐳 Docker Support** – Optional container workflow for local experimentation and deployment
+- **🔧 Production-Ready** – Automated tests and configuration management powered by `pydantic-settings`
 
-## Installation
+## 🛠 Available tools
+
+`dolibarr_mcp_server` registers MCP tools that map to common Dolibarr workflows.
+See the [API reference](docs/api-reference.md) for full details.
+
+- **System** – `test_connection`, `get_status`, and `dolibarr_raw_api`
+- **Users** – CRUD helpers for Dolibarr users
+- **Customers / Third Parties** – CRUD helpers for partners
+- **Products** – CRUD helpers for product catalogue entries
+- **Invoices** – CRUD helpers for invoices
+- **Orders** – CRUD helpers for customer orders
+- **Contacts** – CRUD helpers for contact records
+
+The async implementation in [`dolibarr_client.py`](src/dolibarr_mcp/dolibarr_client.py)
+handles authentication, pagination, and error handling for all endpoints.
+
+## 📦 Installation
 
 ### Linux / macOS
 
@@ -46,11 +68,26 @@ pip install -e '.[dev]'
 
 1. Launch the **x64 Native Tools Command Prompt for VS** or **Developer PowerShell for VS** (`vsenv`).
 2. Create a virtual environment: `py -3 -m venv .venv`.
-3. Activate it: `call .venv\\Scripts\\activate.bat` (Command Prompt) or `.\.venv\\Scripts\\Activate.ps1` (PowerShell).
+3. Activate it: `call .venv\\Scripts\\activate.bat` (Command Prompt) or `.\\.venv\\Scripts\\Activate.ps1` (PowerShell).
 4. Install the package: `pip install -e .`.
 5. Install development extras when required: `pip install -e .[dev]` (PowerShell requires escaping brackets: ``pip install -e .`[dev`]``).
+6. Note the Python path (`where python`) for integration with Claude Desktop or other MCP hosts.
 
-## Configuration
+### Docker
+
+```bash
+# Using Docker Compose (recommended)
+docker compose up -d
+
+# Or build and run directly
+docker build -t dolibarr-mcp .
+docker run -d \
+  -e DOLIBARR_URL=https://your-dolibarr.example.com/api/index.php \
+  -e DOLIBARR_API_KEY=YOUR_API_KEY \
+  dolibarr-mcp
+```
+
+## ⚙️ Configuration
 
 Set the following environment variables (they may live in a `.env` file):
 
@@ -58,43 +95,43 @@ Set the following environment variables (they may live in a `.env` file):
 - `DOLIBARR_API_KEY` – personal Dolibarr API token
 - `LOG_LEVEL` – optional logging verbosity (defaults to `INFO`)
 
-[`Config`](src/dolibarr_mcp/config.py) is built with `pydantic-settings` and supports loading from the environment, `.env` files, and CLI overrides. See the [configuration guide](docs/configuration.md) for a full matrix and troubleshooting tips.
+[`Config`](src/dolibarr_mcp/config.py) is built with `pydantic-settings` and
+supports loading from the environment, `.env` files, and CLI overrides. See the
+[configuration guide](docs/configuration.md) for a full matrix and troubleshooting tips.
 
-## Running the server
+## ▶️ Running the server
 
-Dolibarr MCP communicates with hosts over STDIO. Once configured, launch the server with:
+Dolibarr MCP communicates with hosts over STDIO. Once configured, launch the
+server with:
 
 ```bash
 python -m dolibarr_mcp.cli serve
 ```
 
-You can validate credentials and connectivity using the built-in test command before wiring it into a host:
+You can validate credentials and connectivity using the built-in test command
+before wiring it into a host:
 
 ```bash
 python -m dolibarr_mcp.cli test --url https://example.com/api/index.php --api-key YOUR_TOKEN
 ```
 
-## Available tools
+## 🤖 Using with Claude Desktop
 
-`dolibarr_mcp_server` registers MCP tools that map to common Dolibarr workflows:
+Add an entry to `claude_desktop_config.json` that points to your virtual
+environment’s Python executable and the `dolibarr_mcp.cli` module. After
+installation, verify the executable path with `which python` (Linux/macOS) or
+`where python` (Windows `vsenv`). Restart Claude Desktop so it picks up the new
+MCP server.
 
-- **System** – `test_connection`, `get_status`
-- **Users** – CRUD helpers for Dolibarr users
-- **Customers / Third Parties** – CRUD helpers for partners
-- **Products** – CRUD helpers for product catalogue entries
-- **Invoices** – CRUD helpers for invoices
-- **Orders** – CRUD helpers for customer orders
-- **Contacts** – CRUD helpers for contact records
-- **Raw API access** – `dolibarr_raw_api` for direct REST operations
+## 🧪 Development workflow
 
-The async implementation in [`dolibarr_client.py`](src/dolibarr_mcp/dolibarr_client.py) handles request signing, pagination, and error handling. The [API reference](docs/api-reference.md) summarises the exposed REST coverage.
+- Run the test-suite with `pytest` (see [development docs](docs/development.md)
+  for coverage flags and Docker helpers).
+- Editable installs rely on the `src/` layout and expose the `dolibarr-mcp`
+  console entry point.
+- Contributions follow the same structure and documentation conventions as
+  `prestashop-mcp` to keep the twin projects in sync.
 
-## Development workflow
-
-- Run the test-suite with `pytest` (see [development docs](docs/development.md) for coverage flags and Docker helpers).
-- Editable installs rely on the `src/` layout and expose the `dolibarr-mcp` console entry point.
-- Contributions follow the same structure and documentation conventions as `prestashop-mcp` to keep the twin projects in sync.
-
-## License
+## 📄 License
 
 This project is released under the [MIT License](LICENSE).