From 1740bac6d55f1de53f033e548d641f09981c0b17 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 5 Sep 2026 13:38:36 +0200
Subject: [PATCH] docs: reshape hero path into Getting Started funnel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Point readers through Docker auto-source quickstart → deployment →
advanced feeds; fold MCP/CLI/skill docs onto the same path and redirect
legacy /web-application/getting-started/.
---
 AGENTS.md                                     |  18 +-
 astro.config.mjs                              |  25 +-
 .../docs/DockerComposeSnippet.astro           |   3 +-
 src/content/docs/common-use-cases.mdx         |   2 +-
 src/content/docs/creating-custom-feeds.mdx    | 236 ++++--------------
 src/content/docs/feed-directory/index.mdx     |   2 +-
 .../docs/get-involved/contributing.mdx        |   2 +-
 src/content/docs/getting-started.mdx          |  65 +++--
 src/content/docs/index.mdx                    |  53 ++--
 .../ruby-gem/guides/advanced-features.mdx     |   2 +-
 .../ruby-gem/guides/ai-agent-workflows.mdx    | 102 +++-----
 .../guides/backward-compatibility.mdx         |   6 +-
 .../guides/capturing-feed-configs.mdx         |   8 +-
 .../ruby-gem/guides/custom-http-requests.mdx  |   2 +-
 .../ruby-gem/guides/dynamic-parameters.mdx    |   2 +-
 .../ruby-gem/guides/managing-feed-configs.mdx |  10 +-
 .../docs/ruby-gem/reference/auto-source.mdx   |   6 +-
 .../docs/ruby-gem/reference/cli-reference.mdx |  54 ++--
 .../docs/ruby-gem/reference/mcp-server.mdx    | 174 +++++--------
 .../docs/ruby-gem/reference/strategy.mdx      |   4 +-
 .../ruby-gem/tutorials/your-first-feed.mdx    |   4 +-
 .../docs/troubleshooting/troubleshooting.mdx  |   4 +-
 src/content/docs/web-application/concepts.mdx |  48 ++++
 .../docs/web-application/deployment.mdx       | 135 +++++-----
 .../docs/web-application/getting-started.mdx  | 107 --------
 src/content/docs/web-application/index.mdx    |  52 ++--
 26 files changed, 431 insertions(+), 695 deletions(-)
 create mode 100644 src/content/docs/web-application/concepts.mdx
 delete mode 100644 src/content/docs/web-application/getting-started.mdx

diff --git a/AGENTS.md b/AGENTS.md
index 2443448d..37c2c83f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -86,18 +86,18 @@ Preferred verification flow for docs/content changes:
 
 ### User Journey Funnel
 
-Maintain a directed "funnel" for documentation to maximize user success and conversion:
+Keep docs pointed along one success path:
 
-1.  **Phase 1: Quickstart (Local Demo)** — The primary entry point. Run `html2rss-web` with Docker and generate a feed from a page URL in minutes.
-2.  **Phase 2: Production (Deployment)** — The goal for invested users. Move to a stable, production-ready instance.
-3.  **Phase 3: Refinement (Custom Configs)** — Secondary optimization. Author custom YAML configs only when automatic generation needs precise control.
+1. **Getting Started** — Run `html2rss-web` with Docker; paste a page URL; open the generated feed.
+2. **Deployment** — Production compose, tokens, LAN HTTP vs HTTPS reverse proxy.
+3. **Advanced Feeds** — Custom YAML only when auto-source needs precise control (escape hatch).
 
-**Rules for Funnel Maintenance:**
+**Rules:**
 
-- Avoid branching paths in introductory pages; always point toward the next phase in the funnel.
-- Define "html2rss-web" as the primary interface and "page-to-RSS" as the primary workflow.
-- Use "Feed Directory" consistently to refer to the pre-built feed catalog; avoid terms like "catalog", "included feeds", or "packaged configs" in user-facing docs.
-- Do not introduce new terminology (e.g., "toolkit") or unrelated infrastructure concepts (e.g., "custom domains") unless they are essential to a specific guide.
+- Introductory pages hand off to the next step; do not fork the reader into parallel “primary” paths.
+- `html2rss-web` is the primary interface; page-URL auto-source is the primary workflow.
+- Say **Feed Directory** for the curated feed list; avoid “catalog”, “included feeds”, or “packaged configs” in user-facing copy.
+- Do not invent product terms or infrastructure side quests unless a specific operator guide needs them.
 
 ### Code Snippets
 
diff --git a/astro.config.mjs b/astro.config.mjs
index 81b8a06d..3fd7913f 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -13,6 +13,7 @@ export default defineConfig({
     "/components/html2rss": "/ruby-gem/",
     "/components/html2rss-configs": "/creating-custom-feeds/",
     "/components": "/",
+    "/web-application/getting-started/": "/getting-started/",
     "/web-application/how-to/deployment": "/web-application/deployment/",
     "/web-application/how-to/automatic-updates": "/web-application/deployment/",
     "/web-application/how-to/use-automatic-feed-generation":
@@ -267,15 +268,10 @@ export default defineConfig({
           link: "/feed-directory/",
         },
         {
-          label: "Create Custom Feeds",
-          link: "/creating-custom-feeds/",
-        },
-        {
-          label: "Web Application",
-          collapsed: true,
+          label: "Self-Hosting & Deployment",
+          collapsed: false,
           items: [
             "web-application",
-            "web-application/getting-started",
             "web-application/deployment",
             {
               label: "Guides",
@@ -288,7 +284,20 @@ export default defineConfig({
           ],
         },
         {
-          label: "Ruby Gem",
+          label: "How It Works",
+          link: "/web-application/concepts/",
+        },
+        {
+          label: "AI Agent Workflows & MCP",
+          collapsed: false,
+          items: ["ruby-gem/guides/ai-agent-workflows", "ruby-gem/reference/mcp-server"],
+        },
+        {
+          label: "Advanced Feeds",
+          link: "/creating-custom-feeds/",
+        },
+        {
+          label: "Ruby Gem & CLI",
           collapsed: true,
           items: [
             "ruby-gem",
diff --git a/src/components/docs/DockerComposeSnippet.astro b/src/components/docs/DockerComposeSnippet.astro
index f8b58ebd..5a8bd437 100644
--- a/src/components/docs/DockerComposeSnippet.astro
+++ b/src/components/docs/DockerComposeSnippet.astro
@@ -13,9 +13,10 @@ const snippets: Record<Props["variant"], string> = {
   html2rss-web:
     image: ${webImage}
     ports:
-      - "127.0.0.1:4000:4000"
+      - "4000:4000"
     environment:
       RACK_ENV: development
+      AUTO_SOURCE_ENABLED: "true"
       HTML2RSS_ACCESS_TOKEN: CHANGE_ME_ADMIN_TOKEN
       BOTASAURUS_SCRAPER_URL: http://botasaurus:4010
 
diff --git a/src/content/docs/common-use-cases.mdx b/src/content/docs/common-use-cases.mdx
index 931b1a8a..9ee56f75 100644
--- a/src/content/docs/common-use-cases.mdx
+++ b/src/content/docs/common-use-cases.mdx
@@ -91,6 +91,6 @@ Follow multiple open source projects and their updates.
 
 ## Next Steps
 
-- **[Run html2rss-web with Docker](/web-application/getting-started/)** to verify your own instance.
+- **[Run html2rss-web with Docker](/getting-started/)** to verify your own instance.
 - **[Use automatic feed generation](/web-application/guides/use-automatic-feed-generation/)** when you want direct page-URL conversion.
 - **[Create custom feeds](/creating-custom-feeds/)** when you need stable, reviewable extraction rules.
diff --git a/src/content/docs/creating-custom-feeds.mdx b/src/content/docs/creating-custom-feeds.mdx
index f9651a0c..31b098d2 100644
--- a/src/content/docs/creating-custom-feeds.mdx
+++ b/src/content/docs/creating-custom-feeds.mdx
@@ -1,81 +1,38 @@
 ---
-title: "Creating Custom Feeds"
-description: "Learn to write custom YAML configurations for RSS feeds when auto-sourcing isn't enough."
+title: "Advanced Feeds (Escape Hatch)"
+description: "Write YAML configs when auto-source is not enough; mount feeds.yml; contribute to html2rss-configs."
 sidebar:
   order: 2
 ---
 
 import { Aside, Code } from "@astrojs/starlight/components";
 
-When existing feeds or auto-sourcing are not enough, write a YAML config for the site you want to follow.
+Prefer [Getting Started](/getting-started/) (URL paste) and the [Feed Directory](/feed-directory/) first. Use a custom YAML config when auto-source misses items you care about, or when you need reviewable selectors.
 
-**Prerequisites:** You should be familiar with the [Getting Started](/getting-started/) guide before diving into custom configurations.
-
-<Aside type="tip" title="Use this guide when you need more control">
-  Reach for a custom config when you need stable, reviewable extraction rules or generated output misses
-  important content.
+<Aside type="tip" title="Escape hatch">
+  Agents can draft configs via MCP (`capture` → `test` → `apply`) or the
+  [`html2rss-config`](https://github.com/html2rss/html2rss-configs/tree/master/.agents/skills/html2rss-config)
+  skill. You still mount or publish the YAML yourself.
 </Aside>
 
----
-
-## When to Use Custom Configs
-
-**Use custom configs when:**
-
-- **Auto-sourcing doesn't work** for the website you want to follow
-- **Existing feeds are incomplete** or missing important content
-- **You need specific formatting** or data extraction
-- **The website has complex structure** that requires custom selectors
-- **You want to combine data** from multiple sources
-
-## Recommended Workflow
-
-1. **Inspect the live page** in your browser developer tools
-2. **Optionally draft with capture** — `html2rss capture https://example.com/articles > your-config.yml` (see [Capturing Feed Configs](/ruby-gem/guides/capturing-feed-configs/))
-3. **Write or refine the smallest useful config** that extracts items, titles, and links
-4. **Validate the config** with `html2rss validate your-config.yml`
-5. **Render the feed** with `html2rss feed your-config.yml`
-6. **Add it to `html2rss-web`** so you can use it through your normal instance
-7. **Escalate request strategy when needed**: use Botasaurus (`strategy: botasaurus` or `auto` with `BOTASAURUS_SCRAPER_URL`) only when troubleshooting requires browser rendering
-
-This order keeps iteration fast and makes it easier to see whether the problem is the page structure, your
-selectors, or the fetch strategy.
-
----
-
-## How It Works
+## Recommended workflow
 
-A config file is a simple "recipe" that tells html2rss:
+1. Inspect the live page (browser DevTools).
+2. Optionally draft: `html2rss capture https://example.com/articles > your-config.yml`
+3. Validate: `html2rss validate your-config.yml`
+4. Live-check: `html2rss test your-config.yml`, then ship with `html2rss apply your-config.yml`
+5. Mount into `html2rss-web` or contribute to html2rss-configs
+6. Escalate to `strategy: botasaurus` (or `auto` with `BOTASAURUS_SCRAPER_URL`) only when Faraday is not enough
 
-1. **Which website** to look at
-2. **What content** to find
-3. **How to organize** it into an RSS feed
+`html2rss feed` is a Thor alias for `apply`. `html2rss auto` aliases `scrape` (one-shot, no YAML).
 
-### The `channel` Block
-
-This tells html2rss basic information about your feed - like giving it a name and telling it which website to look at.
-
-**Example:**
+## Minimal config
 
 <Code
   code={`
   channel:
     url: https://example.com/blog
-    title: My Awesome Blog
-  `}
-  lang="yaml"
-/>
-
-This says: "Look at this website and call the feed 'My Awesome Blog'"
-
-### The `selectors` Block
-
-This is where you tell the html2rss engine exactly what to find on the page. You use CSS selectors (like you might use in web design) to point to specific parts of the webpage.
-
-**Example:**
-
-<Code
-  code={`
+    title: My Blog
   selectors:
     items:
       selector: "article.post"
@@ -84,123 +41,56 @@ This is where you tell the html2rss engine exactly what to find on the page. You
     url:
       selector: "h2 a"
       extractor: "href"
-  `}
+`}
   lang="yaml"
 />
 
-This says: "Find each article, get the title from the h2 anchor, and get the link from the same h2 anchor's href attribute"
-
-**Need more details?** Check our [complete guide to selectors](/ruby-gem/reference/selectors/) for all the options.
-
----
-
-## Your First Config
+Details: [Selectors](/ruby-gem/reference/selectors/), [Strategy](/ruby-gem/reference/strategy/).
 
-**Step 1:** Inspect the website you want to create a feed for. Start with your browser's developer tools to inspect the live DOM. "View Page Source" can still help, but it may miss JavaScript-rendered content.
-
-**Step 2:** Create a file called `example.com.yml` with this basic structure:
+## Test locally
 
 <Code
   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"
+  html2rss validate your-config.yml && \\
+  html2rss apply your-config.yml && \\
+  html2rss apply your-config.yml --input sample.html
+`}
+  lang="bash"
 />
 
-**Step 3:** Test it with your html2rss-web instance or the [Ruby gem](/ruby-gem/installation/).
+Raise `--max-redirects` / `--max-requests` only when the site needs more budget.
 
-**Need help?** See our [troubleshooting guide](/troubleshooting/troubleshooting/) for common issues.
+## Mount on html2rss-web
 
----
-
-## Configuration Options
-
-html2rss supports many configuration options:
-
-- **Basic selectors** for title, description, and links
-- **Advanced features** like custom headers and dynamic parameters
-- **Multiple strategies** for different types of websites
-- **Post-processing** to clean up extracted content
-
-**See our [Ruby Gem Reference](/ruby-gem/reference/)** for complete documentation.
-
----
-
-## Testing Your Config
-
-**Before sharing your config, test it:**
-
-1. **Validate the config first:**
-
-<Code code={`html2rss validate your-config.yml`} lang="bash" />
-
-2. **Then render the feed with the Ruby gem:**
-
-<Code code={`html2rss feed your-config.yml`} lang="bash" />
-
-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
-
-5. **Check the output:** Make sure all items have titles, links, and descriptions
-
-### Useful CLI flags when a site is difficult
-
-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.
+Bind-mount a feeds file (see production Compose comments):
 
 <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
+  volumes:
+    - type: bind
+      source: ./config/feeds.yml
+      target: /app/config/feeds.yml
+      read_only: true
 `}
-  lang="bash"
+  lang="yaml"
 />
 
-Keep these values tight. Raise them only when the site proves it needs more.
-
-## Add It To html2rss-web
-
-Once the config works locally, add it to your `feeds.yml` or shared config repository and restart your
-instance. Then open the feed through your normal `html2rss-web` URL and confirm it behaves the same way
-there.
-
----
-
-## Sharing Your Config
+Feeds are served as `.rss` / `.json` paths on your instance (for example `/example.com/blog.rss`).
 
-**Help the community by sharing your config:**
+## Contribute to the Feed Directory
 
-1. Go to [html2rss-configs on GitHub](https://github.com/html2rss/html2rss-configs)
-2. Click "Fork" → "Add file" → Create `domain.com/name.yml` under `lib/html2rss/configs/`
-3. Include top-level `directory.topics`, `directory.title`, and mirror `channel.title` (required for Feed Directory configs). Optional `directory.summary` (max 160 characters).
-4. Paste your config → "Commit new file" → "Open pull request"
+1. Fork [html2rss-configs](https://github.com/html2rss/html2rss-configs)
+2. Add `lib/html2rss/configs/<domain>/<name>.yml`
+3. Include `directory.topics`, `directory.title`, and matching `channel.title`
+4. Open a pull request
 
-Example catalog metadata:
+Example metadata:
 
 <Code
   code={`
   directory:
     topics:
       - tech
-      - research
     title: Example — News
     summary: Short description of what this feed covers.
   channel:
@@ -219,43 +109,11 @@ Example catalog metadata:
   lang="yaml"
 />
 
-Allowed `directory.topics` values (prefer 1–2 primary topics): `sports`, `energy`, `tech`, `science`, `news`, `entertainment`, `jobs`, `finance`, `security`, `travel`, `environment`, `consumer`, `civic`, `product`, `research`.
-
-Use `{Organization} — {Feed surface}` for `directory.title` (for example, `Anthropic — News`). The [Feed Directory](/feed-directory/) lists configs from a running `html2rss-web` instance.
-
-**Need help?** See our [contribution guide](/get-involved/contributing/) for detailed instructions.
-
----
-
-## Troubleshooting
-
-**Common issues when writing configs:**
-
-- **No items found?** Check your selectors with browser tools (F12) - the `items.selector` might not match the page structure
-- **Invalid YAML?** Use spaces, not tabs, and ensure proper indentation
-- **Website not loading?** Check the URL and try accessing it in your browser
-- **Missing content?** Try a browser-based rendering strategy during troubleshooting
-- **Wrong data extracted?** Verify your selectors are pointing to the right elements
-
-**Need more help?** See our [comprehensive troubleshooting guide](/troubleshooting/troubleshooting/) or ask in [GitHub Discussions](https://github.com/orgs/html2rss/discussions).
-
----
-
-## Next Steps
-
-**🎉 Congratulations!** You've learned the basics of creating html2rss configuration files.
-
-### What's Next?
-
-**For Beginners:**
-
-- **[Run html2rss-web with Docker](/web-application/getting-started/)** - Use the newest integrated behavior
-- **[Learn more about selectors](/ruby-gem/reference/selectors/)** - Master CSS selectors
-- **[Submit your config via GitHub Web](https://github.com/html2rss/html2rss-configs)** - No Git knowledge required!
+Allowed topics: `sports`, `energy`, `tech`, `science`, `news`, `entertainment`, `jobs`, `finance`, `security`, `travel`, `environment`, `consumer`, `civic`, `product`, `research`.
 
-**For Contributors:**
+## Next
 
-- **[Browse existing configs](https://github.com/html2rss/html2rss-configs/tree/master/lib/html2rss/configs)** - See real examples
-- **[Join discussions](https://github.com/orgs/html2rss/discussions)** - Connect with other users
-- **[Learn about strategies](/ruby-gem/reference/strategy/)** - Decide when to use static vs JavaScript/browser-based extraction
-- **[Learn advanced features](/ruby-gem/guides/advanced-features/)** - Take your configs to the next level
+- [Getting Started](/getting-started/)
+- [MCP / AI workflows](/ruby-gem/guides/ai-agent-workflows/)
+- [Contributing](/get-involved/contributing/)
+- [Troubleshooting](/troubleshooting/troubleshooting/)
diff --git a/src/content/docs/feed-directory/index.mdx b/src/content/docs/feed-directory/index.mdx
index 8b5944d2..028653ba 100644
--- a/src/content/docs/feed-directory/index.mdx
+++ b/src/content/docs/feed-directory/index.mdx
@@ -17,7 +17,7 @@ import FeedDirectory from "../../../components/feed-directory/FeedDirectory.astr
 
 Browse pre-built feed configs by site name. The list loads from the active `html2rss-web` instance (`GET /api/v1/configs`). Search, filter by topic or language, and paginate results. Export OPML for the current filter set when subscribing to several feeds at once.
 
-Need the main onboarding path first? Start with [Getting Started](/web-application/getting-started/) and create a feed from your own page URL. The directory below is the fallback path when a curated config already covers your site.
+Need the main onboarding path first? Start with [Getting Started](/getting-started/) and create a feed from your own page URL. The directory below is the fallback path when a curated config already covers your site.
 
 Need a different instance? Use **Change instance** in the directory header, self-host your own, or find more options on the [community-run wiki](https://github.com/html2rss/html2rss-web/wiki/Instances).
 
diff --git a/src/content/docs/get-involved/contributing.mdx b/src/content/docs/get-involved/contributing.mdx
index b764dbf2..5c13db80 100644
--- a/src/content/docs/get-involved/contributing.mdx
+++ b/src/content/docs/get-involved/contributing.mdx
@@ -35,7 +35,7 @@ Are you missing an RSS feed for a website? You can create your own feed config a
 
 **Want to test your config first?** Use the [Ruby gem](/ruby-gem/installation/) to test it locally:
 
-<Code code={`html2rss feed your-config.yml`} lang="bash" />
+<Code code={`html2rss apply your-config.yml`} lang="bash" />
 
 ### 2. Host a Public Instance
 
diff --git a/src/content/docs/getting-started.mdx b/src/content/docs/getting-started.mdx
index a9f97d7e..25e3dfb3 100644
--- a/src/content/docs/getting-started.mdx
+++ b/src/content/docs/getting-started.mdx
@@ -1,44 +1,63 @@
 ---
 title: "Getting Started"
-description: "Start html2rss-web locally, paste your own URL, enter one token, and open the generated feed."
+description: "Run html2rss-web with Docker, paste a page URL, enter the demo token, and open your generated RSS feed."
 sidebar:
   order: 1
 ---
 
 import { Code } from "@astrojs/starlight/components";
 
-This page points to the main onboarding flow.
+import MinimalDockerCompose from "../../components/docs/MinimalDockerCompose.astro";
 
-## Start Here
+Run `html2rss-web` locally with Docker, create one feed from a page URL, then move to production setup when you want stable hosting.
 
-If you want the recommended path, go to [Run html2rss-web with Docker](/web-application/getting-started/).
+## What you need
 
-That guide is the canonical setup flow for:
+- Docker
+- About two minutes for first success
 
-- running `html2rss-web` locally
-- creating a feed from your own page URL
-- using the demo token first
-- moving to production setup only after first success
-- choosing fallback or custom-config paths only when needed
+## Step 1: Folder and compose file
 
-## Quick Shortcuts
+<Code
+  code={`
+  mkdir html2rss-web && \\
+  cd html2rss-web
+`}
+  lang="bash"
+/>
 
-- **[Run html2rss-web with Docker](/web-application/getting-started/)**: recommended first step
-- **[Use automatic feed generation](/web-application/guides/use-automatic-feed-generation/)**: understand the normal direct page-URL workflow
-- **[Use the Feed Directory](/web-application/guides/use-the-feed-directory/)**: fallback when the Feed Directory already covers your site
-- **[Create Custom Feeds](/creating-custom-feeds/)**: write configs when you need more control
-- **[Troubleshooting Guide](/troubleshooting/troubleshooting/)**: fix startup or extraction problems
+Use the quickstart stack from [`docker-compose.quickstart.yml`](https://github.com/html2rss/html2rss-web/blob/main/docker-compose.quickstart.yml). Save it as `docker-compose.yml`:
 
-## Using the Ruby CLI
+<MinimalDockerCompose />
 
-If you are working directly with the gem instead of `html2rss-web`, start with:
+That stack runs:
 
-<Code code={`html2rss auto https://example.com/blog`} lang="bash" />
+- `html2rss-web` on port `4000`
+- companion `botasaurus` for JavaScript-rendered pages
+- `AUTO_SOURCE_ENABLED=true` so URL-to-RSS works without YAML
+- demo access token `CHANGE_ME_ADMIN_TOKEN`
 
-For strategy behavior and manual overrides, see the [Strategy reference](/ruby-gem/reference/strategy/).
+## Step 2: Start
 
-If the target site is unusually redirect-heavy or needs extra follow-up requests, the CLI also supports:
+<Code code={`docker compose up -d`} lang="bash" />
 
-<Code code={`html2rss auto https://example.com/blog --max-redirects 10 --max-requests 5`} lang="bash" />
+## Step 3: Create a feed
 
-For config-driven runs, the same flags are available on `html2rss feed`.
+1. Open `http://localhost:4000` (or `http://<LAN_IP>:4000/` on your network).
+2. Paste a **listing** URL — newsroom, changelog, releases, category, or archive page (not a bare homepage).
+3. When prompted, enter `CHANGE_ME_ADMIN_TOKEN`.
+4. Open the generated feed URL (`.rss` or `.json`).
+
+## Next
+
+1. **[Deployment](/web-application/deployment/)** — production compose, real tokens, LAN HTTP vs HTTPS proxy.
+2. **[Feed Directory](/web-application/guides/use-the-feed-directory/)** — subscribe when a curated feed already covers the site.
+3. **[Advanced Feeds](/creating-custom-feeds/)** — custom YAML only when auto-source needs tighter selectors.
+
+## Ruby CLI (optional)
+
+Without the web UI, one-shot auto-source from the gem:
+
+<Code code={`html2rss scrape https://example.com/blog`} lang="bash" />
+
+`html2rss auto` is a Thor alias for `scrape`. Strategy details: [Strategy reference](/ruby-gem/reference/strategy/).
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
index e70b6f84..5df1934a 100644
--- a/src/content/docs/index.mdx
+++ b/src/content/docs/index.mdx
@@ -1,46 +1,31 @@
 ---
-title: "Turn Any Website Into an RSS Feed"
-description: "Run html2rss-web with Docker, paste your own page URL, enter one token, and open the generated feed."
+title: "Turn any website into an RSS feed"
+description: "Paste a page URL into html2rss-web, get RSS or JSON Feed. Auto-source, Feed Directory, and MCP for agents."
 ---
 
-`html2rss` turns any website into a stable RSS feed. Run the 10-minute quickstart to see it in action, then move to a production setup when you are ready to stay updated.
+`html2rss` turns websites into stable RSS and JSON feeds. The recommended path is **html2rss-web**: paste a page URL, enter an access token, and subscribe to the generated feed. Auto-source (with the Botasaurus companion for JavaScript-heavy sites) handles extraction without hand-written selectors.
 
-## Start Here
+## Start here
 
-**Quickstart:** [Run html2rss-web with Docker](/web-application/getting-started/)
+**[Getting Started](/getting-started/)** — Docker quickstart in about two minutes.
 
-The canonical path to your first feed:
+Then:
 
-1.  **Phase 1: Local Demo** — Run the stack and generate a feed from any page URL in minutes.
-2.  **Phase 2: Production** — Move to [Deployment](/web-application/deployment/) for a stable, production-ready instance.
-3.  **Phase 3: Refinement** — Create [Custom Feeds](/creating-custom-feeds/) only when you need absolute control over extraction.
+1. **[Deployment](/web-application/deployment/)** — production tokens and hosting.
+2. **[Feed Directory](/feed-directory/)** — curated feeds from your instance.
+3. **[Advanced Feeds](/creating-custom-feeds/)** — YAML escape hatch when you need exact selectors.
 
-## Deep Dives
+## Also useful
 
-### Features & Operations
+- **[How It Works](/web-application/concepts/)** — auto-source, tokens, Botasaurus, ecosystem map.
+- **[AI Agent Workflows & MCP](/ruby-gem/guides/ai-agent-workflows/)** — native MCP tools and the `html2rss-config` curation skill.
+- **[Monitoring](/web-application/reference/monitoring/)** — health checks and Sentry.
 
-- **[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.
+## Typical uses
 
-### Engine & Customization
+- Follow blogs and news without social algorithms.
+- Track product changelogs and release notes.
+- Monitor job boards and community forums.
+- Subscribe when a site does not publish its own feed.
 
-- **[Creating Custom Feeds](/creating-custom-feeds/)**: Write and test your own scraping rules.
-- **[Selectors Reference](/ruby-gem/reference/selectors/)**: Learn the CSS/XPath matching rules.
-- **[Strategy Reference](/ruby-gem/reference/strategy/)**: Handle static vs. JavaScript-heavy pages.
-- **[Ruby Gem Reference](/ruby-gem/)**: Full engine API documentation and CLI usage.
-
-## What People Use It For
-
-- Follow blogs and news sites without social media algorithms.
-- Track product updates, changelogs, and release notes.
-- Monitor job postings and community forums.
-- Subscribe to any site that does not publish its own feed.
-
-## Practical Notes
-
-- **Start with Docker**: It is the recommended way to run `html2rss-web`.
-- **Start with a Page URL**: Automatic generation is the primary workflow.
-- **Feed Directory**: Check the [Feed Directory](/feed-directory/) first; the site you want might already be covered.
-
-**Need help?** Continue to the [troubleshooting guide](/troubleshooting/troubleshooting/) or join [GitHub Discussions](https://github.com/orgs/html2rss/discussions).
+**Need help?** [Troubleshooting](/troubleshooting/troubleshooting/) or [GitHub Discussions](https://github.com/orgs/html2rss/discussions).
diff --git a/src/content/docs/ruby-gem/guides/advanced-features.mdx b/src/content/docs/ruby-gem/guides/advanced-features.mdx
index f89cc46c..3f2ae9f3 100644
--- a/src/content/docs/ruby-gem/guides/advanced-features.mdx
+++ b/src/content/docs/ruby-gem/guides/advanced-features.mdx
@@ -81,7 +81,7 @@ Optimize requests with appropriate headers:
 
 ### Enable Debug Logging
 
-<Code code={`LOG_LEVEL=debug html2rss feed config.yml`} lang="bash" />
+<Code code={`LOG_LEVEL=debug html2rss apply config.yml`} lang="bash" />
 
 ### Web Application Health Checks
 
diff --git a/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx b/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx
index 75926be7..7ead82f0 100644
--- a/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx
+++ b/src/content/docs/ruby-gem/guides/ai-agent-workflows.mdx
@@ -1,40 +1,27 @@
 ---
 title: AI Agent Workflows with MCP
-description: Guide to integrating html2rss with AI agents, Claude Desktop, and Cursor using the Model Context Protocol (MCP).
+description: Wire Cursor or Claude Desktop to html2rss MCP; use bare verbs and the html2rss-config skill.
 ---
 
 import { Code } from "@astrojs/starlight/components";
 
-`html2rss` includes a native [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server. This allows AI assistants in tools like Cursor, Claude Desktop, and GitHub Copilot to scrape pages, capture feed configurations, and generate RSS feeds autonomously.
+`html2rss` includes a native [MCP](https://modelcontextprotocol.io/) server so agents can scrape pages, capture YAML, test, and ship RSS without parsing CLI stdout.
 
-## Why Use MCP?
+## Why MCP
 
-Without MCP, agents must invoke shell commands, manage output buffers, and parse unstructured text. With MCP:
+- Tools and schemas are discovered by the client.
+- Every result is an envelope: `ok`, `next_step`, `guidance`, `payload`.
+- `html2rss://runtime` reports whether Botasaurus is configured on **this** MCP process (`botasaurus_configured` only).
 
-- The agent automatically discovers available tools, arguments, and return types.
-- Responses are structured envelopes (`ok`, `next_step`, `guidance`, `payload`) — articles in `payload.items`, YAML in `payload.yaml`, RSS in `payload.rss`.
-- Agents can inspect, capture, validate, and verify feeds iteratively in a closed feedback loop.
-- `html2rss://runtime` reports whether Botasaurus is configured in this MCP process (boolean only).
+Full tool schemas: [MCP Server Reference](/ruby-gem/reference/mcp-server/).
 
-## Client Setup
+## Client setup
 
-### 1. Version Manager Shims (mise, asdf, rbenv, chruby)
+Invoke through your version manager so Ruby and gem bins resolve correctly.
 
-Because version managers manage Ruby runtimes and gem paths through environment shims, configure your MCP client to invoke the version manager executable rather than a bare `html2rss` command.
+### Cursor
 
-<Code
-  code={`
-  # Install the gem in your global environment
-  mise exec -- gem install html2rss
-  # Or add it to your project Gemfile
-  mise exec -- bundle add html2rss
-`}
-  lang="bash"
-/>
-
-### 2. Cursor Configuration
-
-Add `html2rss` to your Cursor MCP settings (`~/.cursor/mcp.json` or `.cursor/mcp.json`):
+`~/.cursor/mcp.json` or `.cursor/mcp.json`:
 
 <Code
   code={`
@@ -53,64 +40,55 @@ Add `html2rss` to your Cursor MCP settings (`~/.cursor/mcp.json` or `.cursor/mcp
   lang="json"
 />
 
-_(If using `asdf`, replace `"command": "mise"` with `"asdf"` and `"args": ["exec", "html2rss", "mcp"]`.)_
+For `asdf`, use `"command": "asdf"` and `"args": ["exec", "html2rss", "mcp"]`.
 
-### 3. Claude Desktop Configuration
+### Claude Desktop
 
-Add `html2rss` to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):
+Same server block in Claude’s desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS).
 
-<Code
-  code={`
-  {
-    "mcpServers": {
-      "html2rss": {
-        "command": "mise",
-        "args": ["exec", "--", "html2rss", "mcp"],
-        "env": {
-          "BOTASAURUS_SCRAPER_URL": "http://127.0.0.1:4010"
-        }
-      }
-    }
-  }
-`}
-  lang="json"
-/>
+Put `BOTASAURUS_SCRAPER_URL` in the MCP `env` block — a shell export does not reach the MCP process. Confirm with `html2rss://runtime`.
+
+## Golden loops
+
+**Articles now:** `scrape` (or `batch_scrape`). `strategy: "auto"` already falls back to Botasaurus when configured — do not retry with explicit `faraday` after `auto`. Empty items can still be success; follow `next_step`.
 
-## Autonomous Workflow Patterns
+**Durable YAML:** optional `inspect` → `recon` → `capture` → `test` → `apply`.
 
-**Budget:** `scrape_url` is one call. Durable config is `capture_config` → `validate_config` → `apply_config`. Call `inspect_url` only when the result is weak or you need recon (final URL, status, https→http, native RSS/Atom).
+- `capture` returns draft YAML in `payload.yaml`.
+- For html2rss-configs destinations, add `directory.topics` and explicit channel `title` / `url`.
+- `test` asserts live extraction; then `apply` ships RSS (`isError` on zero items).
 
-### Pattern A: One-Shot Content Scraping
+**Config already in hand:** `validate` → `test` → `apply`.
 
-When an agent needs articles immediately without saving a feed configuration:
+Weak scrape/capture → `inspect`. When alternates warrant it, follow `next_step` to `recon`.
 
-1. Call `scrape_url` with `strategy: "auto"`. Auto runs Faraday then Botasaurus when `BOTASAURUS_SCRAPER_URL` is set on the MCP process, prefers native RSS/Atom when present, and may rewrite a weak homepage URL via entry resolution.
-2. An empty item list is still success for articles-now. Read `payload.items`. Follow `next_step` (including `read_runtime` / `html2rss://runtime` when Botasaurus is unset).
-3. Call `inspect_url` when the result is weak or you need recon (`final_url`, `status`, `scheme_downgrade`, `alternate_feeds`, `surface_category`). Follow `next_step` — often `scrape_url` when `alternate_feeds` is present.
+## html2rss-config skill
 
-### Pattern B: Iterative Feed Config Authoring
+For curated configs in the [html2rss-configs](https://github.com/html2rss/html2rss-configs) repo, use the repo skill at `.agents/skills/html2rss-config/SKILL.md`. It routes `new` / `repair` / `expand` modes and points at:
 
-When an agent is tasked with creating a durable YAML feed configuration:
+| Helper                 | Role                             |
+| ---------------------- | -------------------------------- |
+| `scripts/add_config`   | Create from a URL or file        |
+| `scripts/batch_recon`  | Parallel BUILD/DEFER/DROP ledger |
+| `scripts/check_config` | CLI `validate` + `test`          |
+| `scripts/probe_rss`    | Native RSS via `recon`           |
 
-1. **Capture:** Call `capture_config`. YAML is `payload.yaml` (`items` + `enhance: true`). Check `payload.articles_count` and `has_selectors`.
-2. **Recon (optional):** Call `inspect_url` for `final_url`, `status`, `scheme_downgrade`, `alternate_feeds`, and `surface_category` if the draft is weak. Follow `next_step` (often `scrape_url` when alternates are present).
-3. **Rewrite:** If the destination is html2rss-configs, add `directory.topics` and explicit channel `title`/`url`. Strive to keep `enhance: true` (set `false` only when chrome leaks into items).
-4. **Validate:** Pass `yaml` (or `config`) to `validate_config`. Exactly one of those arguments.
-5. **Apply:** Call `apply_config`. `isError` plus `payload.item_count: 0` means the config is not shippable — channel title in the XML is not success.
+YAML lives under `lib/html2rss/configs/<domain>/`. Quality gates stay in that repo’s `AGENTS.md`.
 
-## JavaScript-Rendered Sites (Botasaurus)
+## Botasaurus for agents
 
-For dynamic JavaScript single-page applications or sites protected by anti-bot measures, launch the Botasaurus scrape service:
+Start the companion scraper (from `html2rss` or your web Compose stack), then point the MCP `env` at it:
 
 <Code
   code={`
+  # From the html2rss gem repo:
   docker compose -f docker-compose.botasaurus.yml up -d
 `}
   lang="bash"
 />
 
-Put `BOTASAURUS_SCRAPER_URL` (typically `http://127.0.0.1:4010`) in the MCP server `env` block above — a shell export does not reach the Cursor/Claude MCP process. Confirm with `html2rss://runtime` (`botasaurus_configured: true`). AutoFallback then hops without a second tool call.
+Typical URL: `http://127.0.0.1:4010`.
 
-## Daemon logs (stderr)
+## Daemon logs
 
-`html2rss mcp` uses stdout for JSON-RPC, so the daemon logs to **stderr**. Unless you set `LOG_LEVEL`, the MCP process uses `info` (the gem library default stays `warn`). A foreground watcher sees the start banner, each tool call, and pipeline fallbacks. Use `LOG_LEVEL=debug` for more detail or `LOG_LEVEL=warn` to quiet it.
+`html2rss mcp` uses stdout for JSON-RPC and logs to stderr. Set `LOG_LEVEL=debug` for more detail or `LOG_LEVEL=warn` to quiet.
diff --git a/src/content/docs/ruby-gem/guides/backward-compatibility.mdx b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
index 1a69217b..8de5059b 100644
--- a/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
+++ b/src/content/docs/ruby-gem/guides/backward-compatibility.mdx
@@ -12,9 +12,9 @@ This page outlines breaking changes, purged legacy aliases, and migration steps
 Upgrade notes for configs and integrators targeting gem **0.27.0** (current `master` after `0.26.0`):
 
 1. **MCP result envelope** — Every MCP tool returns `{ ok, next_step, guidance, payload }` in text and `structuredContent`. Read `payload.items`, `payload.yaml`, and `payload.rss`; scrape text is not a raw item array.
-2. **MCP AutoFallback** — `scrape_url` and `capture_config` with `strategy: "auto"` run Faraday → Botasaurus in one call. `inspect_url` with `auto` stays on Faraday (pin `botasaurus` when you need browser rendering for inspect).
-3. **Capture output** — `html2rss capture` and MCP `capture_config` emit an items selector plus `enhance: true` only (no per-field title/url/description selector soup). Capture stamps `strategy:` when AutoFallback selects a concrete transport.
-4. **CLI `--explain`** — `html2rss auto --explain` and `html2rss capture --explain` print telemetry JSON on stderr; stdout stays the feed or YAML. Status includes `admission_drops` when Cleanup dropped items.
+2. **MCP AutoFallback** — `scrape` and `capture` with `strategy: "auto"` run Faraday → Botasaurus in one call. `inspect` with `auto` stays on Faraday (pin `botasaurus` when you need browser rendering for inspect).
+3. **Capture output** — `html2rss capture` and MCP `capture` emit an items selector plus `enhance: true` only (no per-field title/url/description selector soup). Capture stamps `strategy:` when AutoFallback selects a concrete transport.
+4. **CLI `--explain`** — `html2rss scrape --explain` and `html2rss capture --explain` print telemetry JSON on stderr; stdout stays the feed or YAML. Status includes `admission_drops` when Cleanup dropped items.
 5. **`Html2rss.auto_feed_result`** — URL-only auto discovery returns `FeedResult` with the same `status` telemetry as config builds.
 6. **`request.botasaurus` OpenAPI 2.0** — Keys must match the scrape-API `ScrapeRequest` (unknown keys rejected). Use `scroll: true` (not `scroll_to_bottom`), `window_size: { width:, height: }` (not a two-item array), and `wait_timeout_seconds` in `1..30`. See [Strategy](/ruby-gem/reference/strategy/#botasaurus).
 7. **Botasaurus wire format** — Client expects OpenAPI 2.0 `ScrapeSuccess` / `ScrapeError` envelopes from the scrape API.
diff --git a/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx b/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx
index 8f11d655..cad7f99c 100644
--- a/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx
+++ b/src/content/docs/ruby-gem/guides/capturing-feed-configs.mdx
@@ -80,7 +80,7 @@ See the [CLI reference](/ruby-gem/reference/cli-reference/#capture) for the full
 2. **Discover** — AutoSource extracts admitted articles
 3. **Segment** — SST Segmenter strategies `:list` → `:cluster` → `:semantic`
 4. **Gate** — emit an items selector only when enough articles match
-5. **Assemble** — `{ items: { selector:, enhance: true } }` plus channel. When AutoFallback selects a concrete transport (or you pin one), Capture **stamps** `strategy:` into the YAML so later `html2rss feed` / `Html2rss.feed` replay the same transport.
+5. **Assemble** — `{ items: { selector:, enhance: true } }` plus channel. When AutoFallback selects a concrete transport (or you pin one), Capture **stamps** `strategy:` into the YAML so later `html2rss apply` / `Html2rss.feed` replay the same transport.
 
 When the quality gate fails, selectors are omitted (`has_selectors: false`) rather than inventing attribute selectors. Hint with `--items_selector` or refine by hand.
 
@@ -93,18 +93,18 @@ Capture focuses on:
 
 It does not invent per-field title/url/description selectors, author, `published_at`, categories, or enclosure selectors. `enhance: true` fills missing article fields via the HTML article extractor at feed-build time.
 
-MCP `capture_config` returns that YAML in `payload.yaml`. `validate_config` / `apply_config` accept the YAML string (XOR a config hash). `apply_config` is `isError` when the feed has zero items (`payload.item_count`).
+MCP `capture` returns that YAML in `payload.yaml`. `validate` / `apply` accept the YAML string (XOR a config hash). `apply` is `isError` when the feed has zero items (`payload.item_count`).
 
 ## Recommended Follow-Up
 
 1. Validate: `html2rss validate my-feed.yml`
-2. Render: `html2rss feed my-feed.yml`
+2. Render: `html2rss apply my-feed.yml`
 3. Tighten the items selector, strategy, or `request.botasaurus` options if needed
 4. For Feed Directory contributions, add `directory.topics` and keep `enhance: true` unless chrome leaks (see [Creating Custom Feeds](/creating-custom-feeds/#sharing-your-config))
 
 ## Related
 
 - [CLI reference — Capture](/ruby-gem/reference/cli-reference/#capture)
-- [AI agent workflows (MCP `capture_config`)](/ruby-gem/guides/ai-agent-workflows/)
+- [AI agent workflows (MCP `capture`)](/ruby-gem/guides/ai-agent-workflows/)
 - [Creating custom feeds](/creating-custom-feeds/)
 - [Auto Source](/ruby-gem/reference/auto-source/)
diff --git a/src/content/docs/ruby-gem/guides/custom-http-requests.mdx b/src/content/docs/ruby-gem/guides/custom-http-requests.mdx
index 91110c28..81594728 100644
--- a/src/content/docs/ruby-gem/guides/custom-http-requests.mdx
+++ b/src/content/docs/ruby-gem/guides/custom-http-requests.mdx
@@ -206,7 +206,7 @@ Test your configuration to ensure headers work correctly:
   code={`
   curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.example.com/posts && \
-  html2rss feed your-config.yml
+  html2rss apply your-config.yml
 `}
   lang="bash"
 />
diff --git a/src/content/docs/ruby-gem/guides/dynamic-parameters.mdx b/src/content/docs/ruby-gem/guides/dynamic-parameters.mdx
index e7e149a3..70f22bc2 100644
--- a/src/content/docs/ruby-gem/guides/dynamic-parameters.mdx
+++ b/src/content/docs/ruby-gem/guides/dynamic-parameters.mdx
@@ -31,7 +31,7 @@ You can add dynamic parameters to the `channel` and `headers` values. This is us
 
 You can then pass the values for these parameters when you run `html2rss`:
 
-<Code code={`html2rss feed the_feed_config.yml --params id:42 foo:bar`} lang="bash" />
+<Code code={`html2rss apply the_feed_config.yml --params id:42 foo:bar`} lang="bash" />
 
 ---
 
diff --git a/src/content/docs/ruby-gem/guides/managing-feed-configs.mdx b/src/content/docs/ruby-gem/guides/managing-feed-configs.mdx
index 950aa938..d8d515a2 100644
--- a/src/content/docs/ruby-gem/guides/managing-feed-configs.mdx
+++ b/src/content/docs/ruby-gem/guides/managing-feed-configs.mdx
@@ -1,6 +1,6 @@
 ---
 title: Managing Feed Configs
-description: "Learn how to manage feed configurations with YAML files. Organize, version control, and maintain your html2rss feed configurations effectively."
+description: "Learn how to manage feed configurations with YAML files. Organize, version control, and maintain your html2rss apply configurations effectively."
 ---
 
 import { Code } from "@astrojs/starlight/components";
@@ -80,10 +80,10 @@ Prefer `Html2rss.feed_result` when one scrape must render as both RSS and JSON F
 
 - `scraper_tallies`, `selected_strategy`, `attempt_count`, `strategy_attempts` (auto-fallback attempts; empty outside `strategy: auto`)
 - `admission_drops` (Cleanup reason → count)
-- `entry_url` / `scrape_url` (pasted vs effective URL after entry resolution)
+- `entry_url` / `scrape` (pasted vs effective URL after entry resolution)
 - `entry_resolution` (`applied`, `probe_count`, `reason`, optional `winner_score`)
 
-For URL-only auto discovery, `Html2rss.auto_feed_result(url)` returns the same `FeedResult` (CLI `html2rss auto --explain` prints `status.to_h` on stderr).
+For URL-only auto discovery, `Html2rss.auto_feed_result(url)` returns the same `FeedResult` (CLI `html2rss scrape --explain` prints `status.to_h` on stderr).
 
 <Code
   code={`
@@ -104,8 +104,8 @@ Depth and method contracts: [YARD for `html2rss`](https://www.rubydoc.info/gems/
 
 <Code
   code={`
-  html2rss feed feeds.yml my-first-feed ; \
-  html2rss feed single.yml
+  html2rss apply feeds.yml my-first-feed ; \
+  html2rss apply single.yml
 `}
   lang="sh"
 />
diff --git a/src/content/docs/ruby-gem/reference/auto-source.mdx b/src/content/docs/ruby-gem/reference/auto-source.mdx
index c09d39ae..1ec09d9d 100644
--- a/src/content/docs/ruby-gem/reference/auto-source.mdx
+++ b/src/content/docs/ruby-gem/reference/auto-source.mdx
@@ -44,7 +44,7 @@ What each scraper does:
 
 After scrapers, **Cleanup** is the admission gate: merge, dedupe, hard-exclude non-article destinations, drop junk titles, trim to `limit`. Scoring ranks and demotes; it does not refill `limit` after Cleanup.
 
-Drop reasons (counts) land on `Html2rss::Status#admission_drops`. Print them with `html2rss auto URL --explain` (JSON on stderr; the feed stays on stdout). Prefer `Html2rss.auto_feed_result` in Ruby when you need that status object.
+Drop reasons (counts) land on `Html2rss::Status#admission_drops`. Print them with `html2rss scrape URL --explain` (JSON on stderr; the feed stays on stdout). Prefer `Html2rss.auto_feed_result` in Ruby when you need that status object.
 
 `auto_source` also prepends kicker/teaser labels to titles when present, and discovers channel-level `author` and `image` (favicon, touch-icon, or OpenGraph images) from the host page.
 
@@ -64,12 +64,12 @@ Resolution runs when enabled, the page is not a blocked surface, and any of:
 - a weak surface (`high_entropy_surface`, `app_shell`, `unsupported_surface`)
 - at least half of the articles came from `native_feed`
 
-Inspect results with `html2rss auto URL --explain` or `Html2rss::Status#to_h`:
+Inspect results with `html2rss scrape URL --explain` or `Html2rss::Status#to_h`:
 
 | Field              | Meaning                                                         |
 | ------------------ | --------------------------------------------------------------- |
 | `entry_url`        | Pasted / channel URL                                            |
-| `scrape_url`       | Effective fetch URL after resolution                            |
+| `scrape`           | Effective fetch URL after resolution                            |
 | `entry_resolution` | `{ applied, probe_count, reason }` plus optional `winner_score` |
 
 `entry_resolution.applied: true` means a winner was selected. The sticky rewrite still requires a successful retry extract.
diff --git a/src/content/docs/ruby-gem/reference/cli-reference.mdx b/src/content/docs/ruby-gem/reference/cli-reference.mdx
index dae1b54b..3554048f 100644
--- a/src/content/docs/ruby-gem/reference/cli-reference.mdx
+++ b/src/content/docs/ruby-gem/reference/cli-reference.mdx
@@ -15,25 +15,25 @@ For detailed documentation on the Ruby API, please refer to the official YARD do
 
 The `html2rss` executable is the primary way to interact with the gem from your terminal.
 
-### Auto
+### Scrape
 
-Automatically discovers items from a page and prints the generated RSS or JSONFeed to stdout.
+Automatically discovers items from a page and prints the generated RSS or JSON Feed to stdout. (`html2rss auto` is a Thor alias.)
 
 <Code
   code={`
-  html2rss auto https://example.com/articles ; \\
-  html2rss auto https://example.com/articles --format jsonfeed ; \\
-  html2rss auto https://example.com/articles --limit 10 ; \\
-  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 --explain ; \\
-  html2rss auto --input sample.html ; \\
-  html2rss auto https://example.com/articles --input sample.html
+  html2rss scrape https://example.com/articles ; \\
+  html2rss scrape https://example.com/articles --format jsonfeed ; \\
+  html2rss scrape https://example.com/articles --limit 10 ; \\
+  BOTASAURUS_SCRAPER_URL="http://localhost:4010" html2rss scrape https://example.com/protected --strategy botasaurus ; \\
+  html2rss scrape https://example.com/articles --items_selector ".post-card" ; \\
+  html2rss scrape https://example.com/articles --explain ; \\
+  html2rss scrape --input sample.html ; \\
+  html2rss scrape https://example.com/articles --input sample.html
 `}
   lang="bash"
 />
 
-Command: `html2rss auto [URL]`
+Command: `html2rss scrape [URL]`
 
 Available options:
 
@@ -46,9 +46,9 @@ Available options:
 - `--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.
 - `--explain`: Print `Html2rss::Status` JSON to stderr (`version`, `dedup_dropped`, and when present `scraper_tallies`, `selected_strategy`, `attempt_count`, `strategy_attempts`, `admission_drops`, `entry_url`, `scrape_url`, `entry_resolution`). Stdout stays the RSS or JSON Feed.
 
-#### URL Surface Guidance For `auto`
+#### URL surface guidance for `scrape`
 
-`auto` works best when the input URL already exposes a server-rendered list of entries.
+`scrape` works best when the input URL already exposes a server-rendered list of entries.
 
 - High-success surfaces:
   - newsroom or press listing pages
@@ -62,9 +62,9 @@ Available options:
 
 When possible, pass a direct listing/update URL instead of a top-level homepage or app entrypoint.
 
-#### Failure Outcomes You Should Expect
+#### Failure outcomes
 
-When no extractable items are found, `auto` classifies likely causes instead of only returning a generic message:
+When no extractable items are found, `scrape` classifies likely causes instead of only returning a generic message:
 
 - `blocked surface likely (anti-bot or interstitial)`:
   - try a more specific public listing URL or configure `BOTASAURUS_SCRAPER_URL`
@@ -91,7 +91,7 @@ Start by changing the input URL to a direct listing/update page, then move to ex
 <Code
   code={`
   BOTASAURUS_SCRAPER_URL="http://localhost:4010" \\
-  html2rss auto https://example.com/updates --strategy botasaurus
+  html2rss scrape https://example.com/updates --strategy botasaurus
 `}
   lang="bash"
 />
@@ -102,24 +102,24 @@ If you see a Botasaurus configuration error, check:
 - `BOTASAURUS_SCRAPER_URL` is a valid URL
 - the Botasaurus scrape API is reachable from the shell environment running `html2rss`
 
-### Feed
+### Apply
 
-Loads a YAML config, builds the feed, and prints the RSS XML to stdout.
+Loads a YAML config, builds the feed, and prints the RSS XML to stdout. (`html2rss feed` is a Thor alias.)
 
 <Code
   code={`
-  html2rss feed single.yml ; \\
-  html2rss feed feeds.yml my-first-feed ; \\
-  html2rss feed single.yml --strategy auto ; \\
-  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 --input sample.html
+  html2rss apply single.yml ; \\
+  html2rss apply feeds.yml my-first-feed ; \\
+  html2rss apply single.yml --strategy auto ; \\
+  BOTASAURUS_SCRAPER_URL="http://localhost:4010" html2rss apply single.yml --strategy botasaurus ; \\
+  html2rss apply single.yml --max-redirects 5 --max-requests 6 ; \\
+  html2rss apply single.yml --params id:42 foo:bar ; \\
+  html2rss apply single.yml --input sample.html
 `}
   lang="bash"
 />
 
-Command: `html2rss feed YAML_FILE [feed_name]`
+Command: `html2rss apply YAML_FILE [feed_name]`
 
 Available options:
 
@@ -158,7 +158,7 @@ Available options:
 - `--input`: Local HTML file path to read input from without making network requests.
 - `--explain`: Print capture quality JSON to stderr (`articles_count`, `channel_title`, `has_selectors`, `segment_strategy`, `selected_strategy`, `admission_drops`). Stdout stays YAML.
 
-When AutoFallback (or a pinned strategy) selects a concrete transport, the printed YAML includes a top-level `strategy:` so later `html2rss feed` uses the same hop.
+When AutoFallback (or a pinned strategy) selects a concrete transport, the printed YAML includes a top-level `strategy:` so later `html2rss apply` uses the same hop.
 
 ### MCP
 
diff --git a/src/content/docs/ruby-gem/reference/mcp-server.mdx b/src/content/docs/ruby-gem/reference/mcp-server.mdx
index 4cc809fd..41540aa1 100644
--- a/src/content/docs/ruby-gem/reference/mcp-server.mdx
+++ b/src/content/docs/ruby-gem/reference/mcp-server.mdx
@@ -1,60 +1,48 @@
 ---
 title: MCP Server Reference
-description: Complete protocol reference for the html2rss Model Context Protocol (MCP) server, tools, resources, prompts, and transports.
+description: Model Context Protocol tools, resources, prompts, and transports for the html2rss gem.
 ---
 
 import { Code } from "@astrojs/starlight/components";
 
-`html2rss` includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes gem capabilities directly to AI agents, clients, and IDEs (such as Cursor, Claude Desktop, and GitHub Copilot).
+`html2rss` ships a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for AI agents and IDEs (Cursor, Claude Desktop, Copilot).
 
-## Overview
-
-The MCP server allows AI agents to inspect pages, capture reusable feed configurations, validate configs, and generate feeds without executing ad-hoc shell scripts or parsing CLI output.
+## Start
 
 <Code
   code={`
-  # Start with standard I/O transport (default for AI desktop clients)
+  # stdio (default for desktop clients)
   html2rss mcp
-  # Start with local HTTP transport (loopback only)
+  # HTTP on loopback only
   html2rss mcp --transport http --port 8080
 `}
   lang="bash"
 />
 
-## Transports & Security
-
-The MCP server supports two transport mechanisms:
-
-| Transport   | Command                                     | Default Port | Description                                                                     |
-| :---------- | :------------------------------------------ | :----------- | :------------------------------------------------------------------------------ |
-| **`stdio`** | `html2rss mcp --transport stdio`            | N/A          | Standard input/output communication. Recommended for Cursor and Claude Desktop. |
-| **`http`**  | `html2rss mcp --transport http --port 8080` | `8080`       | Streamable HTTP transport bound strictly to `127.0.0.1` (loopback only).        |
+| Transport | Command                                     | Notes                                                        |
+| --------- | ------------------------------------------- | ------------------------------------------------------------ |
+| `stdio`   | `html2rss mcp`                              | Recommended for Cursor / Claude Desktop                      |
+| `http`    | `html2rss mcp --transport http --port 8080` | Bound to `127.0.0.1` only; needs `rack`, `rackup`, `webrick` |
 
-### Security & Dependencies for HTTP
+Daemon logs go to **stderr** (stdout is JSON-RPC). Default `LOG_LEVEL` for the MCP process is `info` unless you set it.
 
-- **Loopback binding:** The HTTP transport only binds to `127.0.0.1`. Never expose it to public interfaces without authentication and reverse proxy origin controls.
-- **Dependencies:** The HTTP transport requires the `rack`, `rackup`, and `webrick` gems. If they are not present, starting the server raises a descriptive `LoadError`.
-- **Logging:** stdio JSON-RPC uses stdout. The daemon logs to stderr and defaults to `LOG_LEVEL=info` unless `LOG_LEVEL` is set (`debug` for more, `warn` to quiet).
+## Strategy
 
-## Strategy Resolution in MCP
+`scrape` and `capture` with `strategy: "auto"` run Faraday → Botasaurus AutoFallback in one call. Prefer native RSS/Atom when present; weak homepage URLs may be rewritten via entry resolution.
 
-`scrape_url` and `capture_config` with `strategy: "auto"` (the default) run Faraday → Botasaurus AutoFallback in one call. That path prefers native RSS/Atom when present and may run entry URL resolution on weak homepage/hub extracts — see [Auto Source](/ruby-gem/reference/auto-source/) and [Strategy](/ruby-gem/reference/strategy/#auto-default).
+`inspect` with `auto` stays on Faraday. Pin `strategy: "botasaurus"` when inspect needs browser rendering.
 
-`inspect_url` with `auto` uses Faraday for a cheap diagnostic. Pin `strategy: "botasaurus"` when you need browser rendering for inspect. Inspect reports head `rel=alternate` feeds only (no `/feed` path guessing).
-
-Read `html2rss://runtime` for `botasaurus_configured` (boolean only). Set `BOTASAURUS_SCRAPER_URL` on the **MCP process** env (see [AI agent workflows](/ruby-gem/guides/ai-agent-workflows/)).
-
-**Tool-call budget:** `scrape_url` = 1 call. Durable config = `capture_config` → `validate_config` → `apply_config`. Call `inspect_url` only when scrape/capture is weak or you need recon. Follow envelope `next_step` / `guidance`.
+Read `html2rss://runtime` for `botasaurus_configured` (boolean only). Set `BOTASAURUS_SCRAPER_URL` on the **MCP process** env.
 
 ## Result envelope
 
-Every tool returns the same JSON object in both the text content and `structuredContent`:
+Every tool returns one JSON object in text content and `structuredContent`:
 
 <Code
   code={`
   {
     "ok": true,
-    "next_step": "validate_config",
+    "next_step": "test",
     "guidance": "...",
     "payload": {}
   }
@@ -62,112 +50,88 @@ Every tool returns the same JSON object in both the text content and `structured
   lang="json"
 />
 
-`isError` matches `ok: false`. Scrape results expose articles in `payload.items`.
+`isError` matches `ok: false`. Articles live in `payload.items`; YAML in `payload.yaml`; RSS in `payload.rss`.
+
+`next_step` is one of: `done`, `inspect`, `recon`, `validate`, `apply`, `scrape`, `capture`, `read_runtime`, `test`.
 
-`next_step` is one of: `done`, `inspect_url`, `validate_config`, `apply_config`, `scrape_url`, `capture_config`, `read_runtime`.
+## Tools (7 bare verbs + batch trio)
 
-## Tools Reference
+Golden path for durable YAML: `inspect` (optional) → `recon` → `capture` → `test` → `apply`. One-shot articles: `scrape`. Schema-only side door: `validate`.
 
-The server registers 5 primary tools for AI agent orchestration.
+### `scrape`
 
-### `scrape_url`
+One-shot article extraction as JSON Feed items (no saved config).
 
-One-shot article extraction as JSON Feed items. Use when you need articles immediately without authoring or saving a YAML feed config.
+- **Parameters:** `url` (required); `strategy` (`auto` / `faraday` / `botasaurus`, default `auto`); `limit` (default `25`); optional `items_selector`
+- **Payload:** `items`, plus totals / strategy fields when present
+- Empty items can still be `ok: true` — follow `next_step` / `guidance`
 
-- **Parameters:**
-  - `url` _(string, required)_: Source page URL to scrape.
-  - `strategy` _(string, optional)_: Request strategy (`auto`, `faraday`, `botasaurus`). Default: `auto`.
-  - `limit` _(integer, optional)_: Maximum articles to keep. Default: `25`.
-  - `items_selector` _(string, optional)_: CSS selector hint for items.
-- **Return value:** Envelope with `payload.items` (JSON Feed article objects: `title`, `url`, `description`, `published_at`, `author`, `image`, `categories`). Also `payload.total`, `requested_strategy`, `channel_title`, and `admission_drops` when present.
-- **Error handling:** Unhandled exceptions return `isError: true` with `payload.class` / `payload.message`. An empty item list is still success (`ok: true`; follow `next_step`, which may be `inspect_url` or `read_runtime`).
+### `inspect`
 
-### `inspect_url`
+Diagnostics: final URL, status, scheme downgrade, `rel=alternate` feeds, surface category, admission drops.
 
-Diagnostic page analysis plus recon from the same fetch. `auto` uses Faraday; pin `botasaurus` when you need browser rendering.
+- **Parameters:** `url` (required); `strategy` (default `auto`)
+- Follow `next_step` — often `recon` when alternates warrant it, or `scrape` / `capture`
 
-- **Parameters:**
-  - `url` _(string, required)_: Source page URL.
-  - `strategy` _(string, optional)_: Request strategy (`auto`, `faraday`, `botasaurus`). Default: `auto`.
-- **Return value:** Envelope whose `payload` is the diagnostic object:
-  - `requested_url` / `final_url`: requested URL vs `Response#url` after redirects.
-  - `status`: HTTP status when the strategy reports one.
-  - `scheme_downgrade`: `true` when the fetch went https → http.
-  - `alternate_feeds`: `rel=alternate` RSS/Atom links from the document head (no `/feed` path guessing).
-  - `surface_category`: page surface class (listing, weak, blocked, and related).
-  - `content_type` / `html_response` / `scraper_eligibility`.
-  - `sst`: `{ node_count, degraded, segment_stats }` when SST ran; `segment_stats` is also emitted at the top level when present.
-  - `articles_count` and `admission_drops` when the response is HTML (Cleanup drop-reason counts).
-  - `blocked_surface` when an interstitial signature is detected.
-  - `xhr_capture` when the inspect strategy is `botasaurus` (`count`, redacted `sample_endpoints`, `candidate_articles`).
-- **next_step:** Follow the envelope. Typical values: `scrape_url` when `alternate_feeds` is present or when no articles were found; `capture_config` when articles were found and there are no alternates.
+### `recon`
 
-### `capture_config`
+Curation verdict and `native_feed` preference (`BUILD` / `DEFER` / `DROP`).
 
-Analyzes a target URL and derives a reusable YAML draft (`items` selector + `enhance: true`). Same serializer as CLI `html2rss capture`. Full schema options live in resource `html2rss://schema`.
+- **Parameters:** `url` (required); `strategy` (default `auto`)
 
-- **Parameters:**
-  - `url` _(string, required)_: Source page URL.
-  - `strategy` _(string, optional)_: Request strategy (`auto`, `faraday`, `botasaurus`). Default: `auto`.
-  - `items_selector` _(string, optional)_: Optional CSS selector hint for items.
-- **Return value:** Envelope with `payload.yaml` (string keys; same serializer as CLI `html2rss capture`). Treat as a draft: catalog feeds still need `directory.topics` and explicit channel `title`/`url`. Strive to keep `enhance: true`.
-- **payload:** Also `articles_count`, `channel_title`, `has_selectors`, `requested_strategy`, and when present `segment_strategy`, `selected_strategy`, `admission_drops`. Follow `next_step` (`validate_config` or `inspect_url`).
+### `capture`
 
-### `validate_config`
+Derive a reusable YAML draft (`payload.yaml`). Same serializer as CLI `html2rss capture`. Catalog feeds still need `directory.topics` and explicit channel `title` / `url`.
 
-Validates a feed configuration against the official `html2rss` JSON schema (`html2rss://schema`) and runtime constraints.
+- **Parameters:** `url` (required); `strategy`; optional `items_selector`
+- Typical `next_step`: `test` or `inspect`
 
-- **Parameters** (exactly one of `config` or `yaml`):
-  - `config` _(object, optional)_: Feed configuration object.
-  - `yaml` _(string, optional)_: Feed configuration YAML (same form as CLI capture / catalog files).
-- **Return value:** Envelope with empty `payload` on success (`next_step`: `apply_config`).
-- **Error handling:** Returns `isError: true` with `payload.errors` if schema validation fails, or `next_step: validate_config` if both/neither argument is provided.
+### `validate`
 
-### `apply_config`
+Schema-only check against `html2rss://schema`. Exactly one of `config` or `yaml`.
 
-Executes a validated feed configuration against a page and returns RSS 2.0 XML. This is the ship gate: `isError` when the feed has zero items.
+- Success `next_step` is usually `test`
 
-- **Parameters:**
-  - `url` _(string, required)_: Source page URL (populates `channel.url` if omitted from config).
-  - `config` _(object, optional)_: Feed configuration object (XOR `yaml`).
-  - `yaml` _(string, optional)_: Feed configuration YAML (XOR `config`).
-- **Return value:** Envelope with `payload.rss` (RSS 2.0 XML) and `payload.item_count` from the rendered RSS `items` (not a regex over the XML).
-- **Error handling:** `isError: true` when the scrape produced no items (`payload.item_count: 0`, `next_step: inspect_url`), or on unhandled exceptions.
+### `test`
 
-## Resources Reference
+Schema validation plus live extraction (`min_items`, optional `strict_quality`, `compare_enhance`).
 
-The MCP server exposes reference data under the `html2rss://` URI scheme:
+- Success `next_step` is `apply`
+- Payload includes sample items, timing, and `quality_report` when present
 
-| URI                         | MIME Type          | Description                                                                                                              |
-| :-------------------------- | :----------------- | :----------------------------------------------------------------------------------------------------------------------- |
-| **`html2rss://schema`**     | `application/json` | The complete JSON Schema for `html2rss` feed configurations, including selector rules, extractors, and request controls. |
-| **`html2rss://extractors`** | `application/json` | Alphabetical list of all registered extractor names (`attribute`, `html`, `href`, `text`, `static`, etc.).               |
-| **`html2rss://strategies`** | `application/json` | Published MCP request strategies (`auto`, `faraday`, `botasaurus`). Does not list `local_file`.                          |
-| **`html2rss://runtime`**    | `application/json` | Boolean `botasaurus_configured` from process env. Never includes the scraper URL.                                        |
+### `apply`
 
-`validate_config` / `apply_config` reject `strategy: local_file` and `request.local_file_path`. Use CLI `--input` for fixtures.
+Ship gate: build RSS from a config. Required `url` plus exactly one of `config` or `yaml`.
 
-## Prompts Reference
+- **Payload:** `rss`, `item_count`
+- `isError` when zero items
 
-The server publishes guided prompt workflows for AI assistants:
+### Batch trio
 
-### `scrape-webpage`
+| Tool            | Job                                    |
+| --------------- | -------------------------------------- |
+| `batch_scrape`  | Parallel scrape with per-URL isolation |
+| `batch_inspect` | Parallel inspect                       |
+| `batch_recon`   | Parallel recon                         |
 
-One `scrape_url` call with `strategy: auto` (AutoFallback already hops). Call `inspect_url` only if the result is weak or you need recon.
+## Resources
 
-- **Arguments:**
-  - `url` _(string, required)_: Target URL to scrape.
+| URI                     | Description                                                                                                        |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `html2rss://schema`     | Feed config JSON Schema                                                                                            |
+| `html2rss://extractors` | Extractor names                                                                                                    |
+| `html2rss://strategies` | `auto`, `faraday`, `botasaurus` (not `local_file`)                                                                 |
+| `html2rss://runtime`    | `version`, `mcp_contract_version`, `catalog_fingerprint`, `tools`, `botasaurus_configured` — never the scraper URL |
 
-### `capture-feed-config`
+`validate` / `apply` reject `strategy: local_file` and `request.local_file_path`. Use CLI `--input` for fixtures.
 
-Four-step workflow for a durable feed config:
+## Prompts
 
-1. Call `capture_config` — YAML is `payload.yaml`. Check `payload.articles_count` and `has_selectors`. Strive `enhance: true`.
-2. If weak or you need recon, call `inspect_url` (`auto` uses Faraday; pin `botasaurus` for browser rendering).
-3. Call `validate_config` with `yaml` (or `config`) — must not be `isError`.
-4. Call `apply_config` — `isError` if zero items. Confirm `payload.item_count` before shipping.
+| Name                  | Flow                                                                           |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `scrape-webpage`      | One `scrape` call; `inspect` only if weak                                      |
+| `capture-feed-config` | `capture` → `test` → `apply` (catalog rewrite when targeting html2rss-configs) |
 
-If the destination is html2rss-configs, rewrite the draft for `directory.topics` and explicit channel `title`/`url`.
+## Client setup
 
-- **Arguments:**
-  - `url` _(string, required)_: Target URL to analyze.
+See [AI Agent Workflows](/ruby-gem/guides/ai-agent-workflows/) for Cursor / Claude Desktop `mcp.json` examples and the `html2rss-config` skill.
diff --git a/src/content/docs/ruby-gem/reference/strategy.mdx b/src/content/docs/ruby-gem/reference/strategy.mdx
index 4a58c9d0..52ed0072 100644
--- a/src/content/docs/ruby-gem/reference/strategy.mdx
+++ b/src/content/docs/ruby-gem/reference/strategy.mdx
@@ -114,9 +114,9 @@ Example scrape-API payload shape:
 <Code
   code={`
   BOTASAURUS_SCRAPER_URL="http://localhost:4010" \\
-  html2rss auto https://example.com/updates --strategy botasaurus
+  html2rss scrape https://example.com/updates --strategy botasaurus
   BOTASAURUS_SCRAPER_URL="http://localhost:4010" \\
-  html2rss feed my_config.yml --strategy botasaurus
+  html2rss apply my_config.yml --strategy botasaurus
 `}
   lang="bash"
 />
diff --git a/src/content/docs/ruby-gem/tutorials/your-first-feed.mdx b/src/content/docs/ruby-gem/tutorials/your-first-feed.mdx
index e3021dfe..bf47b0ab 100644
--- a/src/content/docs/ruby-gem/tutorials/your-first-feed.mdx
+++ b/src/content/docs/ruby-gem/tutorials/your-first-feed.mdx
@@ -15,7 +15,7 @@ The easiest way to create a feed is with the `auto` command. It requires no conf
 
 Open your terminal and run this command:
 
-<Code code={`html2rss auto https://unmatchedstyle.com/`} lang="bash" />
+<Code code={`html2rss scrape https://unmatchedstyle.com/`} lang="bash" />
 
 `html2rss` will analyze the website and generate an RSS feed for you, printing it directly to the console. This is a great way to see if `html2rss` can automatically handle your target website.
 
@@ -52,7 +52,7 @@ Let's create a feed for a simple article listing page.
 
 3.  **Run the `feed` command:**
 
-<Code code={`html2rss feed example.yml`} lang="bash" />
+<Code code={`html2rss apply example.yml`} lang="bash" />
 
 This configuration tells `html2rss`:
 
diff --git a/src/content/docs/troubleshooting/troubleshooting.mdx b/src/content/docs/troubleshooting/troubleshooting.mdx
index 6da865bb..6f30a58c 100644
--- a/src/content/docs/troubleshooting/troubleshooting.mdx
+++ b/src/content/docs/troubleshooting/troubleshooting.mdx
@@ -30,7 +30,7 @@ The `auto` flow is URL-surface sensitive.
   - search result pages
   - client-rendered app-shell entrypoints
 
-If extraction quality is poor, switch to a more specific listing/update URL before tuning selectors. `html2rss auto URL --explain` prints admission drop counts on stderr so you can see why items were dropped (junk titles, non-article destinations) without mixing JSON into the feed.
+If extraction quality is poor, switch to a more specific listing/update URL before tuning selectors. `html2rss scrape URL --explain` prints admission drop counts on stderr so you can see why items were dropped (junk titles, non-article destinations) without mixing JSON into the feed.
 
 ### Empty Feeds
 
@@ -86,7 +86,7 @@ Then run with:
 <Code
   code={`
   BOTASAURUS_SCRAPER_URL="http://localhost:4010" \\
-  html2rss auto https://example.com/updates --strategy botasaurus
+  html2rss scrape https://example.com/updates --strategy botasaurus
 `}
   lang="bash"
 />
diff --git a/src/content/docs/web-application/concepts.mdx b/src/content/docs/web-application/concepts.mdx
new file mode 100644
index 00000000..a0e36e4f
--- /dev/null
+++ b/src/content/docs/web-application/concepts.mdx
@@ -0,0 +1,48 @@
+---
+title: "How It Works"
+description: "Auto-source, Botasaurus, access tokens, and how html2rss-web relates to the gem and Feed Directory."
+sidebar:
+  order: 2
+---
+
+## Auto-source (URL to RSS)
+
+With `AUTO_SOURCE_ENABLED=true`, the web UI accepts a page URL and builds a feed without a hand-written YAML config. The engine prefers listing-like pages (newsrooms, changelogs, releases, category archives). Homepages and search pages are weaker inputs.
+
+Production Docker Compose defaults `AUTO_SOURCE_ENABLED` to `true`. Non-compose hosts still follow the Ruby flag: enabled in development/test unless overridden, off in production unless you set the env var.
+
+## Botasaurus companion
+
+`html2rss-web` talks to `botasaurus-scrape-api` at `BOTASAURUS_SCRAPER_URL` (Compose sets `http://botasaurus:4010`). That service renders JavaScript-heavy pages when Faraday alone is not enough. Auto-source uses Faraday first, then Botasaurus when configured.
+
+## Three tokens (plain English)
+
+| Variable                | Role                                                                                            |
+| ----------------------- | ----------------------------------------------------------------------------------------------- |
+| `HTML2RSS_SECRET_KEY`   | Encrypts session cookies and signed state (≥ 32 characters). Required in production.            |
+| `HTML2RSS_ACCESS_TOKEN` | What users paste into the UI to create feeds (≥ 16 characters). Required by production Compose. |
+| `HEALTH_CHECK_TOKEN`    | Optional. Gates authenticated `GET /api/v1/health` when you want a private probe.               |
+
+Generate secrets with `openssl rand -hex 32`. Demo quickstart hard-codes `CHANGE_ME_ADMIN_TOKEN` as the access token — replace it before any shared or public host.
+
+Optional: `SENTRY_DSN` (web) and `BOTASAURUS_SENTRY_DSN` (scraper) for error reporting. They are separate projects; leave both unset until you want monitoring.
+
+## HTTP vs HTTPS
+
+Plain HTTP works on localhost and LAN. The app sets HSTS and CSP `upgrade-insecure-requests` only when the request is HTTPS (including when a reverse proxy sends `X-Forwarded-Proto: https`). Put Caddy, Nginx, or Traefik in front for public TLS.
+
+## Ecosystem map
+
+| Piece                | Job                                                                                |
+| -------------------- | ---------------------------------------------------------------------------------- |
+| **html2rss-web**     | Web UI, API, feed URLs, Feed Directory catalog API                                 |
+| **html2rss** (gem)   | Extraction engine, CLI (`scrape` / `apply`), MCP server                            |
+| **html2rss-configs** | Curated YAML under `lib/html2rss/configs/`; signed registry bundles                |
+| **Feed Directory**   | Browse UI on the docs site; loads entries from your instance `GET /api/v1/configs` |
+
+## Where next
+
+- [Getting Started](/getting-started/) — first feed
+- [Deployment](/web-application/deployment/) — production
+- [MCP Server](/ruby-gem/reference/mcp-server/) — agent tools
+- [Advanced Feeds](/creating-custom-feeds/) — custom YAML
diff --git a/src/content/docs/web-application/deployment.mdx b/src/content/docs/web-application/deployment.mdx
index 1024ee09..d32230dd 100644
--- a/src/content/docs/web-application/deployment.mdx
+++ b/src/content/docs/web-application/deployment.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Deployment & Production"
-description: "Deploy html2rss-web with Docker, keep first success small, then add production pieces after the local token-gated flow works."
+description: "Deploy html2rss-web with Docker Compose, real tokens, LAN HTTP or HTTPS reverse proxy."
 sidebar:
   order: 3
 ---
@@ -9,104 +9,101 @@ import { Code } from "@astrojs/starlight/components";
 
 import DockerComposeSnippet from "../../../components/docs/DockerComposeSnippet.astro";
 
-html2rss-web ships on Docker Hub. Start with the [Getting Started guide](/web-application/getting-started/), which uses [`docker-compose.quickstart.yml`](https://github.com/html2rss/html2rss-web/blob/main/docker-compose.quickstart.yml). Make sure the one-file demo works first, then add the production pieces below.
+Start from a working [Getting Started](/getting-started/) demo, then switch to production Compose with your own secrets.
 
-The examples use `html2rss/web:1`, the recommended major-version tag. Pin an exact release if your deployment process requires it.
+Use image tag `html2rss/web:1` (or pin an exact release). Production Compose lives in [`html2rss-web/docker-compose.yml`](https://github.com/html2rss/html2rss-web/blob/main/docker-compose.yml) with [`.env.example`](https://github.com/html2rss/html2rss-web/blob/main/.env.example).
 
-## Choose Your Production Scope First
+## Production compose (recommended)
 
-There are two materially different deployment modes:
+1. Download and copy env:
 
-- **Automatic generation enabled:** primary self-hosted workflow, requires `AUTO_SOURCE_ENABLED=true` and `HTML2RSS_ACCESS_TOKEN`
-- **Included feeds fallback only:** lower-maintenance path when the Feed Directory already covers your needs
+<Code
+  code={`
+  curl -O https://raw.githubusercontent.com/html2rss/html2rss-web/main/docker-compose.yml
+  curl -O https://raw.githubusercontent.com/html2rss/html2rss-web/main/.env.example
+  cp .env.example .env
+`}
+  lang="bash"
+/>
 
-If you do not need page-URL generation yet, keep `AUTO_SOURCE_ENABLED` off and ship the fallback mode only.
+2. Set secrets in `.env`:
 
-## Prepare for Production
+<Code
+  code={`
+  openssl rand -hex 32  # HTML2RSS_SECRET_KEY
+  openssl rand -hex 32  # HTML2RSS_ACCESS_TOKEN
+`}
+  lang="bash"
+/>
+
+| Variable                               | Required       | Notes                                              |
+| -------------------------------------- | -------------- | -------------------------------------------------- |
+| `HTML2RSS_SECRET_KEY`                  | Yes            | ≥ 32 characters                                    |
+| `HTML2RSS_ACCESS_TOKEN`                | Yes            | ≥ 16 characters; paste into the UI                 |
+| `AUTO_SOURCE_ENABLED`                  | Default `true` | Keep `true` for URL-to-RSS                         |
+| `HEALTH_CHECK_TOKEN`                   | No             | Only if you use authenticated `GET /api/v1/health` |
+| `SENTRY_DSN` / `BOTASAURUS_SENTRY_DSN` | No             | Separate web vs scraper Sentry projects            |
 
-Before exposing html2rss-web, ensure:
+3. Start:
 
-- Your domain (for example `yourdomain.com`) resolves to the host running Docker
-- Inbound TCP ports 80 and 443 reach the host (check firewalls and cloud security groups)
-- You are ready to watch the first deployment logs for certificate issuance
-- You have a value ready for `HTML2RSS_SECRET_KEY`
-- You have a value ready for `HTML2RSS_ACCESS_TOKEN`
+<Code code={`docker compose up -d`} lang="bash" />
 
-If you plan to enable automatic feed generation, also prepare:
+Web listens on host port **4000** (`4000:4000`). Botasaurus stays on `127.0.0.1:4010` inside the published mapping from Compose. Open `http://localhost:4000/` or `http://<LAN_IP>:4000/` and paste `HTML2RSS_ACCESS_TOKEN`.
 
-- a clear way to give users the same `HTML2RSS_ACCESS_TOKEN` your instance expects
-- optional advanced-rendering infrastructure only if harder sites later prove they need it
+Port `4000` on all interfaces is intentional for LAN access. Protect the instance with a strong access token; do not expose an unauthenticated demo token on a shared network.
 
-### Why a Reverse Proxy?
+## LAN / Tailscale (plain HTTP)
 
-A reverse proxy terminates public HTTPS traffic and forwards requests to html2rss-web on your private Docker network.
+No reverse proxy required. The app does **not** force HTTPS upgrades on plain HTTP, so LAN IPs keep working. HSTS and CSP `upgrade-insecure-requests` apply only on HTTPS requests.
 
-### Option A: Caddy (Automatic HTTPS)
+## Public HTTPS (Caddy example)
 
-Caddy handles certificates and redirects.
+Terminate TLS in front of the app and forward to port 4000:
 
 <DockerComposeSnippet variant="productionCaddy" />
 
-Create a `.env` file beside your compose file:
+Example `.env` beside Compose:
 
 <Code
   code={`
   CADDY_HOST=yourdomain.com
   HTML2RSS_SECRET_KEY=<openssl rand -hex 32>
-  HTML2RSS_ACCESS_TOKEN=<strong access token>
-  # Optional only if you want authenticated GET /api/v1/health
-  # HEALTH_CHECK_TOKEN=<strong health token>
+  HTML2RSS_ACCESS_TOKEN=<openssl rand -hex 32>
+  # Optional:
+  # HEALTH_CHECK_TOKEN=
+  # SENTRY_DSN=
+  # BOTASAURUS_SENTRY_DSN=
 `}
   lang="dotenv"
 />
 
-Before starting the stack:
-
-- Set `CADDY_HOST` for your domain.
-- Generate `HTML2RSS_SECRET_KEY` with `openssl rand -hex 32`.
-- Set a strong `HTML2RSS_ACCESS_TOKEN`. This is the token users paste into the web UI.
-- Leave `HEALTH_CHECK_TOKEN` unset unless you intentionally use authenticated `GET /api/v1/health`.
-- Leave `BUILD_TAG` and `GIT_SHA` unset unless you intentionally override image metadata in logs.
-- Adjust optional knobs such as `AUTO_SOURCE_ENABLED` and `SENTRY_DSN` as needed; refer to the [environment reference](/web-application/reference/env-variables/) for details.
-
-After `docker compose up -d`, run `docker compose logs caddy --tail 20`; look for `certificate obtained`.
+After `docker compose up -d`, check `docker compose logs caddy --tail 20` for certificate issuance.
 
-Re-test after DNS changes with [SSL Labs](https://www.ssllabs.com/ssltest/).
+## Custom feeds mount
 
-## Secure Your Instance
+Auto-source is the default. To add curated YAML feeds, bind-mount `feeds.yml` (see [Advanced Feeds](/creating-custom-feeds/)):
 
-Harden the application before inviting other users:
-
-- Set a strong `HTML2RSS_ACCESS_TOKEN` and rotate it when needed
-- Prefer environment files (`.env`) stored outside version control for secrets
-- Keep token sharing/distribution outside public docs and outside version control
-- Give trusted users the same current `HTML2RSS_ACCESS_TOKEN` through your normal operator channel
-- If you use authenticated `GET /api/v1/health`, set a strong `HEALTH_CHECK_TOKEN`; do not leave `CHANGE_ME_HEALTH_CHECK_TOKEN` anywhere in production
-
-<DockerComposeSnippet variant="secure" />
-
-Store these variables in a `.env` file and reference it with `env_file:` as demonstrated in the Caddy example.
-
-## Operate & Monitor
-
-Keep the instance healthy once it is in production:
-
-- Review `docker compose logs` regularly for feed errors or certificate renewals
-- Pull newer images for the Docker tag you selected on your update cadence
-- Right-size CPU and memory to avoid starvation when parsing large feeds
-- Use `GET /api/v1/health/ready` for standard readiness checks
-- Add authenticated `GET /api/v1/health` only when your operator tooling needs it
-
-### Resource Guardrails
+<Code
+  code={`
+  volumes:
+    - type: bind
+      source: ./config/feeds.yml
+      target: /app/config/feeds.yml
+      read_only: true
+`}
+  lang="yaml"
+/>
 
-<DockerComposeSnippet variant="resourceGuardrails" />
+## Operate
 
-Adjust limits to match host capacity. Increase memory for large feeds.
+- `GET /api/v1/health/ready` for readiness
+- Authenticated `GET /api/v1/health` only when `HEALTH_CHECK_TOKEN` is set
+- OpenAPI at `/openapi.yaml` on the running instance
+- [Monitoring reference](/web-application/reference/monitoring/) for Sentry and probes
+- [Environment variables](/web-application/reference/env-variables/) for the full table
 
-## Share & Support
+## Next
 
-- Test different feed sources before inviting external users
-- Publish `/openapi.yaml` from the running instance if you expect agents or integrations to call the API directly
-- Add your instance to the [community wiki](https://github.com/html2rss/html2rss-web/wiki/Instances) if you want it listed publicly
-- Visit the [troubleshooting guide](/troubleshooting/troubleshooting/) or join the [community discussions](https://github.com/orgs/html2rss/discussions) when you need help
-- Ready to contribute fixes or docs? See the [contributing guide](/get-involved/contributing/)
+- [Feed Directory](/web-application/guides/use-the-feed-directory/)
+- [How It Works](/web-application/concepts/)
+- [Troubleshooting](/troubleshooting/troubleshooting/)
diff --git a/src/content/docs/web-application/getting-started.mdx b/src/content/docs/web-application/getting-started.mdx
deleted file mode 100644
index b047870a..00000000
--- a/src/content/docs/web-application/getting-started.mdx
+++ /dev/null
@@ -1,107 +0,0 @@
----
-title: "Getting Started"
-description: "Run html2rss-web locally with Docker, use the demo token once, and then move to the real deployment setup."
-sidebar:
-  order: 2
----
-
-import { Code } from "@astrojs/starlight/components";
-
-import MinimalDockerCompose from "../../../components/docs/MinimalDockerCompose.astro";
-
-Run `html2rss-web` locally with Docker, confirm one generated feed works, then move to the real operator setup.
-
-## What You Will Have When This Works
-
-After this guide, you should have:
-
-- `html2rss-web` running at `http://localhost:4000`
-- successful feed generated from your own page URL
-- a clear handoff from the demo stack to the real deployment setup
-- a generated feed URL from your own page URL
-- a clear fallback path when direct generation is not the right fit
-
-## What You'll Need
-
-- **Docker**
-- **About 10 minutes**
-
-If you do not already have Docker, [install it first](https://docs.docker.com/get-started/).
-
-## Step 1: Create a Folder
-
-<Code
-  code={`
-  mkdir html2rss-web && \
-  cd html2rss-web
-`}
-  lang="bash"
-/>
-
-## Step 2: Copy `docker-compose.yml`
-
-Use the quickstart stack from [`docker-compose.quickstart.yml`](https://github.com/html2rss/html2rss-web/blob/main/docker-compose.quickstart.yml).
-
-Create your local `docker-compose.yml` from that file:
-
-<MinimalDockerCompose />
-
-This first-run stack keeps the path narrow:
-
-- `html2rss-web`
-- `botasaurus`
-- automatic feed generation enabled
-- `RACK_ENV=development`
-
-## Step 3: Start the Stack
-
-<Code code={`docker compose up -d`} lang="bash" />
-
-## First Success Check
-
-1. Open `http://localhost:4000`
-2. Paste your own page URL into `Page URL`
-3. Start with a listing, newsroom, changelog, releases, or updates page instead of a homepage
-4. Enter `CHANGE_ME_ADMIN_TOKEN` when prompted
-5. Open the generated feed URL
-
-If that works, the demo stack is behaving correctly.
-
-## Move To Real Setup Next
-
-After the demo works, continue with the real operator setup.
-
-1. **[Deployment & Production](/web-application/deployment/)**: convert the demo into a stable, production-ready setup
-2. **[Use automatic feed generation](/web-application/guides/use-automatic-feed-generation/)**: understand the page-URL flow in more detail
-3. **[Monitoring](/web-application/reference/monitoring/)**: choose readiness or authenticated health checks for your deployment
-
-## If The First URL Is Poor
-
-Automatic mode works best when the input URL is already a page that lists updates.
-
-Higher-success inputs:
-
-- newsroom or press pages
-- changelog or release pages
-- category, tag, archive, or listing pages
-
-Lower-success inputs:
-
-- generic homepages
-- search pages
-- entry pages
-
-When output quality is poor, change the input URL first before assuming setup is broken.
-
-## Fallback Path
-
-If the site you want is already in the feed directory, or you want a fast sample before creating another generated feed, use the feed directory on your own instance.
-
-- [Use the Feed Directory](/web-application/guides/use-the-feed-directory/)
-- [Feed Directory](/feed-directory/)
-
-## Next Steps
-
-1. **[Deployment & Production](/web-application/deployment/)**: convert the demo into a real operator setup
-2. **[Create Custom Feeds](/creating-custom-feeds/)**: write your own config when you need reviewable extraction rules
-3. **[Need help?](/troubleshooting/troubleshooting/)**: troubleshoot startup and extraction problems
diff --git a/src/content/docs/web-application/index.mdx b/src/content/docs/web-application/index.mdx
index 1d8cb2bf..31b1ab1a 100644
--- a/src/content/docs/web-application/index.mdx
+++ b/src/content/docs/web-application/index.mdx
@@ -1,48 +1,32 @@
 ---
 title: "Web Application"
-description: "html2rss-web is the self-hosted web interface and feed server for page-URL generation, fallback feeds, and custom configs."
+description: "html2rss-web is the self-hosted UI and feed server for URL-to-RSS, Feed Directory, and custom configs."
 sidebar:
   label: "Overview"
   order: 1
 ---
 
-`html2rss-web` is the recommended way to get started. Run the quickstart demo first, create one generated feed, then move to the real deployment setup when you want stable URLs of generated feeds, production secrets, explicit tokens, or monitoring.
+`html2rss-web` is the recommended product surface. Run the [Getting Started](/getting-started/) demo, create one feed from a page URL, then move to [Deployment](/web-application/deployment/) for production secrets and stable hosting.
 
-## Get Started
+## What you get
 
-Start with **[Getting Started](/web-application/getting-started/)** to:
+- Web UI for page-URL auto-source
+- Access-controlled create API (`HTML2RSS_ACCESS_TOKEN`)
+- Feed Directory catalog from your instance (`GET /api/v1/configs`)
+- Optional custom YAML via `feeds.yml` mount
+- OpenAPI at `/openapi.yaml`
 
-- run your own local instance
-- use the demo token
-- open a generated feed from your own instance
+The extraction engine is the [`html2rss`](https://github.com/html2rss/html2rss) gem.
 
-## What The Web App Gives You
+## Flow
 
-- **Web interface:** direct feed creation from page URLs
-- **Access-controlled generation:** `POST /api/v1/feeds` expects the token configured on your instance
-- **Included Feed Directory:** packaged fallback feeds you can use immediately from your own deployment
-- **Config-based extension path:** move to custom feeds when you need reviewable rules
-- **Caching and HTTP handling:** shipped as part of the deployment
-- **Generated API contract:** OpenAPI is published at `/openapi.yaml`
+1. [Getting Started](/getting-started/) — local Docker
+2. [Deployment](/web-application/deployment/) — production
+3. [Advanced Feeds](/creating-custom-feeds/) — YAML escape hatch
 
-The scraping and feed-building engine is provided by the Ruby gem [`html2rss`](https://github.com/html2rss/html2rss).
+## Guides
 
-## Recommended Flow
-
-1.  **[Getting Started](/web-application/getting-started/)**: run the app locally in 10 minutes
-2.  **[Deployment & Production](/web-application/deployment/)**: move to a stable, production-ready setup
-3.  **[Create Custom Feeds](/creating-custom-feeds/)**: build stable extraction rules when needed
-
-## Feature Guides
-
-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 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
-
-- **OpenAPI:** `/openapi.yaml` on your instance, or [`public/openapi.yaml`](https://github.com/html2rss/html2rss-web/blob/main/public/openapi.yaml) in the repo
-- **API metadata:** `/api/v1`
-- **Config schema for the core gem:** [`html2rss-config.schema.json`](https://github.com/html2rss/html2rss/blob/master/schema/html2rss-config.schema.json)
+- [Use automatic feed generation](/web-application/guides/use-automatic-feed-generation/)
+- [Use the Feed Directory](/web-application/guides/use-the-feed-directory/)
+- [How It Works](/web-application/concepts/)
+- [Monitoring](/web-application/reference/monitoring/)