docs: modify README to improve read flow

Author: codesalatdev

README.md

@@ -4,7 +4,7 @@
 
 **If you want to know why interacting with Picnic is getting harder than ever, check out their blogpost about architectural changes: [https://blog.picnic.nl/adding-write-functionality-to-pages-with-self-service-apis-d09aa7dbc9c0](https://jobs.picnic.app/en/blogs/adding-write-functionality-to-pages-with-self-service-apis)**
 
-Fork of the Unofficial Python wrapper for the [Picnic](https://picnic.app) API. While not all API methods have been implemented yet, you'll find most of what you need to build a working application are available. 
+Fork of the Unofficial Python wrapper for the [Picnic](https://picnic.app) API. While not all API methods have been implemented yet, you'll find most of what you need to build a working application is available.
 
 This library is not affiliated with Picnic and retrieves data from the endpoints of the mobile application. **Use at your own risk.**
 
@@ -62,14 +62,18 @@ domain-JSON endpoints (`get_user`, `get_cart`, `get_delivery_slots`,
 `get_delivery`, `get_deliveries` / `get_current_deliveries`, and the cart-mutation
 methods). Every model exposes `.raw` with the original, untouched payload as an
 escape hatch for data that isn't modelled yet, and `.model_dump()` for a
-plain-dict view. See the [migration notes](#migrating-from-1x-to-20).
+plain-dict view.
 
 A couple of endpoints still return raw dicts: `get_delivery_scenario` and
 `get_delivery_position` (only populated while a delivery is en route, so there is
 no stable shape to model), and `get_article_category` (appears to have been
 removed by Picnic — use `get_article(id, add_category=True)` instead).
 
-## Searching for an article
+If you are upgrading from 1.x, see the [migration notes](#migrating-from-1x-to-20).
+
+## Usage
+
+### Searching for an article
 
 ```python
 result = picnic.search('coffee')          # -> SearchResult
@@ -81,7 +85,7 @@ result.items[0].raw                         # original tile payload
 Search tiles only carry `display_price` (the price shown, in integer cents) — the
 raw payload has no separate `price` key — so read `display_price`.
 
-## Get article by ID
+### Get article by ID
 
 ```python
 article = picnic.get_article("s1019822")   # -> Article | None
@@ -104,32 +108,14 @@ article = picnic.get_article("s1019822", add_category=True)
 article.category.name                       # 'Koffiebonen'
 ```
 
-## Get article by GTIN (EAN)
+### Get article by GTIN (EAN)
+
 ```python
 article = picnic.get_article_by_gtin("8000070025400")  # -> Article | None
 article.name                                # 'Lavazza Caffè Crema e Aroma Bohnen'
 ```
 
-## Migrating from 1.x to 2.0
-
-- `search()` now returns a `SearchResult` (`.items` is a list of `SearchResultItem`)
-  instead of `[{"items": [...]}]`.
-- `get_article()` / `get_article_by_gtin()` now return an `Article` (or `None`)
-  instead of a `dict`; use `.id` / `.name` / `.category` instead of key access.
-- `get_category_by_ids()` now returns a `Category` instead of a `dict`.
-- Missing/unexpected PML nodes now raise `PicnicParseError` (from
-  `python_picnic_api2`) instead of a bare `KeyError`.
-- The domain-JSON methods now return typed models instead of raw dicts:
-  `get_user()` → `User`, `get_cart()` / `add_product()` / `remove_product()` /
-  `clear_cart()` → `Cart`, `get_delivery_slots()` → `DeliverySlots`,
-  `get_delivery()` → `Delivery`, and `get_deliveries()` /
-  `get_current_deliveries()` → `list[DeliverySummary]`. Use attribute access
-  (`cart.items`, `user.contact_email`) instead of `["items"]` / `["contact_email"]`.
-- `get_delivery_scenario()`, `get_delivery_position()` and `get_article_category()`
-  still return raw dicts (see [Typed models](#typed-models-2x)).
-- Any field you need that isn't modelled yet is available on `model.raw`.
-
-## Get the user
+### Get the user
 
 ```python
 user = picnic.get_user()          # -> User
@@ -138,7 +124,7 @@ user.address.city                   # 'Amsterdam'
 user.total_deliveries               # 25
 ```
 
-## Check cart
+### Check cart
 
 ```python
 cart = picnic.get_cart()          # -> Cart
@@ -148,7 +134,8 @@ cart.items[0].items[0].name         # 'Lavazza Caffè Crema e Aroma Bohnen'
 cart.raw                            # original cart payload
 ```
 
-## Manipulating your cart
+### Manipulating your cart
+
 All of these methods return the updated `Cart`.
 
 ```python
@@ -162,7 +149,7 @@ picnic.remove_product("s1019822")
 picnic.clear_cart()
 ```
 
-## See upcoming deliveries
+### See upcoming deliveries
 
 ```python
 deliveries = picnic.get_current_deliveries()   # -> list[DeliverySummary]
@@ -175,10 +162,29 @@ delivery = picnic.get_delivery(deliveries[0].delivery_id)   # -> Delivery
 delivery.orders[0].items[0].items[0].name
 ```
 
-## See available delivery slots
+### See available delivery slots
 
 ```python
 slots = picnic.get_delivery_slots()   # -> DeliverySlots
 slots.delivery_slots[0].window_start    # '2025-04-29T17:15:00.000+02:00'
 slots.selected_slot.slot_id
 ```
+
+## Migrating from 1.x to 2.0
+
+- `search()` now returns a `SearchResult` (`.items` is a list of `SearchResultItem`)
+  instead of `[{"items": [...]}]`.
+- `get_article()` / `get_article_by_gtin()` now return an `Article` (or `None`)
+  instead of a `dict`; use `.id` / `.name` / `.category` instead of key access.
+- `get_category_by_ids()` now returns a `Category` instead of a `dict`.
+- Missing/unexpected PML nodes now raise `PicnicParseError` (from
+  `python_picnic_api2`) instead of a bare `KeyError`.
+- The domain-JSON methods now return typed models instead of raw dicts:
+  `get_user()` → `User`, `get_cart()` / `add_product()` / `remove_product()` /
+  `clear_cart()` → `Cart`, `get_delivery_slots()` → `DeliverySlots`,
+  `get_delivery()` → `Delivery`, and `get_deliveries()` /
+  `get_current_deliveries()` → `list[DeliverySummary]`. Use attribute access
+  (`cart.items`, `user.contact_email`) instead of `["items"]` / `["contact_email"]`.
+- `get_delivery_scenario()`, `get_delivery_position()` and `get_article_category()`
+  still return raw dicts (see [Typed models](#typed-models-2x)).
+- Any field you need that isn't modelled yet is available on `model.raw`.