diff --git a/src/content/docs/creating-custom-feeds.mdx b/src/content/docs/creating-custom-feeds.mdx
index 16382e65..22422ece 100644
--- a/src/content/docs/creating-custom-feeds.mdx
+++ b/src/content/docs/creating-custom-feeds.mdx
@@ -80,9 +80,9 @@ This is where you tell the html2rss engine exactly what to find on the page. You
       selector: "article.post"
     title:
       selector: "h2 a"
-    link:
+    url:
       selector: "h2 a"
-      attribute: href
+      extractor: "href"
   `}
   lang="yaml"
 />
@@ -100,20 +100,19 @@ This says: "Find each article, get the title from the h2 anchor, and get the lin
 **Step 2:** Create a file called `example.com.yml` with this basic structure:
 
 <Code
-  code={
-    "channel:\n" +
-    "  url: https://example.com/blog\n" +
-    "  title: My Blog\n" +
-    "\n" +
-    "selectors:\n" +
-    "  items:\n" +
-    '    selector: "article.post"\n' +
-    "  title:\n" +
-    '    selector: "h2 a"\n' +
-    "  link:\n" +
-    '    selector: "h2 a"\n' +
-    "    attribute: href"
-  }
+  code={`
+  channel:
+    url: https://example.com/blog
+    title: My Blog
+  selectors:
+    items:
+      selector: "article.post"
+    title:
+      selector: "h2 a"
+    url:
+      selector: "h2 a"
+      extractor: "href"
+  `}
   lang="yaml"
 />
 
@@ -148,9 +147,13 @@ html2rss supports many configuration options:
 
 <Code code={`html2rss feed your-config.yml`} lang="bash" />
 
-3. **Test with `html2rss-web`:** Add your config to the `feeds.yml` file and restart your instance
+3. **Or test against a locally saved HTML file without network requests:**
+
+<Code code={`html2rss feed your-config.yml --input sample.html`} lang="bash" />
+
+4. **Test with `html2rss-web`:** Add your config to the `feeds.yml` file and restart your instance
 
-4. **Check the output:** Make sure all items have titles, links, and descriptions
+5. **Check the output:** Make sure all items have titles, links, and descriptions
 
 ### Useful CLI flags when a site is difficult
 
@@ -158,11 +161,13 @@ Some sites need a little more request budget than the defaults.
 
 - Use `--max-redirects` when the site bounces through several canonicalization or tracking redirects before the real page loads.
 - Use `--max-requests` when your config needs more than one request, for example pagination or other follow-up fetches.
+- Use `--input` to supply a local HTML file to inspect extraction offline.
 
 <Code
   code={`
   html2rss feed your-config.yml --max-redirects 10 && \
   html2rss feed your-config.yml --max-requests 5 && \
+  html2rss feed your-config.yml --input /path/to/page.html && \
   html2rss auto https://example.com/blog --max-redirects 10 --max-requests 5
 `}
   lang="bash"
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
index 695e2f98..0ec4945c 100644
--- a/src/content/docs/index.mdx
+++ b/src/content/docs/index.mdx
@@ -19,7 +19,7 @@ The canonical path to your first feed:
 
 ### Features & Operations
 
-- **[Use included configs](/web-application/guides/use-included-configs/)**: Use the Feed Directory for popular sites.
+- **[Use the Feed Directory](/web-application/guides/use-the-feed-directory/)**: Use the Feed Directory for popular sites.
 - **[Monitoring](/web-application/reference/monitoring/)**: Keep your instance healthy with probes and Sentry.
 - **[Reference](/web-application/reference/)**: Environment variables and versioning strategy.
 
diff --git a/src/content/docs/ruby-gem/guides/advanced-content-extraction.mdx b/src/content/docs/ruby-gem/guides/advanced-content-extraction.mdx
index 31f7552c..b458d0ee 100644
--- a/src/content/docs/ruby-gem/guides/advanced-content-extraction.mdx
+++ b/src/content/docs/ruby-gem/guides/advanced-content-extraction.mdx
@@ -7,8 +7,8 @@ While basic selectors are straightforward, you can achieve very precise content
 
 ## Extractors
 
-Learn how to extract specific attributes (like `src` for images) or static values. See [Extractors](/ruby-gem/reference/selectors/#extractors/).
+Learn how to extract specific attributes (like `src` for images) or static values. See [Extractors](/ruby-gem/reference/selectors/#extractors).
 
 ## Post Processors
 
-Manipulate extracted text, sanitize HTML, convert Markdown, or apply custom logic. See [Post Processors](/ruby-gem/reference/selectors/#post-processors/).
+Manipulate extracted text, sanitize HTML, convert Markdown, or apply custom logic. See [Post Processors](/ruby-gem/reference/selectors/#post-processors).
diff --git a/src/content/docs/ruby-gem/guides/backward-compatibility.mdx b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
index 92a7a6df..3aaad17a 100644
--- a/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
+++ b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
@@ -1,54 +1,69 @@
 ---
-title: "Backward Compatibility"
-description: "html2rss maintains backward compatibility with older configuration formats and attribute names."
+title: "Backward Compatibility & Migrations"
+description: "Migration guide and backward-compatibility reference for html2rss configuration formats."
 ---
 
 import { Code } from "@astrojs/starlight/components";
 
-html2rss maintains backward compatibility with older configuration formats and attribute names.
+This page outlines recent breaking changes, purged legacy aliases, and migration steps for older feed configurations.
 
-## Renamed Attributes
+## Removed Legacy Selector Aliases
 
-Some attribute names have been renamed for clarity, but the old names still work:
+In previous versions, `html2rss` accepted legacy selector names with a deprecation warning. These shims have been removed:
 
-| Current Name   | Legacy Names         | Description                  |
-| -------------- | -------------------- | ---------------------------- |
-| `published_at` | `updated`, `pubDate` | Publication date of the item |
+| Removed Name | Required Name  | Description           |
+| :----------- | :------------- | :-------------------- |
+| `pubDate`    | `published_at` | Item publication date |
+| `updated`    | `published_at` | Item publication date |
 
-### Example
+### Migration Example
 
-Both of these configurations work identically:
+Update any occurrences of `pubDate` or `updated` in your `selectors` block to `published_at`:
 
 <Code
   code={`
-  # Current format (recommended)
+  # Deprecated / Removed
   selectors:
-    published_at:
+    updated:
       selector: ".date"
 
-# Legacy format (still supported)
+# Current & Required
 
 selectors:
-updated:
+published_at:
 selector: ".date"
-`} lang="yaml"
+`}
+lang="yaml"
 />
 
-## Migration Guide
+## Removed Channel Attributes
 
-If you're upgrading from an older version of html2rss:
+`strategy` and `headers` were previously tolerated inside the `channel` block. These legacy shims have been removed. Both keys must now be placed at the top level of your feed configuration:
 
-1. **Update attribute names**: Replace `updated` with `published_at` in your configurations
-2. **Test your feeds**: Verify that all feeds still work correctly after the update
-
-## Deprecated Features
-
-The following features are deprecated but still supported:
-
-- **Legacy attribute names**: While still supported, use the current names for new configurations
+<Code
+  code={`
+  # Deprecated / Removed
+  channel:
+    url: "https://example.com/articles"
+    strategy: browserless
+    headers:
+      User-Agent: "CustomAgent/1.0"
+
+# Current & Required
+
+strategy: browserless
+headers:
+User-Agent: "CustomAgent/1.0"
+channel:
+url: "https://example.com/articles"
+`}
+lang="yaml"
+/>
 
-## Getting Help
+## Migration Checklist
 
-If you encounter issues with backward compatibility:
+When upgrading to modern `html2rss` releases:
 
-- **Report issues**: Open an issue if you find compatibility problems
+1. **Rename date selectors**: Ensure date selectors use `published_at` rather than `updated` or `pubDate`.
+2. **Move channel-level transport keys**: Ensure `strategy` and `headers` are defined at the top level of the YAML file.
+3. **Validate configurations**: Run `html2rss validate config.yml` to ensure your YAML conforms to the current schema.
diff --git a/src/content/docs/ruby-gem/index.mdx b/src/content/docs/ruby-gem/index.mdx
index 9d7a39b8..4fe10115 100644
--- a/src/content/docs/ruby-gem/index.mdx
+++ b/src/content/docs/ruby-gem/index.mdx
@@ -10,8 +10,11 @@ This section provides comprehensive documentation for the `html2rss` Ruby gem.
 If you are looking for the stable machine-readable contract for config authoring, use the JSON Schema exported by the core repo:
 
 - Repository file: [**`html2rss-config.schema.json`**](https://github.com/html2rss/html2rss/blob/master/schema/html2rss-config.schema.json)
-- CLI export: `html2rss schema`
-- Runtime validation: `html2rss validate config.yml`
+- CLI export: `html2rss schema` (also `--write`, `--no-pretty`)
+- Runtime validation: `html2rss validate config.yml` or `Html2rss::Config.validate`
+- Ruby discovery: `Html2rss::Config.json_schema` / `Html2rss::Config.schema_path`
+
+The exported schema covers client-side validation. Runtime validation remains authoritative for dynamic cross-field checks such as selector-key references. Contributors regenerating the checked-in artifact should run `bundle exec rake config:schema` in the core repo.
 
 ## Getting Started
 
diff --git a/src/content/docs/ruby-gem/reference/auto-source.mdx b/src/content/docs/ruby-gem/reference/auto-source.mdx
index 277db98e..459ab67d 100644
--- a/src/content/docs/ruby-gem/reference/auto-source.mdx
+++ b/src/content/docs/ruby-gem/reference/auto-source.mdx
@@ -23,12 +23,18 @@ To enable it, add `auto_source: {}` to your configuration:
 `auto_source` uses the following strategies to find content:
 
 1.  **`wordpress_api`:** Detects the `<link rel="https://api.w.org/">` tag used by WordPress and pulls posts from the REST API without parsing article HTML. See [WordPress API](/ruby-gem/reference/wordpress-api/).
-2.  **`schema`:** Parses `<script type="json/ld">` tags containing structured data (e.g., [Schema.org](https://schema.org/)).
-3.  **`semantic_html`:** Searches for semantic HTML5 tags like `<article>`, `<main>`, and `<section>`.
-4.  **`html`:** Analyzes the HTML structure to find frequently occurring selectors that are likely to contain the main content.
-5.  **json_state:** Single-page applications often stash pre-rendered article data in `<script type="application/json">` tags or global variables
+2.  **`sitemap`:** Automatically locates XML sitemap documents (`<link rel="sitemap">`, `/sitemap.xml`, or `/robots.txt`), filtering entries by priority and recency, with support for Google News tags (`<news:news>`).
+3.  **`meta_oembed`:** Extracts single-item articles, video pages, and media updates from OpenGraph/Twitter meta tags and resolves JSON oEmbed endpoints (`<link rel="alternate" type="application/json+oembed">`).
+4.  **`schema`:** Parses `<script type="json/ld">` tags containing structured data (e.g., [Schema.org](https://schema.org/)), extracting authors and publishers.
+5.  **`microdata`:** Extracts HTML Microdata annotations (`itemscope itemtype`).
+6.  **`microformats2`:** Parses Microformats2 `h-entry` markup, extracting `p-name`, `e-content`, `u-url`, `dt-published`, `p-author`, `p-category`, and `u-photo` / `u-featured` media.
+7.  **`semantic_html`:** Searches for semantic HTML5 tags like `<article>`, `<main>`, and `<section>`, with fallback clustering for anchorless lists.
+8.  **`html`:** Analyzes HTML structure to find frequently occurring item selectors, with tag-structure and class-clustering fallbacks.
+9.  **`json_state`:** Single-page applications often stash pre-rendered article data in `<script type="application/json">` tags or global variables
     such as `window.__NEXT_DATA__`, `window.__NUXT__`, or `window.STATE`. The JSON-state scraper walks those blobs, finds arrays with
-    `title`/`url` pairs, and converts them into the same hashes produced by `HtmlExtractor`.
+    `title`/`url` pairs, and converts them into feed items.
+
+`auto_source` also automatically extracts and prepends kicker/teaser labels to article titles when present.
 
 **`json_state` Limitations:** the scraper requires discoverable arrays of hashes containing clear `title` and `url` fields. Minified or
 obfuscated state objects, heavily encoded values, or blobs that require executing embedded functions are ignored.
@@ -51,16 +57,28 @@ Enable or disable specific scrapers and adjust their settings:
     scraper:
       wordpress_api:
         enabled: false # default: true
+      sitemap:
+        enabled: true # default: true
+        min_priority: 0.3 # default: 0.3
+        max_age_days: 30 # default: 30
+      meta_oembed:
+        enabled: true # default: true
       schema:
         enabled: false # default: true
+      microdata:
+        enabled: true # default: true
+      microformats2:
+        enabled: true # default: true
       semantic_html:
-        enabled: false # default: true
+        enabled: true # default: true
+        fallback_anchorless: true # default: true
       json_state:
         enabled: false # default: true
       html:
         enabled: true
         minimum_selector_frequency: 3 # default: 2
         use_top_selectors: 3 # default: 5
+        fallback_anchorless: true # default: true
   `}
   lang="yaml"
 />
diff --git a/src/content/docs/ruby-gem/reference/cli-reference.mdx b/src/content/docs/ruby-gem/reference/cli-reference.mdx
index 01c77e50..961c1845 100644
--- a/src/content/docs/ruby-gem/reference/cli-reference.mdx
+++ b/src/content/docs/ruby-gem/reference/cli-reference.mdx
@@ -17,21 +17,31 @@ The `html2rss` executable is the primary way to interact with the gem from your
 
 ### Auto
 
-Automatically discovers items from a page and prints the generated RSS feed to stdout.
+Automatically discovers items from a page and prints the generated RSS or JSONFeed to stdout.
 
 <Code
   code={`
   html2rss auto https://example.com/articles ; \
+  html2rss auto https://example.com/articles --format jsonfeed ; \
   html2rss auto https://example.com/app --strategy browserless --max-redirects 5 --max-requests 6 ; \
   BOTASAURUS_SCRAPER_URL="http://localhost:4010" html2rss auto https://example.com/protected --strategy botasaurus ; \
-  html2rss auto https://example.com/articles --items_selector ".post-card"
+  html2rss auto https://example.com/articles --items_selector ".post-card" ; \
+  html2rss auto --input sample.html ; \
+  html2rss auto https://example.com/articles --input sample.html
 `}
   lang="bash"
 />
 
-Command: `html2rss auto URL`
+Command: `html2rss auto [URL]`
 
-Default behavior is `--strategy auto`, which tries `faraday` then `botasaurus` then `browserless`.
+Available options:
+
+- `--strategy`: Optional request strategy (`auto`, `faraday`, `browserless`, `botasaurus`, `local_file`). Defaults to `auto`, which tries `faraday` -> `botasaurus` -> `browserless`.
+- `--format`: Output format for the auto-sourced feed (`rss` or `jsonfeed`). Defaults to `rss`.
+- `--items_selector`: Optional CSS selector hint for item extraction.
+- `--max-redirects`: Maximum redirects to follow per request.
+- `--max-requests`: Maximum requests to allow for this feed build (defaults to `4` for auto discovery).
+- `--input`: Local HTML file path to read input from without making network requests. When provided without a `URL`, `html2rss` attempts to detect the base URL from `<link rel="canonical">` or OpenGraph metadata in the HTML.
 
 #### URL Surface Guidance For `auto`
 
@@ -78,17 +88,17 @@ Start by changing the input URL to a direct listing/update page, then move to ex
 <Code
   code={`
   # 1) Start Browserless in the background
-  docker run -d --rm --name html2rss-browserless \
-    -p 3000:3000 \
-    -e "CONCURRENT=10" \
-    -e "TOKEN=6R0W53R135510" \
+  docker run -d --rm --name html2rss-browserless \\
+    -p 3000:3000 \\
+    -e "CONCURRENT=10" \\
+    -e "TOKEN=6R0W53R135510" \\
     ghcr.io/browserless/chromium
 
 # 2) Run html2rss against Browserless
 
-BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" \
- BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \
- html2rss auto https://example.com/updates --strategy browserless
+BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" \\
+BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \\
+html2rss auto https://example.com/updates --strategy browserless
 
 # 3) Stop Browserless when done
 
@@ -111,7 +121,7 @@ For custom Browserless endpoints, `BROWSERLESS_IO_API_TOKEN` is required.
 
 <Code
   code={`
-  BOTASAURUS_SCRAPER_URL="http://localhost:4010" \
+  BOTASAURUS_SCRAPER_URL="http://localhost:4010" \\
   html2rss auto https://example.com/updates --strategy botasaurus
 `}
   lang="bash"
@@ -135,18 +145,27 @@ Loads a YAML config, builds the feed, and prints the RSS XML to stdout.
   html2rss feed single.yml --strategy browserless ; \
   BOTASAURUS_SCRAPER_URL="http://localhost:4010" html2rss feed single.yml --strategy botasaurus ; \
   html2rss feed single.yml --max-redirects 5 --max-requests 6 ; \
-  html2rss feed single.yml --params id:42 foo:bar
+  html2rss feed single.yml --params id:42 foo:bar ; \
+  html2rss feed single.yml --input sample.html
 `}
   lang="bash"
 />
 
 Command: `html2rss feed YAML_FILE [feed_name]`
 
+Available options:
+
+- `--strategy`: Request strategy override (`auto`, `faraday`, `browserless`, `botasaurus`, `local_file`).
+- `--params`: Dynamic parameters passed as key-value pairs (e.g. `--params id:42 section:news`).
+- `--max-redirects`: Maximum redirects to follow per request.
+- `--max-requests`: Total request budget allowed for this feed build.
+- `--input`: Local HTML file path to read input from instead of making a network request.
+
 The CLI keeps `strategy` as a top-level override and writes runtime request limits into the generated config under `request`.
 
 ### Schema
 
-Prints the exported JSON Schema for the current gem version.
+Prints or writes the exported JSON Schema for the current gem version.
 
 <Code
   code={`
@@ -159,6 +178,11 @@ Prints the exported JSON Schema for the current gem version.
 
 Command: `html2rss schema`
 
+Available options:
+
+- `--pretty` / `--no-pretty`: Pretty-print the schema JSON (default: `true`).
+- `--write PATH`: Write the schema JSON directly to the given file path, creating any missing parent directories.
+
 ### Validate
 
 Validates a config with the runtime validator without generating a feed.
@@ -166,13 +190,18 @@ Validates a config with the runtime validator without generating a feed.
 <Code
   code={`
   html2rss validate single.yml ; \
-  html2rss validate feeds.yml my-first-feed
+  html2rss validate feeds.yml my-first-feed ; \
+  html2rss validate single.yml --params id:42
 `}
   lang="bash"
 />
 
 Command: `html2rss validate YAML_FILE [feed_name]`
 
+Available options:
+
+- `--params`: Dynamic parameters to interpolate before validation (default: `{}`).
+
 ### Help
 
 Displays the help message with available commands and options.
diff --git a/src/content/docs/ruby-gem/reference/configuration.mdx b/src/content/docs/ruby-gem/reference/configuration.mdx
index fc43dceb..9dad7c29 100644
--- a/src/content/docs/ruby-gem/reference/configuration.mdx
+++ b/src/content/docs/ruby-gem/reference/configuration.mdx
@@ -9,16 +9,19 @@ You can configure global defaults for `html2rss` using `Html2rss.configure`. Thi
 
 Global configuration is thread-safe and implements an RCU (Read-Copy-Update) mechanism: once configured, the global configuration instance is frozen and thread-safe.
 
-```ruby
-require 'html2rss'
+<Code
+  code={`
+  require 'html2rss'
 
 Html2rss.configure do |config|
-  config.log_level = :info
-  config.min_ttl = 60
-  config.default_strategy = :faraday
-  config.headers = { 'User-Agent' => 'MyCustomUserAgent/1.0' }
+config.log_level = :info
+config.min_ttl = 60
+config.default_strategy = :faraday
+config.headers = { 'User-Agent' => 'MyCustomUserAgent/1.0' }
 end
-```
+`}
+lang="ruby"
+/>
 
 ## Options
 
diff --git a/src/content/docs/ruby-gem/reference/selectors.mdx b/src/content/docs/ruby-gem/reference/selectors.mdx
index d25da5df..9b4e5578 100644
--- a/src/content/docs/ruby-gem/reference/selectors.mdx
+++ b/src/content/docs/ruby-gem/reference/selectors.mdx
@@ -61,34 +61,139 @@ Available options:
 
 ## Paginated Feeds
 
-`html2rss` can follow a single `rel="next"` pagination chain when you configure `selectors.items.pagination.max_pages`.
+Configure `selectors.items.pagination` to fetch items across multiple pages. `html2rss` supports several pagination strategies to handle different website architectures.
+
+### Common Options
+
+- **`strategy`**: The pagination strategy name (default: `rel_next`).
+- **`max_pages`**: The total page budget for the item selector chain, including the initial page (default: `5`).
+
+If you specify `pagination` as a simple integer (e.g., `pagination: 5`), it defaults to the `rel_next` strategy with the specified `max_pages`.
+
+---
+
+### Strategies
+
+#### 1. `rel_next` (Default)
+
+Follows standard HTML next page relationships via `<link rel="next">` or `<a rel="next">` tags.
+
+<Code
+  code={`
+  selectors:
+    items:
+      selector: "article"
+      pagination: 5 # or { strategy: rel_next, max_pages: 5 }
+  `}
+  lang="yml"
+/>
+
+#### 2. `custom_selector`
+
+Uses a custom CSS or XPath selector to locate the link pointing to the next page. It reads the element's `href` attribute or text content as the next URL.
+
+- **`selector`** (String, required): The CSS selector or XPath expression for the next-page element.
 
 <Code
   code={`
-  channel:
-    url: "https://example.com/news"
   selectors:
     items:
       selector: "article"
       pagination:
-        max_pages: 3
-    title:
-      selector: "h1"
-    url:
-      selector: "a"
-      extractor: "href"
+        strategy: custom_selector
+        selector: "a.next-page-link"
+        max_pages: 5
+  `}
+  lang="yml"
+/>
+
+#### 3. `url_template`
+
+Increments a page number in a query parameter or replaces a `{page}` token inside the URL template.
+
+- **`param`** (String, default: `page`): The name of the query parameter representing the page number.
+- **`start_page`** (Integer, default: `1`): The initial page number.
+- **`step`** (Integer, default: `1`): The step value to increment by for each subsequent page.
+
+If the initial URL contains the `{page}` placeholder, `html2rss` replaces `{page}` with the calculated page number. Otherwise, it appends/replaces the query parameter specified by `param`.
+
+<Code
+  code={`
+  selectors:
+    items:
+      selector: "article"
+      pagination:
+        strategy: url_template
+        param: "page"
+        start_page: 1
+        step: 1
+        max_pages: 5
+  `}
+  lang="yml"
+/>
+
+#### 4. `offset`
+
+Increments a numeric offset in a query parameter or replaces an `{offset}` token inside the URL template.
+
+- **`param`** (String, default: `offset`): The name of the query parameter representing the offset.
+- **`start_offset`** (Integer, default: `0`): The initial offset value.
+- **`increment`** (Integer, default: `20`): The offset value to add for each subsequent page.
+
+If the initial URL contains the `{offset}` placeholder, `html2rss` replaces `{offset}` with the calculated offset. Otherwise, it appends/replaces the query parameter specified by `param`.
+
+<Code
+  code={`
+  selectors:
+    items:
+      selector: "article"
+      pagination:
+        strategy: offset
+        param: "offset"
+        start_offset: 0
+        increment: 20
+        max_pages: 5
   `}
   lang="yml"
 />
 
-Behavior:
+#### 5. `json_cursor`
+
+Digs next-page URLs or cursor tokens directly from JSON response payloads.
+
+Requires configuring **either** `cursor_path` or `next_url_path`:
+
+- **`cursor_path`** (String): Dot-notation path to the cursor value in the JSON payload (e.g., `meta.next_cursor`). When present, `html2rss` appends/updates the query parameter specified by `param` (defaults to `cursor`) with the cursor value.
+- **`next_url_path`** (String): Dot-notation path to the next page URL in the JSON payload (e.g., `links.next`).
+- **`param`** (String, default: `cursor`): The query parameter name used with `cursor_path`.
+
+<Code
+  code={`
+  selectors:
+    items:
+      selector: "items"
+      pagination:
+        strategy: json_cursor
+        cursor_path: "meta.next_cursor" # or next_url_path: "links.next"
+        param: "cursor"
+        max_pages: 5
+  `}
+  lang="yml"
+/>
+
+---
 
-- `max_pages` is the total page budget for the item selector chain, including the initial page.
-- `max_pages` is capped by the system request ceiling of 10 pages per feed build.
-- Pagination follows strict `link[rel~="next"]` or `a[rel~="next"]` targets only.
-- Follow-up pages use the current page's effective origin after redirects.
-- Pagination stops when there is no next link, a page repeats, or the shared request budget is exhausted.
-- The same request safeguards apply to pagination and Browserless navigation, including timeout limits, redirect limits, response-size guards, and private-network denial.
+### Behavior & Request Budgeting
+
+- **Auto-budgeting**: The request budget (`max_requests`) is automatically calculated and adjusted based on your `max_pages` configuration so you do not need to manually configure `request.max_requests` under normal circumstances.
+- **System ceiling**: The absolute request limit is capped at `10` requests per build. If `max_pages` exceeds the system request ceiling, it will be clamped to the ceiling, and a warning will be logged.
+- **Stop conditions**: Pagination stops automatically if:
+  - The configured `max_pages` is reached.
+  - The request budget is exhausted.
+  - A page yields 0 new items.
+  - An already visited URL is encountered (loop protection).
+  - A network or extraction error occurs.
+- **Request safeguards**: All request safeguards apply to pagination (such as redirect limits, timeout boundaries, private-network denial, and response-size limits).
 
 ## RSS 2.0 Selectors
 
diff --git a/src/content/docs/ruby-gem/reference/strategy.mdx b/src/content/docs/ruby-gem/reference/strategy.mdx
index c8219ccd..921baaa5 100644
--- a/src/content/docs/ruby-gem/reference/strategy.mdx
+++ b/src/content/docs/ruby-gem/reference/strategy.mdx
@@ -11,6 +11,7 @@ The `strategy` key defines how `html2rss` fetches a website's content.
 - **`faraday`**: Makes a direct HTTP request. It is fast but does not execute JavaScript.
 - **`browserless`**: Renders the website in a headless Chrome browser, which is necessary for JavaScript-heavy sites.
 - **`botasaurus`**: Delegates fetching to a Botasaurus scrape API. This is opt-in and requires `BOTASAURUS_SCRAPER_URL`.
+- **`local_file`**: Reads HTML content directly from a local file on disk without making network requests.
 
 `strategy` is a top-level config key. Request-specific controls live under `request`.
 
@@ -22,6 +23,41 @@ The default strategy chain is:
 
 `faraday` -> `botasaurus` -> `browserless`
 
+Auto fallback shares one request budget across all strategy attempts. For pagination-heavy or dynamic pages, increase `request.max_requests` (or `--max-requests`) when retries exhaust the budget.
+
+Auto fallback decisions are hidden at the default `LOG_LEVEL=warn`; run with `LOG_LEVEL=info` to include them in CLI output.
+
+## `faraday`
+
+`faraday` is the standard static HTTP transport. When no custom `User-Agent` header is supplied in `headers`, `html2rss` sends `html2rss/<VERSION>` by default.
+
+## `local_file`
+
+`local_file` parses content directly from a local file on disk. It is designed for offline testing, local fixtures, and CLI `--input` workflows.
+
+Because no remote network connection is established, `local_file` skips remote network guards and SSRF preflight checks.
+
+### Configuration
+
+<Code
+  code={`
+  strategy: local_file
+  request:
+    local_file_path: "tmp/page.html"
+  channel:
+    url: "https://example.com/articles"
+  selectors:
+    items:
+      selector: ".article"
+    title:
+      selector: "h2"
+    url:
+      selector: "a"
+      extractor: "href"
+  `}
+  lang="yml"
+/>
+
 ## `browserless`
 
 To use the `browserless` strategy, you need a running instance of [Browserless.io](https://www.browserless.io/).
@@ -32,11 +68,11 @@ You can run a local Browserless.io instance using Docker:
 
 <Code
   code={`
-  docker run \
-    --rm \
-    -p 3000:3000 \
-    -e "CONCURRENT=10" \
-    -e "TOKEN=6R0W53R135510" \
+  docker run \\
+    --rm \\
+    -p 3000:3000 \\
+    -e "CONCURRENT=10" \\
+    -e "TOKEN=6R0W53R135510" \\
     ghcr.io/browserless/chromium
 `}
   lang="sh"
@@ -52,6 +88,7 @@ Set the `strategy` at the top level of your feed configuration and put request c
   request:
     max_redirects: 5
     max_requests: 6
+    total_timeout_seconds: 30
   channel:
     url: "https://example.com/app"
   selectors:
@@ -70,10 +107,12 @@ Set the `strategy` at the top level of your feed configuration and put request c
 
 Use this split consistently:
 
-- `strategy`: selects `auto`, `faraday`, `browserless`, or `botasaurus`
-- `headers`: top-level headers shared by all strategies
-- `request.max_redirects`: redirect limit for the request session
-- `request.max_requests`: total request budget for the whole feed build
+- `strategy`: selects `auto`, `faraday`, `browserless`, `botasaurus`, or `local_file`
+- `headers`: top-level headers shared by remote strategies (defaults to `html2rss/<VERSION>` User-Agent)
+- `request.max_redirects`: redirect limit for the request session (default: `5`)
+- `request.max_requests`: total request budget for the whole feed build (default: `10`)
+- `request.total_timeout_seconds`: maximum total wall-clock budget for the entire feed build
+- `request.local_file_path`: file path for `local_file` strategy
 - `request.browserless.*`: Browserless-only options
 - `request.botasaurus.*`: Botasaurus-only options
 
@@ -87,6 +126,7 @@ Example:
   request:
     max_redirects: 5
     max_requests: 6
+    total_timeout_seconds: 45
     browserless:
       preload:
         wait_after_ms: 5000
@@ -141,13 +181,13 @@ You can also specify the strategy on the command line:
 <Code
   code={`
   # Set environment variables for your Browserless.io instance
-  BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" \
-  BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \
-  html2rss feed my_config.yml --strategy browserless ; \
-  html2rss feed my_config.yml --max-redirects 5 --max-requests 6 ; \
-  html2rss feed my_config.yml
+  BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" \\
+  BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \\
+  html2rss feed my_config.yml --strategy browserless
+
+html2rss feed my_config.yml --max-redirects 5 --max-requests 6
 `}
-  lang="sh"
+lang="bash"
 />
 
 ### Browserless Troubleshooting
@@ -169,49 +209,67 @@ For custom Browserless websocket endpoints, `BROWSERLESS_IO_API_TOKEN` is mandat
 - `strategy: botasaurus`
 - `BOTASAURUS_SCRAPER_URL` set to your Botasaurus scrape API base URL (for example `http://localhost:4010`)
 
+html2rss still enforces local request policy preflight and timeout budget. Botasaurus handles browser navigation/rendering internals, so some policy details are delegated to upstream execution.
+
 ### Configuration
 
 <Code
   code={`
+  channel:
+    url: "https://example.com"
   strategy: botasaurus
+  auto_source: {}
   request:
-    max_redirects: 5
-    max_requests: 6
     botasaurus:
       navigation_mode: auto
       max_retries: 2
       headless: false
-  channel:
-    url: "https://example.com/protected-listing"
-  auto_source: {}
   `}
   lang="yml"
 />
 
 Supported `request.botasaurus` options:
 
-- `navigation_mode` (`auto`, `get`, `google_get`, `google_get_bypass`)
-- `max_retries` (`0..3`)
-- `wait_for_selector`
-- `wait_timeout_seconds`
-- `block_images`
-- `block_images_and_css`
-- `wait_for_complete_page_load`
-- `headless`
-- `proxy`
-- `user_agent`
-- `window_size` (two integers, for example `[1920, 1080]`)
-- `lang`
+- `navigation_mode` (`auto`, `get`, `google_get`, `google_get_bypass`; default `auto`)
+- `max_retries` (`0..3`; default `2`)
+- `wait_for_selector` (string)
+- `wait_timeout_seconds` (integer)
+- `block_images` (boolean)
+- `block_images_and_css` (boolean)
+- `wait_for_complete_page_load` (boolean)
+- `headless` (boolean, default `false`)
+- `proxy` (string)
+- `user_agent` (string)
+- `window_size` (two-item integer array, for example `[1920, 1080]`)
+- `lang` (string, for example `en-US`)
+
+### Request payload shape
+
+Example scrape-API payload shape:
+
+<Code
+  code={`
+  {
+    "url": "https://example.com",
+    "navigation_mode": "auto",
+    "max_retries": 2,
+    "headless": false
+  }
+  `}
+  lang="json"
+/>
 
 ### Command-Line Usage
 
 <Code
   code={`
-  BOTASAURUS_SCRAPER_URL="http://localhost:4010" \
-  html2rss auto https://example.com/updates --strategy botasaurus ; \
-  html2rss feed my_config.yml --strategy botasaurus
+  BOTASAURUS_SCRAPER_URL="http://localhost:4010" \\
+  html2rss auto https://example.com/updates --strategy botasaurus
+
+BOTASAURUS_SCRAPER_URL="http://localhost:4010" \\
+html2rss feed my_config.yml --strategy botasaurus
 `}
-  lang="sh"
+lang="bash"
 />
 
 ---
diff --git a/src/content/docs/web-application/guides/setup-for-development.mdx b/src/content/docs/web-application/guides/setup-for-development.mdx
index 61c3f7ab..ecf7eee7 100644
--- a/src/content/docs/web-application/guides/setup-for-development.mdx
+++ b/src/content/docs/web-application/guides/setup-for-development.mdx
@@ -19,26 +19,25 @@ All you need to do is install and run Docker.
 
 # Run the image and name it html2rss-web-dev:
 
-docker run \
- --detach \
- --mount type=bind,source=$(pwd)/config,target=/app/config \
- --name html2rss-web-dev \
- html2rss-web
+docker run \\
+--detach \\
+--mount type=bind,source=$(pwd)/config,target=/app/config \\
+--name html2rss-web-dev \\
+html2rss-web
 
-# Open an interactive TTY with the shell \`sh\`:
+# Open an interactive TTY with the shell:
 
 docker exec -ti html2rss-web-dev sh
 
 # Stop and clean up the container
 
-docker stop html2rss-web-dev && \
- docker rm html2rss-web-dev
+docker stop html2rss-web-dev && docker rm html2rss-web-dev
 
 # Remove the image
 
 docker rmi html2rss-web
 `}
-lang="sh"
+lang="bash"
 />
 
 ### Using installed Ruby
diff --git a/src/content/docs/web-application/index.mdx b/src/content/docs/web-application/index.mdx
index abbc1420..1d8cb2bf 100644
--- a/src/content/docs/web-application/index.mdx
+++ b/src/content/docs/web-application/index.mdx
@@ -38,7 +38,7 @@ The scraping and feed-building engine is provided by the Ruby gem [`html2rss`](h
 Once your instance is running, learn how to use its core features:
 
 - **[Use automatic feed generation](/web-application/guides/use-automatic-feed-generation/)**: create feeds from page URLs
-- **[Use included configs](/web-application/guides/use-included-configs/)**: use the built-in Feed Directory as a fallback
+- **[Use the Feed Directory](/web-application/guides/use-the-feed-directory/)**: use the built-in Feed Directory as a fallback
 - **[Monitoring](/web-application/reference/monitoring/)**: keep your instance healthy
 
 ## For Integrations