Enhance README formatting and content clarity

docs/css/style.css

@@ -15,8 +15,8 @@
   --gray8: #6c6c6c;
   --gray9: #3f3f3f;
   --blue: #067df7;
-  --green: #00A995;
-  --red: #F23342;
+  --green: #00a995;
+  --red: #f23342;
   /* theme */
   --primary-color: var(--base);
   --secondary-color: var(--blue);
@@ -46,6 +46,12 @@
   box-sizing: border-box;
 }
 
+/* Hide the TOC and hr in the main content since it's already in the sidebar */
+.markdown-section > blockquote + ul,
+.markdown-section > blockquote + ul + hr {
+  display: none;
+}
+
 body,
 html {
   height: 100%;
@@ -123,7 +129,7 @@ main {
   text-decoration: underline;
 }
 
-.sidebar ul li.active>a {
+.sidebar ul li.active > a {
   border-right: 2px solid var(--primary-color);
   color: var(--primary-color);
   font-weight: 700;
@@ -167,12 +173,12 @@ main {
   position: relative;
 }
 
-.markdown-section>* {
+.markdown-section > * {
   box-sizing: border-box;
   font-size: inherit;
 }
 
-.markdown-section> :first-child {
+.markdown-section > :first-child {
   margin-top: 0 !important;
 }
 
@@ -196,7 +202,6 @@ main {
 }
 
 @media print {
-
   .github-corner,
   .sidebar,
   .sidebar-toggle {
@@ -399,7 +404,7 @@ body {
   -webkit-font-smoothing: initial;
 }
 
-.markdown-section pre>code {
+.markdown-section pre > code {
   border: 0;
   display: block;
   font-family: var(--code-font);
@@ -440,7 +445,6 @@ body {
 /* github corner */
 
 @keyframes b {
-
   0%,
   100% {
     transform: rotate(0);

packages/browserless/README.md

@@ -1,12 +1,12 @@
 <div align="center">
-  <br>
   <img style="width: 500px; margin:3rem 0 1.5rem;" src="https://github.com/microlinkhq/browserless/raw/master/static/logo-banner.png#gh-light-mode-only" alt="browserless">
   <img style="width: 500px; margin:3rem 0 1.5rem;" src="https://github.com/microlinkhq/browserless/raw/master/static/logo-banner-light.png#gh-dark-mode-only" alt="browserless">
-  <br>
-  <br>
-  <p align="center"><strong>browserless</strong>: The headless Chrome/Chromium performance driver for Node.js.</p>
-  <p align="center">See our <a href="https://browserless.js.org" target='_blank' rel='noopener noreferrer'>website</a> for more information.</p>
-  <br>
+  <br><br>
+  <a href="https://microlink.io"><img src="https://img.shields.io/badge/powered_by-microlink.io-blue?style=flat-square&color=%23EA407B" alt="Powered by microlink.io"></a>
+  <img src="https://img.shields.io/github/tag/microlinkhq/browserless.svg?style=flat-square" alt="Last version">
+  <a href="https://coveralls.io/github/microlinkhq/browserless"><img src="https://img.shields.io/coveralls/microlinkhq/browserless.svg?style=flat-square" alt="Coverage Status"></a>
+  <a href="https://www.npmjs.org/package/browserless"><img src="https://img.shields.io/npm/dm/browserless.svg?style=flat-square" alt="NPM Status"></a>
+  <br><br>
 </div>
 
 ## Install
@@ -17,6 +17,37 @@ Using npm:
 npm install browserless puppeteer --save
 ```
 
+## About
+
+This is the **core package** of the browserless monorepo. It provides a high-level, performance-oriented API for headless Chrome/Chromium automation built on top of [Puppeteer](https://github.com/puppeteer/puppeteer).
+
+### What this package does
+
+The `browserless` package serves as the main entry point and orchestrator for the entire browserless ecosystem. It handles:
+
+- **Browser process management**: Spawns and manages headless Chrome/Chromium processes with optimized flags for performance and stability. Includes automatic respawning when the browser disconnects.
+
+- **Browser context isolation**: Creates isolated browser contexts (similar to browser tabs) with separate cookies and cache, enabling concurrent operations without cross-contamination.
+
+- **Built-in methods**: Provides ready-to-use methods for common tasks:
+  - `html(url)` – Serialize page content to HTML
+  - `text(url)` – Extract plain text from a page
+  - `pdf(url)` – Generate PDF documents
+  - `screenshot(url)` – Capture screenshots with device emulation and overlay support
+
+- **Reliability features**: Built-in retry logic, timeout handling, and graceful error recovery for production environments.
+
+### How it fits in the monorepo
+
+This package integrates and re-exports functionality from other `@browserless/*` packages:
+
+| Dependency | Purpose |
+|------------|---------|
+| `@browserless/goto` | Page navigation with smart waiting strategies, ad blocking, and evasion techniques |
+| `@browserless/screenshot` | Screenshot capture with overlays, device emulation, and code highlighting |
+| `@browserless/pdf` | PDF generation with customizable margins and scaling |
+| `@browserless/errors` | Standardized error handling and timeout errors |
+
 ## License
 
 **browserless** © [Microlink](https://microlink.io), released under the [MIT](https://github.com/microlinkhq/browserless/blob/master/LICENSE.md) License.<br>

packages/cli/README.md

@@ -1,14 +1,18 @@
 <div align="center">
-  <br>
   <img style="width: 500px; margin:3rem 0 1.5rem;" src="https://github.com/microlinkhq/browserless/raw/master/static/logo-banner.png#gh-light-mode-only" alt="browserless">
   <img style="width: 500px; margin:3rem 0 1.5rem;" src="https://github.com/microlinkhq/browserless/raw/master/static/logo-banner-light.png#gh-dark-mode-only" alt="browserless">
-  <br>
-  <br>
-  <p align="center"><strong>@browserless/cli</strong>: CLI to interact with Browserless capabilities.</p>
-  <p align="center">See <a href="https://browserless.js.org/#%2F%3Fid=command-line-interface" target='_blank' rel='noopener noreferrer'>CLI</a> section our <a href="https://browserless.js.org" target='_blank' rel='noopener noreferrer'>website</a> for more information.</p>
-  <br>
+  <br><br>
+  <a href="https://microlink.io"><img src="https://img.shields.io/badge/powered_by-microlink.io-blue?style=flat-square&color=%23EA407B" alt="Powered by microlink.io"></a>
+  <img src="https://img.shields.io/github/tag/microlinkhq/browserless.svg?style=flat-square" alt="Last version">
+  <a href="https://coveralls.io/github/microlinkhq/browserless"><img src="https://img.shields.io/coveralls/microlinkhq/browserless.svg?style=flat-square" alt="Coverage Status"></a>
+  <a href="https://www.npmjs.org/package/browserless"><img src="https://img.shields.io/npm/dm/browserless.svg?style=flat-square" alt="NPM Status"></a>
+  <br><br>
 </div>
 
+> @browserless/cli: CLI to interact with Browserless capabilities.
+
+See [CLI section](https://browserless.js.org/#/?id=cli) our website for more information.
+
 ## Install
 
 Using npm:
@@ -17,6 +21,45 @@ Using npm:
 npm install @browserless/cli -g
 ```
 
+## About
+
+This package provides a **command-line interface** for interacting with browserless capabilities directly from your terminal. It exposes the `browserless` binary that wraps the core browserless API into easy-to-use shell commands.
+
+### What this package does
+
+The `@browserless/cli` package allows you to:
+
+- **Take screenshots** from URLs with gradient backgrounds, browser overlays, and device emulation
+- **Generate PDFs** from web pages
+- **Extract content** as HTML or plain text
+- **Run Lighthouse audits** for performance analysis
+- **Analyze page weight** (network requests, transfer size, resource size)
+- **Check URL status** and response information (redirects, headers, status codes)
+
+### Available commands
+
+| Command | Description |
+|---------|-------------|
+| `screenshot <url>` | Capture a screenshot with optional overlay and background |
+| `pdf <url>` | Generate a PDF document from a web page |
+| `html <url>` | Serialize the page content to HTML |
+| `text <url>` | Extract plain text content from the page |
+| `lighthouse <url>` | Run a Google Lighthouse audit and output JSON report |
+| `page-weight <url>` | Analyze network requests and resource sizes |
+| `ping <url>` | Get response info: status code, redirects, headers |
+| `status <url>` | Get the HTTP status code |
+| `goto <url>` | Navigate to a URL and return page/response info |
+
+### How it fits in the monorepo
+This package depends on:
+
+| Dependency                | Purpose                                                 |
+|---------------------------|---------------------------------------------------------|
+| browserless               | Core API for all browser automation operations          |
+| @browserless/lighthouse   | Lighthouse audit integration (used by lighthouse command) |
+
+The CLI acts as a thin wrapper that parses command-line arguments, initializes a browserless instance, and delegates to the appropriate command handler.
+
 ## License
 
 **@browserless/cli** © [Microlink](https://microlink.io), released under the [MIT](https://github.com/microlinkhq/browserless/blob/master/LICENSE.md) License.<br>

packages/devices/README.md

@@ -1,14 +1,18 @@
 <div align="center">
-  <br>
   <img style="width: 500px; margin:3rem 0 1.5rem;" src="https://github.com/microlinkhq/browserless/raw/master/static/logo-banner.png#gh-light-mode-only" alt="browserless">
   <img style="width: 500px; margin:3rem 0 1.5rem;" src="https://github.com/microlinkhq/browserless/raw/master/static/logo-banner-light.png#gh-dark-mode-only" alt="browserless">
-  <br>
-  <br>
-  <p align="center"><strong>@browserless/devices</strong>: A collection of different devices for emulation purposes.</p>
-  <p align="center">See <a href="https://browserless.js.org/#%2F%3Fid=getdeviceoptions" target='_blank' rel='noopener noreferrer'>devices</a> section our <a href="https://browserless.js.org" target='_blank' rel='noopener noreferrer'>website</a> for more information.</p>
-  <br>
+  <br><br>
+  <a href="https://microlink.io"><img src="https://img.shields.io/badge/powered_by-microlink.io-blue?style=flat-square&color=%23EA407B" alt="Powered by microlink.io"></a>
+  <img src="https://img.shields.io/github/tag/microlinkhq/browserless.svg?style=flat-square" alt="Last version">
+  <a href="https://coveralls.io/github/microlinkhq/browserless"><img src="https://img.shields.io/coveralls/microlinkhq/browserless.svg?style=flat-square" alt="Coverage Status"></a>
+  <a href="https://www.npmjs.org/package/browserless"><img src="https://img.shields.io/npm/dm/browserless.svg?style=flat-square" alt="NPM Status"></a>
+  <br><br>
 </div>
 
+> @browserless/devices: A collection of different devices for emulation purposes.
+
+See [devices section](https://browserless.js.org/#/?id=getdeviceoptions) our website for more information.
+
 ## Install
 
 Using npm:
@@ -17,6 +21,105 @@ Using npm:
 npm install @browserless/devices --save
 ```
 
+## About
+
+This package provides a **device descriptor library** for browser emulation. It extends Puppeteer's built-in device list with additional desktop devices and provides fuzzy matching capabilities for device name resolution.
+
+### What this package does
+
+The `@browserless/devices` package allows you to:
+
+- **Emulate devices** by retrieving viewport dimensions, user agent strings, and device capabilities
+- **Use fuzzy matching** to resolve device names even with typos or case variations
+- **Access extended device list** that includes desktop devices missing from Puppeteer's defaults
+
+### Device properties
+
+Each device descriptor includes:
+
+| Property | Description |
+|----------|-------------|
+| `userAgent` | Browser user agent string |
+| `viewport.width` | Screen width in pixels |
+| `viewport.height` | Screen height in pixels |
+| `viewport.deviceScaleFactor` | Device pixel ratio (DPR) |
+| `viewport.isMobile` | Whether it's a mobile device |
+| `viewport.hasTouch` | Whether the device has touch support |
+| `viewport.isLandscape` | Whether the device is in landscape mode |
+
+### Custom Devices
+
+This package extends [Puppeteer's KnownDevices](https://pptr.dev/api/puppeteer.knowndevices/) with additional desktop devices:
+
+| Device | Resolution | Scale |
+|--------|------------|-------|
+| `Macbook Pro 13` | 1280 × 800 | 2x |
+| `Macbook Pro 15` | 1440 × 900 | 2x |
+| `Macbook Pro 16` | 1536 × 960 | 2x |
+| `iMac 21` | 1980 × 1080 | 1x |
+| `iMac 21 4K` | 2048 × 1152 | 2x |
+| `iMac 24 4.5K` | 4480 × 2520 | 1x |
+| `iMac 27` | 2560 × 1440 | 1x |
+| `iMac 27 5K` | 2560 × 1440 | 2x |
+
+### Fuzzy Device Name Matching
+
+When `lossyDeviceName` is enabled (default), the package uses fuzzy matching to resolve device names:
+
+```js
+const createGetDevice = require('@browserless/devices')
+const getDevice = createGetDevice({ lossyDeviceName: true })
+
+// All of these resolve to "Macbook Pro 13"
+getDevice({ device: 'Macbook Pro 13' })
+getDevice({ device: 'macbook pro 13' })
+getDevice({ device: 'MACBOOK PRO 13' })
+getDevice({ device: 'macbook pro' })
+getDevice({ device: 'macboo pro' })  // typo still works!
+```
+
+### Usage
+
+```js
+const createGetDevice = require('@browserless/devices')
+const getDevice = createGetDevice()
+
+// Get device by name
+const device = getDevice({ device: 'iPhone 13' })
+// => { userAgent: '...', viewport: { width: 390, height: 844, ... } }
+
+// Override viewport properties
+const customDevice = getDevice({
+  device: 'iPad',
+  viewport: { isLandscape: true }
+})
+
+// Use custom headers
+const withHeaders = getDevice({
+  headers: { 'user-agent': 'googlebot' }
+})
+
+// Access all available devices
+console.log(getDevice.deviceDescriptors)
+```
+
+### How it fits in the monorepo
+
+This is a **standalone utility package** with no dependencies on other `@browserless/*` packages. It's used by:
+
+| Consumer | Purpose |
+|----------|---------|
+| `@browserless/goto` | Sets viewport and user agent when navigating to URLs |
+| `browserless` (core) | Exposes `getDevice()` method on browser contexts |
+
+### Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `didyoumean3` | Fuzzy string matching for lossy device name resolution |
+| `memoize-one` | Caches device lookups for performance |
+| `require-one-of` | Auto-detects puppeteer/puppeteer-core installation |
+
 ## License
 
 **@browserless/devices** © [Microlink](https://microlink.io), released under the [MIT](https://github.com/microlinkhq/browserless/blob/master/LICENSE.md) License.<br>