docs: improve README, docs, and add usage examples

Author: MathiasPaulenko

README.md

@@ -88,6 +88,53 @@ browserget doctor
 browserget install chrome --json
 ```
 
+## Examples
+
+### CI pipeline (idempotent)
+
+```bash
+pip install browserget
+browserget ensure chrome chromedriver
+CHROME_PATH=$(browserget path chrome)
+```
+
+### Install a browser and its matching driver
+
+```bash
+browserget install chrome
+browserget install chromedriver --for chrome
+```
+
+### Pin a specific version
+
+```bash
+browserget install firefox --version 131.0
+browserget install geckodriver --for firefox
+```
+
+### List and clean up
+
+```bash
+browserget list
+browserget remove chrome --version 130.0.6723.69
+browserget doctor
+```
+
+### JSON output
+
+```bash
+browserget list --json
+```
+
+Output:
+
+```json
+[
+  {"name": "chrome", "version": "131.0.6778.87", "path": "/home/user/.browserget/chrome/131.0.6778.87"},
+  {"name": "chromedriver", "version": "131.0.6778.87", "path": "/home/user/.browserget/chromedriver/131.0.6778.87"}
+]
+```
+
 ## Supported targets
 
 | Target | Type | Upstream source |

docs/architecture/overview.md

@@ -6,28 +6,32 @@ a single responsibility and can be tested in isolation.
 ## Module diagram
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│                      cli.py                              │
-│   Typer app, command parsing, output formatting          │
-└────────────┬────────────────────────┬───────────────────┘
-             │                        │
-     ┌───────▼───────┐       ┌───────▼───────┐
-     │  installers/  │       │   registry.py │
-     │  chrome.py    │       │  (JSON store) │
-     │  firefox.py   │       └───────────────┘
-     │  edge.py      │
-     │  chromedriver │
-     │  geckodriver  │
-     │  edgedriver   │
-     └───┬───┬───┬───┘
-         │   │   │
-  ┌──────▼┐ ┌▼───▼────┐ ┌────────────┐
-  │http.py│ │parsers/ │ │  cache.py  │
-  │(async)│ │ cft.py  │ │  (paths)   │
-  └───────┘ │firefox  │ └────────────┘
-            │edge.py  │
-            │gecko.py │
-            └─────────┘
+┌────────────────────────────────────────────────────────────┐
+│                         cli.py                             │
+│      Typer app, command parsing, output formatting           │
+└────────────┬───────────────────────────┬───────────────────┘
+             │                           │
+     ┌───────▼────────┐        ┌─────────▼──────────┐
+     │  installers/   │        │    registry.py     │
+     │  chrome.py     │        │   (JSON store)     │
+     │  firefox.py    │        └────────────────────┘
+     │  edge.py       │
+     │  chromedriver  │
+     │  geckodriver   │
+     │  edgedriver    │
+     └───┬───┬───┬────┘
+         │   │    │
+  ┌──────▼┐  │  ┌─▼───────┐  ┌─────────────┐
+  │http.py│  │  │parsers/ │  │  cache.py   │
+  │(async)│  │  │ cft.py  │  │   (paths)   │
+  └───────┘  │  │firefox  │  └─────────────┘
+             │  │edge.py  │
+             │  │gecko.py │
+             │  └─────────┘
+        ┌────┴────┐
+        │ system.py │
+        │ platform.py
+        └───────────┘
 ```
 
 ## Install flow

docs/architecture/parsers.md

@@ -36,17 +36,29 @@ and checksum URLs based on the version and platform.
 
 ### Edge Updates API
 
-Edge and EdgeDriver versions are resolved from the Microsoft Edge Updates API.
+Edge browser versions are resolved from the Microsoft Edge Updates API.
 
-- **URL**: `https://edgeupdates.microsoft.com/api/v1/edge`
+- **URL**: `https://edgeupdates.microsoft.com/api/products`
 - **Format**: JSON
-- **Structure**: An array of products, each with a `downloads` list containing
-  platform-specific URLs and SHA-256 checksums.
-- **Checksums**: Provided as `Hash` fields (SHA-256) in the download entries.
+- **Structure**: An array of products, each with a `Product` name and a
+  `Releases` list. Each release contains `Platform`, `Architecture`,
+  `ProductVersion`, and an `Artifacts` array. Each artifact has `Location`,
+  `Hash`, and `HashAlgorithm` fields.
+- **Checksums**: Provided as `Hash` and `HashAlgorithm` fields in the artifact
+  entries.
 
-The parser (`parsers/edge.py`) filters by target (edge or edgedriver) and
-platform, using the same internal platform strings as the CfT API
-(e.g. `win64`, `linux64`, `mac-arm64`).
+The parser (`parsers/edge.py`) only supports the `Stable` product and the
+`edge` target. It filters by the mapped `Platform` and `Architecture` and
+returns the first artifact for each matching release.
+
+### EdgeDriver CDN
+
+EdgeDriver is **not** available from the Edge Updates API. It is distributed
+from a separate CDN:
+
+- **Latest version URL**: `https://msedgedriver.microsoft.com/LATEST_STABLE`
+- **Download URL**: `https://msedgedriver.microsoft.com/{version}/edgedriver_{platform}.zip`
+- **Format**: Zip archive, no checksums published.
 
 ### GeckoDriver GitHub releases
 

docs/cli-reference/commands.md

@@ -17,30 +17,78 @@ These options are available on `install` and `ensure` commands:
 
 ### install
 
+Downloads and installs one or more browser or driver binaries.
+
+```bash
+browserget install chrome
+browserget install chrome --version 131.0.6778.87
+browserget install chromedriver --for chrome
+```
+
 ::: browserget.cli.install
 
 ### ensure
 
+Idempotent version of `install`: only downloads if the target is missing.
+
+```bash
+browserget ensure chrome chromedriver
+```
+
 ::: browserget.cli.ensure
 
 ### list
 
+Lists all installed artifacts in the registry.
+
+```bash
+browserget list
+browserget list --json
+```
+
 ::: browserget.cli.list_cmd
 
 ### path
 
+Prints the absolute path to an installed artifact.
+
+```bash
+browserget path chrome
+browserget path chromedriver --version 131.0.6778.87
+```
+
 ::: browserget.cli.path_cmd
 
 ### remove
 
+Removes an installed artifact from the cache and registry.
+
+```bash
+browserget remove chrome
+browserget remove chrome --version 130.0.6723.69
+browserget remove chrome --all
+```
+
 ::: browserget.cli.remove
 
 ### versions
 
+Lists available versions for a target from the upstream API.
+
+```bash
+browserget versions chrome
+```
+
 ::: browserget.cli.versions
 
 ### doctor
 
+Checks cache, disk space, and upstream API reachability.
+
+```bash
+browserget doctor
+```
+
 ::: browserget.cli.doctor
 
 ## Exit codes

docs/index.md

@@ -29,6 +29,37 @@ browserget install chromedriver --for chrome
 browserget doctor
 ```
 
+## Common examples
+
+### Idempotent CI setup
+
+```bash
+pip install browserget
+browserget ensure chrome chromedriver
+CHROME_PATH=$(browserget path chrome)
+```
+
+### Pin a version
+
+```bash
+browserget install chrome --version 131.0.6778.87
+browserget install chromedriver --for chrome
+```
+
+### Manage the cache
+
+```bash
+browserget list
+browserget remove chrome --version 130.0.6723.69
+browserget doctor
+```
+
+### Machine-readable output
+
+```bash
+browserget list --json
+```
+
 ## Features
 
 - **7 commands**: `install`, `ensure`, `list`, `path`, `remove`, `versions`, `doctor`