diff --git a/astro.config.mjs b/astro.config.mjs
index fb9174bf..2cb7056f 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -248,17 +248,17 @@ export default defineConfig({
       },
       sidebar: [
         {
-          label: "Home",
-          link: "/",
-        },
-        {
-          label: "Common Use Cases",
-          link: "/common-use-cases",
+          label: "Getting Started",
+          link: "/getting-started",
         },
         {
           label: "Feed Directory",
           link: "/feed-directory/",
         },
+        {
+          label: "Create Custom Feeds",
+          link: "/creating-custom-feeds",
+        },
         {
           label: "Web Application",
           collapsed: true,
@@ -299,10 +299,6 @@ export default defineConfig({
             },
           ],
         },
-        {
-          label: "Write Your Own Feed Configs",
-          link: "/creating-custom-feeds",
-        },
         {
           label: "About",
           link: "/about",
@@ -312,11 +308,6 @@ export default defineConfig({
           collapsed: false,
           autogenerate: { directory: "get-involved" },
         },
-        {
-          label: "Troubleshooting",
-          collapsed: true,
-          autogenerate: { directory: "troubleshooting" },
-        },
       ],
       defaultLocale: "root",
       locales: {
diff --git a/src/components/docs/AutoGenerationOptional.astro b/src/components/docs/AutoGenerationOptional.astro
new file mode 100644
index 00000000..35039fc9
--- /dev/null
+++ b/src/components/docs/AutoGenerationOptional.astro
@@ -0,0 +1,8 @@
+---
+import { Aside } from "@astrojs/starlight/components";
+---
+
+<Aside type="note" title="Automatic generation is optional">
+  The "paste a website URL and generate a feed" workflow is not enabled by default. If you want it, continue
+  with <a href="/web-application/how-to/use-automatic-feed-generation/">Use automatic feed generation</a>.
+</Aside>
diff --git a/src/components/docs/MinimalDockerCompose.astro b/src/components/docs/MinimalDockerCompose.astro
new file mode 100644
index 00000000..ebc0001c
--- /dev/null
+++ b/src/components/docs/MinimalDockerCompose.astro
@@ -0,0 +1,33 @@
+---
+import Code from "astro/components/Code.astro";
+
+const code = `services:
+  html2rss-web:
+    image: gilcreator/html2rss-web
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:3000:3000"
+    volumes:
+      - type: bind
+        source: ./feeds.yml
+        target: /app/config/feeds.yml
+        read_only: true
+    environment:
+      RACK_ENV: production
+      HEALTH_CHECK_USERNAME: health
+      HEALTH_CHECK_PASSWORD: CHANGE_THIS_PASSWORD_BEFORE_USE
+      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:3001
+      BROWSERLESS_IO_API_TOKEN: 6R0W53R135510
+
+  browserless:
+    image: "ghcr.io/browserless/chromium"
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:3001:3001"
+    environment:
+      PORT: 3001
+      CONCURRENT: 10
+      TOKEN: 6R0W53R135510`;
+---
+
+<Code code={code} lang="yaml" />
diff --git a/src/content/docs/creating-custom-feeds.mdx b/src/content/docs/creating-custom-feeds.mdx
index 57d94b71..3814969c 100644
--- a/src/content/docs/creating-custom-feeds.mdx
+++ b/src/content/docs/creating-custom-feeds.mdx
@@ -19,6 +19,12 @@ When auto-sourcing isn't enough, you can write your own configuration files to c
   releases](/web-application/reference/versioning-and-releases/) for details.
 </Aside>
 
+<Aside type="tip" title="Use this guide when you need more control">
+  Start with included feeds first. If your site is not covered, try [automatic feed
+  generation](/web-application/how-to/use-automatic-feed-generation/) next. Reach for a custom config when you
+  need a stable, reviewable setup or the generated feed misses important content.
+</Aside>
+
 ---
 
 ## When to Use Custom Configs
@@ -35,6 +41,20 @@ When auto-sourcing isn't enough, you can write your own configuration files to c
 
 ---
 
+## Recommended Workflow
+
+1. **Inspect the live page** in your browser developer tools
+2. **Write the smallest useful config** that extracts items, titles, and links
+3. **Validate the config** with `html2rss validate your-config.yml`
+4. **Render the feed** with `html2rss feed your-config.yml`
+5. **Add it to `html2rss-web`** so you can use it through your normal instance
+6. **Escalate to `browserless`** if the content is rendered by JavaScript
+
+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
 
 A config file is a simple "recipe" that tells html2rss:
@@ -82,7 +102,7 @@ This says: "Find each article, get the title from the h2 anchor, and get the lin
 
 ## Your First Config
 
-**Step 1:** Look at the website you want to create a feed for. Right-click → "View Page Source" to see the HTML structure.
+**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:
 
@@ -140,6 +160,12 @@ html2rss supports many configuration options:
 
 4. **Check the output:** Make sure all items have titles, links, and descriptions
 
+## 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
@@ -177,6 +203,7 @@ html2rss supports many configuration options:
 **For Beginners:**
 
 - **[Browse the Feed Directory](/feed-directory/)** - See real-world examples
+- **[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!
 
@@ -184,4 +211,5 @@ html2rss supports many configuration options:
 
 - **[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 `browserless`
 - **[Learn advanced features](/ruby-gem/how-to/advanced-features/)** - Take your configs to the next level
diff --git a/src/content/docs/getting-started.mdx b/src/content/docs/getting-started.mdx
index c5a2fcb9..f08de5ba 100644
--- a/src/content/docs/getting-started.mdx
+++ b/src/content/docs/getting-started.mdx
@@ -5,181 +5,21 @@ sidebar:
   order: 1
 ---
 
-Ready to get RSS feeds from any website? Choose your path below. No technical knowledge required!
+This page points to the main onboarding flow.
 
-## Quick Start Options
+## Start Here
 
-### Option 1: Use a Public Instance (Easiest)
+If you want the recommended path, go to [Run html2rss-web with Docker](/web-application/getting-started).
 
-**Try html2rss right now:**
+That guide is the canonical setup flow for:
 
-1. **Go to a public html2rss instance** (see our [community wiki](https://github.com/html2rss/html2rss-web/wiki/Instances) for available instances)
-2. **Browse existing feeds** or create auto-sourced feeds from any URL
-3. **Copy the RSS URL** and add it to your feed reader
-4. **Done!** You're now following the website in your RSS reader
+- running `html2rss-web` locally
+- confirming your first successful feed
+- deciding when to use included feeds, automatic generation, or custom configs
 
-**Perfect for:** Testing, quick feeds, or if you don't want to install anything.
+## Quick Shortcuts
 
-### Option 2: Install Your Own Instance
-
-**For full control and custom feeds:**
-
-1. **Follow the installation steps below**
-2. **Create auto-sourced feeds** from any website
-3. **Add custom configs** when you need more control
-4. **Run your own RSS feed server** with stable HTTPS URLs
-
-**Perfect for:** Power users, custom configurations, or when you need reliability.
-
----
-
-## Installation Guide
-
-This guide will help you set up your own copy of html2rss-web on your computer. Don't worry - we'll walk you through every step!
-
-### What You'll Need
-
-- **Docker** - A tool that makes installation simple (like an app store for server software)
-- **About 10 minutes** - The whole process is quick and automated
-
-**Don't have Docker?** [Install it first](https://docs.docker.com/get-started/) - it's free and works on all major operating systems.
-
-### Step 1: Create a Folder
-
-Create a new folder on your computer to store html2rss-web files:
-
-**Create a new folder** on your computer and name it "html2rss-web". You can do this through your file manager or terminal:
-
-```bash
-mkdir html2rss-web
-cd html2rss-web
-```
-
-### Step 2: Create the Configuration File
-
-Create a file called `docker-compose.yml` in your new folder. This file tells Docker how to set up html2rss-web with all the features you need.
-
-**How to create the file:**
-
-- **Using a text editor:** Create a new file and save it as `docker-compose.yml`
-- **Using terminal:** Use any text editor to create the file
-
-```yaml
-services:
-  html2rss-web:
-    image: gilcreator/html2rss-web:latest
-    restart: unless-stopped
-    ports:
-      - "127.0.0.1:3000:3000"
-    volumes:
-      - type: bind
-        source: ./feeds.yml
-        target: /app/config/feeds.yml
-        read_only: true
-    environment:
-      RACK_ENV: production
-      HEALTH_CHECK_USERNAME: health
-      HEALTH_CHECK_PASSWORD: CHANGE_THIS_PASSWORD_BEFORE_USE
-      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:3001
-      BROWSERLESS_IO_API_TOKEN: 6R0W53R135510
-
-  watchtower:
-    image: containrrr/watchtower
-    restart: unless-stopped
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
-      - "~/.docker/config.json:/config.json"
-    command: --cleanup --interval 7200
-
-  browserless:
-    image: "ghcr.io/browserless/chromium"
-    restart: unless-stopped
-    ports:
-      - "127.0.0.1:3001:3001"
-    environment:
-      PORT: 3001
-      CONCURRENT: 10
-      TOKEN: 6R0W53R135510
-```
-
-### Step 3: Download the Feed List
-
-html2rss-web needs a list of feeds to work with. Download our pre-made list:
-
-**Download the feeds.yml file:**
-
-- **Using your browser:** Right-click [this link](https://raw.githubusercontent.com/html2rss/html2rss-web/master/config/feeds.yml) → Save As → Name it "feeds.yml" → Save in your html2rss-web folder
-- **Using terminal:** Open Terminal in your html2rss-web folder and run:
-
-```bash
-curl https://raw.githubusercontent.com/html2rss/html2rss-web/master/config/feeds.yml -o feeds.yml
-```
-
-### Step 4: Start html2rss-web
-
-Now start html2rss-web:
-
-**Start html2rss-web:**
-
-Open a terminal in your html2rss-web folder and run:
-
-```bash
-docker compose up -d
-```
-
-**That's it!** 🎉 html2rss-web is now running.
-
-**To verify it's working:**
-
-1. Open your web browser
-2. Go to `http://localhost:3000`
-3. You should see the html2rss-web interface with a list of available feeds
-
-**If you see the interface, congratulations!** You've successfully set up html2rss-web.
-
----
-
-## Using Your Instance
-
-### Browse Existing Feeds
-
-Your html2rss-web instance comes with pre-configured feeds for popular websites. Browse the list and copy any RSS URL to your feed reader.
-
-### Create Auto-Sourced Feeds
-
-**Want a feed for a website that's not in the list?**
-
-1. **Go to your html2rss-web interface** (http://localhost:3000)
-2. **Enter any website URL** you want to create a feed for
-3. **Click "Generate Feed"** - html2rss will automatically analyze the page
-4. **Copy the RSS URL** and add it to your feed reader
-
-**This works for most websites** without any configuration needed!
-
-### Add Custom Feeds
-
-**Need more control?** You can add custom feed configurations to your `feeds.yml` file. See our [Creating Custom Feeds](/creating-custom-feeds) guide for details.
-
----
-
-## Troubleshooting
-
-**Common issues when getting started:**
-
-- **Instance won't start?** Check that Docker is running and the port isn't already in use
-- **Can't access the interface?** Make sure you're going to `http://localhost:3000`
-- **Auto-sourced feed not working?** Some websites need custom configuration - see our [troubleshooting guide](/troubleshooting/troubleshooting)
-- **Need help?** Join our [community discussions](https://github.com/orgs/html2rss/discussions)
-
----
-
-## Next Steps
-
-**Ready for more?**
-
-- **[Browse the Feed Directory](/feed-directory/)** - See real-world examples
-- **[Create Custom Feeds](/creating-custom-feeds)** - Learn to write your own configurations
-- **[Troubleshooting Guide](/troubleshooting/troubleshooting)** - Solve common issues
-- **[Join the Community](https://github.com/orgs/html2rss/discussions)** - Get help and share ideas
-
-**🎉 Congratulations!** You now have your own RSS feed server running.
+- **[Run html2rss-web with Docker](/web-application/getting-started)** - Recommended first step
+- **[Browse working feed examples](/feed-directory/)** - See what success looks like
+- **[Create Custom Feeds](/creating-custom-feeds)** - Write configs when you need more control
+- **[Troubleshooting Guide](/troubleshooting/troubleshooting)** - Fix startup or extraction problems
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
index adfe355d..349bccae 100644
--- a/src/content/docs/index.mdx
+++ b/src/content/docs/index.mdx
@@ -3,11 +3,21 @@ title: "Turn Any Website Into an RSS Feed - Never Miss Updates Again"
 description: "Create RSS feeds from any website - no coding required. Turn blogs, news sites, and forums into RSS feeds you can follow in your favorite reader. Free, open source, and easy to use."
 ---
 
-Ever wished you could follow your favorite websites like a social media feed? The html2rss project makes it possible by creating RSS feeds for any website - even ones that don't offer them.
+Run `html2rss-web` with Docker, start with included feeds, and add custom configs only when you need more control.
 
 ## 🚀 Get Started in 30 Seconds
 
-**Try it now:** [Browse Ready-Made Feeds](/feed-directory/) | [Get Started](/getting-started)
+**Start here:** [Run html2rss-web with Docker](/web-application/getting-started) | [Browse working feed examples](/feed-directory/)
+
+Need more control? [Write a custom feed config](/creating-custom-feeds)
+
+---
+
+## How It Works
+
+1. **Run your own local instance** with Docker
+2. **Use included feeds or add your own** website targets
+3. **Subscribe from your RSS reader** using stable feed URLs
 
 ---
 
@@ -34,30 +44,30 @@ Ever wished you could follow your favorite websites like a social media feed? Th
 
 ## What is html2rss?
 
-html2rss is a user-friendly tool that turns any website into an RSS feed. Think of it as a translator that converts website content into a format your feed reader can understand.
+html2rss is a toolkit for turning websites into RSS feeds. Think of it as a translator that converts website content into a format your feed reader can understand.
 
-**Two ways to use html2rss:**
+**Most people should start with the web application:**
 
-- **🌐 Web App** - RSS feed server with auto-sourcing. Perfect for everyone
-- **⚙️ Ruby Gem** - The core engine that powers everything
+- **🌐 html2rss-web** - The easiest way to run your own feed server with Docker
+- **⚙️ html2rss gem** - The underlying engine, CLI, and developer interface
 
 ---
 
 ## 🎯 Choose Your Path
 
-### I'm Getting Started with RSS
+### I want a working instance first
 
-1. **[Get Started](/getting-started)** - Complete guide to using html2rss
-2. **[Browse Examples](/feed-directory/)** - See 100+ ready-made feeds
-3. **[Learn More](/about/)** - Understand how it all works
+1. **[Run html2rss-web with Docker](/web-application/getting-started)** - Recommended starting path
+2. **[Browse working feed examples](/feed-directory/)** - See what success looks like
+3. **[Use the included configs](/web-application/how-to/use-included-configs/)** - Start with ready-made feeds
 
-### I Want to Create Custom Feeds
+### I need more control
 
-1. **[Creating Custom Feeds](/creating-custom-feeds)** - Learn to write your own configs
-2. **[Ruby Gem Reference](/ruby-gem/)** - Full technical documentation
-3. **[Share Your Configs](/get-involved/contributing/)** - Help the community
+1. **[Creating Custom Feeds](/creating-custom-feeds)** - Write and test your own configs
+2. **[Selectors Reference](/ruby-gem/reference/selectors/)** - Learn the matching rules
+3. **[Strategy Reference](/ruby-gem/reference/strategy/)** - Use `browserless` for JS-heavy sites
 
-### I'm a Developer
+### I'm building or integrating
 
 1. **[Ruby Gem Reference](/ruby-gem/)** - Full API documentation
 2. **[Advanced Features](/ruby-gem/how-to/advanced-features/)** - Custom HTTP requests, etc.
@@ -80,6 +90,12 @@ html2rss is a user-friendly tool that turns any website into an RSS feed. Think
 
 ## 🔧 Common Issues?
 
+**Start with Docker, not a public instance.** That gives you the most reliable path and the newest integrated behavior.
+
 **Feed not working?** Check our [troubleshooting guide](/troubleshooting/troubleshooting)
+
+**Need custom control?** Continue to [Creating Custom Feeds](/creating-custom-feeds)
+
 **Need help?** Join our [community discussions](https://github.com/orgs/html2rss/discussions)
+
 **Found a bug?** [Report it on GitHub](https://github.com/html2rss/html2rss/issues)
diff --git a/src/content/docs/web-application/getting-started.mdx b/src/content/docs/web-application/getting-started.mdx
index 8205de55..12ac3428 100644
--- a/src/content/docs/web-application/getting-started.mdx
+++ b/src/content/docs/web-application/getting-started.mdx
@@ -5,36 +5,22 @@ sidebar:
   order: 2
 ---
 
-Ready to create RSS feeds? Choose your path below. No technical knowledge required!
+import AutoGenerationOptional from "../../../components/docs/AutoGenerationOptional.astro";
+import MinimalDockerCompose from "../../../components/docs/MinimalDockerCompose.astro";
 
-## Quick Start Options
+Ready to create RSS feeds? Run `html2rss-web` locally with Docker, verify the interface, then use included feeds before you move on to auto-generation or custom configs.
 
-### Option 1: Use a Public Instance (Easiest)
+## What You Will Have When This Works
 
-**Try html2rss-web right now:**
+After this guide, you should have:
 
-1. **Go to a public html2rss-web instance** (see our [community wiki](https://github.com/html2rss/html2rss-web/wiki/Instances) for available instances)
-2. **Enter a website URL** you want to create a feed for
-3. **Click "Generate Feed"** and copy the RSS URL
-4. **Add to your feed reader** (any RSS reader app)
-
-**Perfect for:** Testing, quick feeds, or if you don't want to install anything.
-
-### Option 2: Install Your Own Instance
-
-**For full control and custom feeds:**
-
-1. **Follow the installation steps below**
-2. **Create custom feeds** for any website
-3. **Run your own instance** with all features
-
-**Perfect for:** Power users, custom configurations, or when you need reliability.
-
----
+- `html2rss-web` running at `http://localhost:3000`
+- a feed list loaded from `feeds.yml`
+- a clear path to either automatic generation or custom YAML configs
 
 ## Installation Guide
 
-This guide will help you set up your own copy of html2rss-web on your computer. Don't worry - we'll walk you through every step!
+This guide walks you through a local Docker setup that gives you the most reliable starting point.
 
 ### What You'll Need
 
@@ -54,52 +40,13 @@ mkdir html2rss-web
 cd html2rss-web
 ```
 
-### Step 2: Create the Configuration File
-
-Create a file called `docker-compose.yml` in your new folder. This file tells Docker how to set up html2rss-web with all the features you need.
-
-**How to create the file:**
-
-- **Using a text editor:** Create a new file and save it as `docker-compose.yml`
-- **Using terminal:** Use any text editor to create the file
-
-```yaml
-services:
-  html2rss-web:
-    image: gilcreator/html2rss-web
-    restart: unless-stopped
-    ports:
-      - "127.0.0.1:3000:3000"
-    volumes:
-      - type: bind
-        source: ./feeds.yml
-        target: /app/config/feeds.yml
-        read_only: true
-    environment:
-      RACK_ENV: production
-      HEALTH_CHECK_USERNAME: health
-      HEALTH_CHECK_PASSWORD: please-set-YOUR-OWN-veeeeeery-l0ng-aNd-h4rd-to-gue55-Passw0rd!
-      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:3001
-      BROWSERLESS_IO_API_TOKEN: 6R0W53R135510
-
-  watchtower:
-    image: containrrr/watchtower
-    restart: unless-stopped
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
-      - "~/.docker/config.json:/config.json"
-    command: --cleanup --interval 7200
-
-  browserless:
-    image: "ghcr.io/browserless/chromium"
-    restart: unless-stopped
-    ports:
-      - "127.0.0.1:3001:3001"
-    environment:
-      PORT: 3001
-      CONCURRENT: 10
-      TOKEN: 6R0W53R135510
-```
+### Step 2: Create a Minimal Configuration File
+
+Create a file called `docker-compose.yml` in your new folder. Start with the minimal local stack:
+
+<MinimalDockerCompose />
+
+Add update automation such as Watchtower later, after the first run works.
 
 ### Step 3: Download the Feed List
 
@@ -116,32 +63,37 @@ curl https://raw.githubusercontent.com/html2rss/html2rss-web/master/config/feeds
 
 ### Step 4: Start html2rss-web
 
-Now start html2rss-web:
-
-**Start html2rss-web:**
-
 Open a terminal in your html2rss-web folder and run:
 
 ```bash
 docker compose up -d
 ```
 
-**That's it!** 🎉 html2rss-web is now running.
+## First Success Check
 
-**To verify it's working:**
+At this point, `html2rss-web` should be running.
 
 1. Open your web browser
 2. Go to `http://localhost:3000`
 3. You should see the html2rss-web interface with a list of available feeds
 
-**If you see the interface, congratulations!** You've successfully set up html2rss-web.
+If you see the interface, the setup worked.
+
+## What To Do First
+
+1. Open one included feed from the list
+2. Copy the RSS URL into your reader
+3. Confirm you can subscribe successfully
+
+That proves the web app, feed config file, and request pipeline are all working together.
+
+<AutoGenerationOptional />
 
 ---
 
 ## Next Steps
 
-**Ready to create feeds?**
-
-- **Browse existing feeds** - Check out what's already available
-- **Create your first feed** - Follow our [How-To Guides](/web-application/how-to/) to make custom feeds
-- **Need help?** Check our [troubleshooting guide](/troubleshooting/troubleshooting) if something doesn't work
+1. **[Use the included configs](/web-application/how-to/use-included-configs/)** - Start with working feeds
+2. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)** - Enable the quick-generate workflow
+3. **[Create Custom Feeds](/creating-custom-feeds)** - Write and test your own configs
+4. **[Need help?](/troubleshooting/troubleshooting)** - Troubleshoot startup and extraction problems
diff --git a/src/content/docs/web-application/how-to/use-automatic-feed-generation.mdx b/src/content/docs/web-application/how-to/use-automatic-feed-generation.mdx
index 020126d8..e19c379e 100644
--- a/src/content/docs/web-application/how-to/use-automatic-feed-generation.mdx
+++ b/src/content/docs/web-application/how-to/use-automatic-feed-generation.mdx
@@ -34,3 +34,14 @@ docker compose up -d
 4. **Get your RSS feed!** html2rss-web will create a feed automatically
 
 **That's it!** No configuration files needed - html2rss-web does all the work for you.
+
+## When to Stop and Switch
+
+Automatic feed generation is a fast first try, not the final answer for every site.
+
+Move on to [Creating Custom Feeds](/creating-custom-feeds) when:
+
+- the generated feed misses important fields
+- the wrong items are extracted
+- the site needs a stable, reviewable setup
+- you need `browserless` or more precise selectors to make the feed reliable
diff --git a/src/content/docs/web-application/how-to/use-included-configs.mdx b/src/content/docs/web-application/how-to/use-included-configs.mdx
index 1155acac..0d28df6a 100644
--- a/src/content/docs/web-application/how-to/use-included-configs.mdx
+++ b/src/content/docs/web-application/how-to/use-included-configs.mdx
@@ -11,9 +11,29 @@ html2rss-web comes with hundreds of ready-made feeds for popular websites! No co
 2. **Copy the URL** (it looks like `domainname.tld/whatever.rss`)
 3. **Add it to your feed reader** - paste the URL and you're done!
 
+## What Success Looks Like
+
+You are successful when:
+
+- the feed URL opens from your own `html2rss-web` instance
+- your feed reader accepts the URL
+- new items appear without you editing any YAML
+
+If that works, keep using included configs for that site. It is the lowest-maintenance path.
+
 ## Example
 
 If you see a config file named `example.com/news.yml`, you can access it at:
 `http://localhost:3000/example.com/news.rss`
 
 Just replace `localhost:3000` with your html2rss-web address.
+
+## When to Move On
+
+Use a custom config when:
+
+- the site you want is not in the directory
+- the included feed misses fields you care about
+- you need a more specific page, section, or output format
+
+Next step: [Create Custom Feeds](/creating-custom-feeds)
diff --git a/src/content/docs/web-application/index.mdx b/src/content/docs/web-application/index.mdx
index dfe62b6c..c5826bb7 100644
--- a/src/content/docs/web-application/index.mdx
+++ b/src/content/docs/web-application/index.mdx
@@ -6,17 +6,29 @@ sidebar:
   order: 1
 ---
 
-This web application scrapes websites to build and deliver RSS 2.0 feeds. It is a powerful tool for creating custom RSS feeds.
+`html2rss-web` is the recommended way to get started. Run it locally with Docker, use included feeds first, and move to automatic generation or custom configs only when you need more control.
 
 ## Get Started
 
-Our **[Getting Started guide](/web-application/getting-started)** covers essential first steps, from understanding the application to installing your own instance.
+Start with **[Getting Started](/web-application/getting-started)** to:
+
+- run your own local instance
+- confirm a first successful feed
+- choose the right next step for your site
 
 ## Key Features
 
-- **Stable URLs:** Provides stable URLs for automatically sourced feeds.
-- **Custom Feeds:** Create custom feeds.
-- **Feed Directory:** Includes many [feeds](https://github.com/html2rss/html2rss-configs) out of the box.
-- **Caching:** Handles request caching and sets HTTP headers.
+- **Stable URLs:** Provides stable URLs for feeds served from your own instance
+- **Included Feeds:** Start with many working configs out of the box
+- **Automatic Generation:** Try new sites quickly when the feature is enabled
+- **Custom Feeds:** Create and refine your own configs when you need more control
+- **Caching:** Handles request caching and sets HTTP headers
 
 The functionality of scraping websites and building the RSS feeds is provided by the Ruby gem [`html2rss`](https://github.com/html2rss/html2rss).
+
+## Recommended Flow
+
+1. **[Getting Started](/web-application/getting-started)** - Run the app locally
+2. **[Use the included configs](/web-application/how-to/use-included-configs/)** - Confirm a working feed first
+3. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)** - Try unsupported sites quickly
+4. **[Create Custom Feeds](/creating-custom-feeds)** - Build a stable custom setup when needed